PyroCMS

Basics

To get started, create a folder and a file with your chosen slug. For this example, we are going to use the Email field type, which has a slug called "email". Create a file with the prefix "field", then the slug, then the .php extension.

email/field.email.php

You can put this file in addons/shared_addons/field_types or addons/[site-slug]/field_types and streams will recognize and use it automatically.

Each field type has a basic structure with data that needs to be there for it work correctly. Here is an example of a very basic field type:

class Field_email 
{
 public $field_type_slug = 'email';

 public $db_col_type = 'varchar';

 /**
  * Output form input
  *
  * @access public
  * @param array
  * @return string
  */
 public function form_output($data)
 {
    $options['name']   = $data['form_slug'];
    $options['id']   = $data['form_slug'];
    $options['value']  = $data['value'];

    return form_input($options);
 }
}

As you can see, we have a class name of Field_yourslug. Inside we have some basic class variables:

Variable Description
field_type_slug The field slug (the same one you are using for the class name and folder/file names).
db_col_type Type of MySQL column that PyroStreams should create to store the data for this field. Any type can be used, but the most common are varchar, text, and int.

Aside from the class variables, one method is necessary – form_output. This method is called when building the form and allows you to include logic and customized input for your fields. In this case, we are just returning a basic input. You can find more about this method on the Methods page.

PyroStreams uses CodeIgniter's Form Helper when creating inputs, and it is available in third party field types as well.

Tapping Into CodeIgniter

If you want to use the CodeIgniter super object in your field types, you can access it via the CI class variable. This is added to your field type automatically so you do not need to use the get_instance() syntax.

$this->CI->load->library('Typography');

Optional Class Properties

You can also add some other class properties to change how PyroStreams interacts with the field type.

Variable Value Description
extra_validation string Validation for required, unique, etc. is added automatically with PyroStreams. However, you might need to add some extra validation from time to time. You can do that by adding a class variable named extra_validation.
input_is_file bool Some field types work with files (such as the image field type). When creating a field type that uses a file, make sure to add a class variable called input_is_file and set it to TRUE.
alt_process bool Sometimes you don't want to actually have a column created for your field type (such as in the case of having a related rows table). Setting this to true will tell PyroStreams to ignore the column in the stream when it needs to because there is none.
version number The current version number of the field type.
author array An array with two keys: name (name of the author) and url URL to the author's website.

Field Parameters

Each field can have custom or prefab field parameters. For instance, many fields, such as the text field take advantage of the max_length field parameter. However, you can make them yourself to give your users added functionality.

Custom fields (preset and ones you make) are activated by putting a class variable into your field type class named custom_parameters.

public $custom_parameters = array('max_length', 'my_custom_one'); 

Preset Field Parameters

Parameter Description
max_length Collects data on the max length of a field.
default_value Collects data on the default value of a field. This is only a simple text input, so if you need a special default input, you should create your own.

Creating Custom Field Parameters

To create custom field parameters, you need to

  1. add them to the custom_parameters class variable (detailed above)
  2. specify a parameter name
  3. specify a parameter input.

To specify the label name of the parameter, just add a new language key in the format of:

$lang['streams:{your_field_type_slug}.{your_param_slug}'] = 'Label';

So if you have a parameter default_setting for your Setting field type, your language variable would look like this:

$lang['streams:setting.default_setting'] = 'Default Setting';

To specify an input, create a method in your field class with the prefix param_

public function param_my_custom_one($value)
{
  // Return the form input
}

It takes one parameter – a string that is the current value of the custom field parameter.

Adding Instructions to Your Field Parameter

If you want to take it one step further, you can return an array (instead of a string) of the input and the instructions for that input:

public function param_choice_data($value = null)
{
  return array(
      'input'     => form_textarea('choice_data', $value),
      'instructions'  => $this->CI->lang->line('streams.choice.instructions')
    );
}

Languages in Field Types

Streams fully supports language files in field types. The canonical language for PyroStreams is English, so we'll use English in the following examples.

