Field
Updated: Sunday, 07 August 2016
Custom fields.
Table of Content
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