Field – Mecha CMS

Table of Content

Properties
Types
Scopes

Properties

All possible properties for a custom field are described as follow…

return array(
    'key' => array(
        'title' => 'Field Title', // default is empty `string`
        'type' => 'text', // default is `summary`
        'scope' => 'page', // default is unset
        'placeholder' => 'Lorem ipsum dolor sit amet…', // default is empty `string`
        'value' => "", // default is empty `string`
        'description' => "", // default is empty `string`
        'attributes' => array(
            'pattern' => '\\d+', // default is `null`
            'required' => true // default is unset
        ),
        'parser' => function($input) { // default is unset
            return Text::parse($input, '->text');
        }
    )
);

Property	Description
`key`	Key of the field for `name` attribute in the HTML form.
`title`	Title of the field.
`type`	Type of the field.
`scope`	Scope of the field.
`placeholder`	Placeholder as a quick hint for the field.
`value`	Default value or values for the field.
`description`	Description data as a complete hint for the field.
`attributes`	Custom HTML attributes for the field.
`parser`	Callback function to sanitize user input values.

If defined, pattern and required attributes in the attributes property will be used as input validator using native HTML5 features. But then, it will also get extra supports from the backend side to perform double validation in the submitted data, so you can’t use things like HTML element inspector to remove the validator attributes from the frontend side.

Related: Dynamic Fields

Types

text
summary
boolean
option
options
file
composer
editor
hidden

Text

A text input element.

return array(
    'author' => array(
        'title' => 'Post Author',
        'type' => 'text'
    )
);

<label class="grid-group grid-group-text">
  <span class="grid span-2 form-label">Post Author</span>
  <span class="grid span-4">
    <input name="fields[author]" class="input-block" type="text">
  </span>
</label>

Summary

A plain text area element. This is the default custom field type.

return array(
    'snippet' => array(
        'title' => 'Post Snippet',
        'type' => 'summary',
        'placeholder' => 'Some description about this post (optional)'
    )
);

<div class="grid-group grid-group-summary">
  <label class="grid span-2 form-label">Post Snippet</label>
  <div class="grid span-4">
    <textarea name="fields[snippet]" class="textarea-block" placeholder="Some description about this post (optional)"></textarea>
  </div>
</div>

Boolean

Optional field with static value. Empty and undefined value value will be evaluated to 1.

'foo bar' → <input type="checkbox" value="foo bar">
'true' → <input type="checkbox" value="true">
"" → <input type="checkbox" value="1">

return array(
    'show' => array(
        'title' => 'Show Author',
        'type' => 'boolean',
        'description' => 'Show author of this post?'
    )
);

<div class="grid-group grid-group-boolean">
  <span class="grid span-2"></span>
  <div class="grid span-4">
    <div>
      <label>
        <input name="fields[show]" type="checkbox" value="1">
        <span>Show Author</span>
      </label>
      <span class="text-info help" title="Show author of this post?">
        <i class="fa fa-question-circle"></i>
      </span>
    </div>
  </div>
</div>

Option

Optional field with alternative values. The value value can also be set with a YAML–like string format:

red: Red
green: Green
blue: Blue

Color:
  red: Red
  green: Green
  blue: Blue
Size:
  small: Small
  medium: Medium
  large: Large

If defined, the placeholder value will becomes the first option in select box with an empty value. It won’t be stored in the page file when selected because empty values will always be removed. Just like boolean field type but with alternative values of the true state.

return array(
    'category' => array(
        'title' => 'Post Category',
        'type' => 'option',
        'placeholder' => 'Select a category…',
        'value' => array(
            'red' => 'Red',
            'green' => 'Green',
            'blue' => 'Blue'
        )
    )
);

<label class="grid-group grid-group-option">
  <span class="grid span-2 form-label">Post Category</span>
  <span class="grid span-4">
    <select name="fields[category]" class="select-block">
      <option value="">Select a category…</option>
      <option value="red">Red</option>
      <option value="green">Green</option>
      <option value="blue">Blue</option>
    </select>
  </span>
</label>

Options

Added since version 1.2.7.

Optional field with multiple alternative values. Users can select more than one option. The value value can also be set with a YAML–like string format:

red: Red
green: Green
blue: Blue

Color:
  red: Red
  green: Green
  blue: Blue
Size:
  small: Small
  medium: Medium
  large: Large

return array(
    'tags' => array(
        'title' => 'Post Tags',
        'type' => 'options',
        'value' => array(
            'red' => 'Red',
            'green' => 'Green',
            'blue' => 'Blue'
        )
    )
);

<div class="grid-group grid-group-options">
  <span class="grid span-2 form-label">Post Tags</span>
  <div class="grid span-4">
    <div>
      <div>
        <label>
          <input name="fields[tags][]" type="checkbox" value="red">
          <span>Red</span>
        </label>
      </div>
      <div>
        <label>
          <input name="fields[tags][]" type="checkbox" value="green">
          <span>Green</span>
        </label>
      </div>
      <div>
        <label>
          <input name="fields[tags][]" type="checkbox" value="blue">
          <span>Blue</span>
        </label>
      </div>
    </div>
  </div>
</div>

File

Attachment files. The value value will be used as a filter to limit the files that can be uploaded based on its file extension. If not defined, then the allowed file extensions will depend on File::$config['file_extension_allow'] value.

return array(
    'doc' => array(
        'title' => 'Post Document',
        'type' => 'file',
        'value' => 'pdf,zip'
    )
);

<div class="grid-group grid-group-file">
  <span class="grid span-2 form-label">Post Document</span>
  <span class="grid span-4">
    <input name="doc" type="file">
    <br>
    <small>
      <strong>Accepted:</strong> <code>*.pdf</code>, <code>*.zip</code>
    </small>
  </span>
</div>

Composer

A smart text area element with a toolbar, purposed to be used as a sentence editor.

return array(
    'content' => array(
        'title' => 'Post Content',
        'type' => 'composer'
    )
);

<div class="grid-group grid-group-composer">
  <label class="grid span-2 form-label">Post Content</label>
  <div class="grid span-4">
    <textarea name="fields[content]" class="textarea-block MTE code"></textarea>
  </div>
</div>

Editor

A smart text area element without toolbar, purposed to be used as a source code editor.

return array(
    'css' => array(
        'title' => 'Post Style',
        'type' => 'editor'
    )
);

<div class="grid-group grid-group-editor">
  <label class="grid span-2 form-label">Post Style</label>
  <div class="grid span-4">
    <textarea name="fields[css]" class="textarea-block code"></textarea>
  </div>
</div>

Hidden

A hidden input element. Used as a replacement for required and read only custom fields. In the Field editor, it is disabled by default.

return array(
    'update' => array(
        'title' => 'Post Update',
        'type' => 'hidden',
        'value' => $_SERVER['REQUEST_TIME']
    )
);

<input name="fields[update]" type="hidden" value="1464783886">

Scopes

Limit your custom fields scope to make it becomes available only on certain post types. By default, it can be article, page or comment, or a combination of them, separated by commas:

article
article,page,comment