Inside your field type folder, you'll need a folder called language. Inside this, you can add the different language folders. In this case, English.

PyroStreams will recognize and load a language file with the same slug as your field type. So if we are creating a language file for the Email field type, the structure would look like this:

email
    - language
        - english
            --- email_lang.php

Inside the email_lang.php file, you'll need an array like this:

$lang['streams:email.name'] = 'Email';

Each language item should follow the convention streams.yourslug.lang_slug. The only one that is required is streams.yourslug.name which will be used as the name of the field type.

Custom Parameter Titles

If you are using Custom Parameters for your field type, you need to put the names of your fields in this language file. Simply use the slugs of your parameters as the language slugs. They will automatically be used.

In your field type:

public $custom_parameters = array('choice_data', 'choice_type');

In your language file:

$lang['streams:choice.choice_data'] = 'Choice Data';
$lang['streams:choice.choice_type'] = 'Choice Type';

Validation

Validation takes several forms for PyroCMS field types.

  • Assignment-added validation. This takes the form of required and unique, which are determined by the field assignment.
  • Standard field type validation. This is the standard validation rules in the actual field type (see below).
  • Custom field type validation. This is the custom validation functionality in the valiation() function (see below).

With these three ways to incorporate validation, you have all the tools you need to validate pretty much anything!

Standard Field Type Validation

Standard field type validation is added as a class variable named extra_validation:

public $extra_validation = 'numeric|integer'; 

Any of CodeIgniter's Form Validation rules can be used here, separated by a pipe character.

Custom Field Type Validation

Sometimes, the standard validation rules aren't enough for your input, and you need some custom validation logic. To add some custom validation logic, just a public validate function to your field type. It takes three parameters:

Parameter Description
value The value submitted to the form for your field.
mode Either 'new' or 'edit', depending on if the form is editing an entry or creating a new one.
field The field instance object.

If the data fails validation, you can return an error string. A return of null or true indicates that your validation has passed the test. Here's a simple example:

public function validate($value, $mode, $field)
{
    if ($value != 'the value we want')
    {
        return 'The '.$field->field_name.' field needs to be the value we want!';
    }

    return true;
}

Remember, you can still access all the $_POST variables, so if you need to grab the row ID, you can use the row_edit_id from the phone data.

$this->CI->input->post('row_edit_id');

Working With File Uploads

Some field types work with files (such as the image field type). When creating a field type that uses a file, make sure to add a class variable called input_is_file and set it to true.

public $input_is_file = true;

This will make sure things like required fields works correctly, since it needs to check the $_FILE variable, not $_POST.

CSS/JS Files

Often times you need to use additional assets in your field type. This could be a CSS file or a view. PyroStreams is set up to allow you to pull in these files without having to figure out where your field type is in the file system.

If you need to add CSS or Javascript on the back end of PyroCMS, you can put them into a css or js folder in the field type, and add them by adding a function called event():

public function event()
{
    $this->CI->type->add_css('email', 'example.css'));
    $this->CI->type->add_js('email', 'example.js'));
}

The above code will add the example.css and example.js files to the admin area from the email field type.

Using View Files

If you'd like to load a view file from your field type, create a views folder in your field type folder and place your view file in there. You can call your view file like this:

$this->CI->type->load_view('field_type_slug', 'view_file', $data, true);

After the first parameter, which should be the field type slug, the next three parameters are the same as CodeIgniter's $this->load->view() function.

Field AJAX Functions

If you need to have your field type access an ajax function, you can create a function in your field type prefixed with ajax_.

public function ajax_myfunction()
{
    // AJAX functionality here.
}

You can then access that function via the following URL:

http://example.com/streams_core/public_ajax/field/[field_type_slug]/myfunction

Remember, this function is publicly accessible, so if you need data checks you need to do those yourself. (Ex: checking for a logged in user). The reason these ajax functions are kept public since we can't anticipate where the entry form using the field type will be used. It could be public or private.