Outlast

Defining your own data fields

Data type definitions

You can define virtually any type of data field in Outlast Framework simply by creating a new class and a few supporting files.

More docs to come, but have a look at /system/plugins/_jquery/fields/*.field.php files. You can duplicate these to make your own.

[For docs, use samples from text.field.php, manytomany.field.php, map.field.php. Available methods are documented in the zajDb and zajField classes.]

Default input editors

All data fields can have HTML templates associated with them which define how the data field is displayed for editing in the admin panel when using the {% input %} tag.

The default input editor for each data type is defined in its zajfield_* class as the edit_template constant. For example, zajfield_manytomany is defined in /system/plugins/_jquery/fields/manytomany.field.php and it has the following field editor definition:

const edit_template = 'field/manytomany.field.html';

This means that when you use an {% input %} with a field that is of datatype manytomany, it will display the template field/manytomany.field.html from any of your system, plugin, or local view folders.

As always, you can override the default inputs by creating the field/manytomany.field.html in your local /app/view/ folder. Keep in mind however that this will override all manytomany fields in your entire project. If you want a custom editor for any particular input, see Custom input editors below.

Input editor variables

When you create a new input editor template, you will need to access the data and parameters associated with the field. These variables are all loaded when the {% input %} tag is generated (see zajlib_tag_mozajik::tag_input).

Input editor templates are regular OFW Template files, so they work exactly like any other view template file. You have access to all variables, tags, and filters as elsewhere.

In addition, you’ll have access to the following special field variables:

{{field.name}} – the name of the current field; this should be used as the input name
{{field.uid}} – a 13 character long completely unique id, generated uniquely each time the field html is compiled (so after template cache reset it is regenerated)
{{field.type}} – the data type of the model field
{{field.class_name}} – a lowercase version of the current object’s class name
{{field.field_name}} – a lowercase version of the current field’s name within the model object
{{field.label}} – the localized label of the current field (not fully supported yet)
{{field.placeholder}} – the localized placeholder of the current field (not fully supported yet)
{{field.value}} – the current value of the field. This will be in whatever dataformat the field returns, so be careful to handle each possible case (such as undefined or empty states).
{{field.choices}} – a list of available choices (this is available for relationship fields such as onetomany, manytoone, onetoone, and manytomany fields)
{{field.options}} – a key/value pair of the options that were set for this field. These are typically set by magic methods and may be different for each field type.
{{field.locale}} – when you generate translation-ready fields with {% inputlocale %} (see docs), this will be set to the locale of the field. When there is no locale (when a regular {% input %} is being generated) it will be false.
{{field.id}} – the #id of the current field. This will be the same each time the field is generated. This is deprecated!

Some custom fields may require more variables and data to display properly. In this case you can use the zajField::__onInputGeneration() magic method to insert code before the {% input %} is generated. The relationship field types use this magic method to define their {{field.choices}}.

Custom input editors

As described above, each data field has a default editor html associated with it. You can override this globally by creating your own field/*.field.html file. However, you can also override the data field editor for any specific input. To do this, simply use the {% input %} tag’s third parameter:

{% input product.related product.data.related 'field/my_custom_related_products_editor.field.html' %}

As a matter of best practice you can (but are not required to) follow these guidelines:

All field editors should be named *.field.html. This is so they can easily be found with a quick file-name search.
All field editors should be placed in a field subfolder within the view folder.
Place all field editors in the same plugin where you use them. So if you use a custom field editor in the shop plugin, place its html in /plugins/shop/view/field/my_field_editor_name.field.html. This is to ensure that it is always available when needed.

Default input filters

Much like input editor templates, you can also define filter templates. These input fields will allow developers to easily generate list filtering options using the {% filter %} tag. (Note that input filter templates are not to be confused with template variable filters – two entirely different concepts.)

The method for creating input filters is similar to input editors. You’ll need to specify the filter template in the field definition php:

const filter_template = 'field/manytomany.filter.html';

Next, create the filter html using the input editor variables detailed above. See /system/plugins/jquery/view/field/*.filter.html for examples.

You can use the __onFilterGeneration($param_array, &$source) magic method to add additional features to the process. See manytoone.field.php as an example.

Check out the documentation on filtering for more details.

Filter input variables

Filter input templates will receive the same {{field.*}} variables that input editor templates also have access to.

Some things to note:

The variable {{field.value}} will refer to the current value of the filter as set in the GET (or POST) query string.
The magic method __onFilterGeneration will be called instead of __onInputGeneration.

Custom input filters

You can use custom input filters the same way you use custom input filters. When using the {% inputfilter %} tag (see docs) simply specify your custom filter html as the second parameter. Naming convention dictates that these files be placed in /field/*.filter.html, relative to your view folder:

{% inputfilter user.name 'field/user_name.filter.html' %}