Class AdminPageFramework_FieldType

The base class for the users to create their custom field types.

When a framework user implements a custom field type into his/her work, this class may be extended to create a field definition class.

Creating a Custom Field Type

1. Decide a unique field type slug that is going to be set in field definition arrays consisting of alphabets and underscores, such as my_custom_field_type. For example, the autocomplete custom field type uses the slug autocomplete and the date&time picker custom field type uses date_time. This sulg is the one the user sets in field definition arrays to the type argument.
2. Define a PHP class that extends the AdminPageFramework_FieldType abstract class.
   1. Extend the AdminPageFramework_FieldType class.

      class MyCustomFieldType extends AdminPageFramework_FieldType {
          // your code that defines the field type goes here
      }

   2. Set the field type slug decided in the above step such as my_custom_field_type to the $aFieldTypeSlugs property.

          public $aFieldTypeSlugs = array( 'my_custom_field_type', );
      

   3. Define the default key-pairs of the field arguments. When you define a field, you create a definition array like this.

          array(
              'field_id'              => 'my_field_id',
              'type'                  => 'my_custom_field_type',
              'your_cusotm_key'       => ...,
              'another_cusotm_key'    => ...,
          )
      

      You can accept custom arguments by defining the key-value pairs in the $aDefaultKeys property array.

      Example

            protected $aDefaultKeys = array(
              'label_min_width'   => 80,
              'attributes'        => array(
                  'size'          => 10,
                  'maxlength'     => 400,
              ),
              'label'             => array(
                  'url'       => 'URL',
                  'title'     => 'Title',
                  // Add more as you need
              ),
          );
      

   4. (optional) Write additional code of procedural subroutines in the setUp() method. The setUp() method is performed when the field type definition is parsed by the framework.

      Example

      protected function setUp() {
          wp_enqueue_script( 'jquery-ui-datepicker' );
      }
      

   5. (optional) Add assets like scripts and styles with getEnqueuingScripts(), getEnqueuingStyles().

      Example

       protected function getEnqueuingScripts() {
           return array(
               array( 'src' => dirname( __FILE__ ) . '/js/datetimepicker-option-handler.js', ),
           );
       }
       protected function getEnqueuingStyles() {
           return array(
               dirname( __FILE__ ) . '/css/jquery-ui-1.10.3.min.css',
           );
       }
      

   6. (optional) Add inline scripts and styles with getScripts(), getStyles().

      Example

      protected function getScripts() {
          return "
              jQuery( document ).ready( function(){
              console.log( 'debugging: loaded' );
              });
          " . PHP_EOL;
      }
      protected function getStyles() {
          return ".admin-page-framework-input-label-container.my_custom_field_type { padding-right: 2em;' }";
      }
      

   7. Construct the output HTML structure with the passed $aField field definition array in the getField() method.

      Example

          protected function getField( $aField ) {
              return
                  $aField['before_label']
                  . $aField['before_input']
                  . "<div class='repeatable-field-buttons'></div>"    // the repeatable field buttons
                  . $this->_getInputs( $aField )
                  . $aField['after_input']
                  . $aField['after_label'];
          }
              private function _getInputs( $aField ) {
                  $_aOutput = array();
                  foreach( ( array ) $aField['label'] as $_sSlug => $_sLabel ) {
                      $_aAttributes = isset( $aField['attributes'][ $_sSlug ] ) && is_array( $aField['attributes'][ $_sSlug ] )
                          ? $aField['attributes'][ $_sSlug ] + $aField['attributes']
                          : $aField['attributes'];
                      $_aAttributes = array(
                          'tyle'  => 'text',
                          'name'  => "{$_aAttributes['name']}[{$_sSlug}]",
                          'id'    => "{$aField['input_id']}_{$_sSlug}",
                          'value' => isset( $aField['attributes']['value'][ $_sSlug ] ) ? $aField['attributes']['value'][ $_sSlug ] : '',
                      ) + $_aAttributes;
                      $_aOutput[] =
                          "<div class='admin-page-framework-input-label-container my_custom_field_type'>"
                              . "<label for='{$aField['input_id']}_{$_sSlug}'>"
                                  . "<span class='admin-page-framework-input-label-string' style='min-width:" . $aField['label_min_width'] . "px;'>"
                                      . $_sLabel
                                  . "</span>" . PHP_EOL
                                  . "<input " . $this->getAttributes( $_aAttributes ) . " />"
                              . "</label>"
                          . "</div>";
                  }
                  return implode( PHP_EOL, $_aOutput );
              }
      

3. Instantiate the field type class by passing the instantiated class name of the framework class. See the below section to see how to include a custom field type.

Including a Custom Field Type

1. Include the definition file and instantiate the class in the script (plugin,theme etc.).

    // pass the PHP class name that extends the framework's class to the first parameter.
   new MyCustomFieldType( 'MY_FRAMEWORK_CLASS_NAME' );
   

2. Define fields with the custom field type with the addSettingFields() method in the framework extending class.

   $this->addSettingFields(
        array(
            'field_id'     =>  'my_field_id',
            'section_id'   =>  'my_section_id',
            'type'         =>  'my_custom_field_type',    // <-- here put the field type slug
            '...'          => '...'
        )
   );