# Fields

todo

Config Key: fields

<?php

// CLIENT_CONFIG/config/fields.php

return [
    'some_field' => [
        'field' => [
            /**
             * Configuration for the field comes here
             */
        ],
        'values' => [
            /**
             * Configuration for the Values come here
             */
        ]
    ],

    // add more fields
];

WARNING

Not all fields support all options a field might have. Within the list of options we've marked the fields-types where the specific option is not applicable.

# Common Field Configuration

todo

# Visual Options

field.label

The label is displayed on the Gui whenever the user interacts with the field.

Required
Type String

field.description

The description is used in later versions of SCP Gui to display a tooltip text for the field use to the user.

Optional
Type String
Default ''

field.placeholder

If the visual field repesentation (e.g. a text-box) supports a placeholder, SCP uses this configuration.

Optional
Type String
Default ''

field.icon

When the filter pane is collapsed SCP is showing icons instead of names for the gui filter. Here you can define the icon by using names of the Material Design Icon Library (opens new window).

Optional
Type String
Default 'help'

field.group

If you have a lot of fields, group them in categories to make the life of your users easier. Setting the group key just adds a new group to the property list.

Optional
Type String

# Behavioral Options

field.filter

The filter is used to determine if the field will be used for a given material. It needs to match the meta data of a material in order to become attached. We default this to [] - an empty filter - which matches always.

Optional
Type Filter
Default: []

field.type

Fields need to have a type to let SCP know which kind of form field should be displayed to the user.

Required
Type String
One of select, tag, date, text, textarea, materials, bool, autocomplete

field.filteringEnabled

If enabled the Gui will display a gui-filter inside the filters section to allow users searching through this meta data field.

Optional
Type Boolean
Default true
Not applicable for types: materials

field.required

If set to true the field needs to be filled out.

Optional
Type Boolean
Default false

field.triggersFieldUpdate

If you set this to true a field change will force the Gui to revalidate all business rules, filters, etc. to display proper fields. If you want to e.g. display specific fields based on values of other fields, the fields which are controlling visibility state should have this option enabled.

Optional
Type Boolean
Default false
Not applicable for types: materials

field.propertyListEnabled

If this option is set to true, the field is displayed inside the property pane. For fields you want to use without exposing the value to your users, set this option to false.

Optional
Type Boolean
Default true

field.sortingEnabled

If you want users to be able to use a field for sorting, just enable this configuration and the Gui will display an appropriate option.

Optional
Type Boolean
Default false
Not applicable for types: materials

field.disabled

Every fields can be disabled by a static true value placed here or by a dynamic filter which is evaluated against the material meta data automatically.

Optional
Type Boolean | Filter
Default false

# Advanced Options

field.options.updates

If you want to update some field configuration with the field value of the current field, you can do so by using this configuration:

<?php

// CLIENT_CONFIG/config/fields.php

return [
    'start_date' => [
        'field' => [
            'type' => 'date',
            'options' => [
                'updates' => [
                    // you can use multiple update calls
                    [
                        // this option can make use of the dot-notation to deeply change
                        // the configuration of a field

                        // in this example we are setting the minimal date of the "end_date"
                        // field to the date value of our "start_date" field
                        'field' => 'end_date',
                        'option' => 'options.minDate'
                    ]
                ],
            ]
        ],
        // ...
    ]
];

field.defaultPreference

Set this to true if you want SCP to fallback to the default values of the field when something has changed – even if there is a value stored.

This is useful if you want to control field values based on some other fields but still want to let user change the data afterwards.

Optional
Type Boolean
Default false
ONLY applicable for types: select, bool

field.alwaysEnabled

Fields get disabled by the field.disabled configuration and the fact if the material is editable or not (check Material Options for further information).

If a field is enabled by default (disabled set to false) but the meta-data of the material is not editable due to a Material Option all fields will get disabled by default.

If you want to enable some fields to be always enabled, no matter what happens – use this field and set it to true or a Filter.

Optional
Type Boolean | Filter
Default false

field.selector

The selector is a path to the database column where the data will be saved. Usually this is not required as we automatically use a JSON based field for storing field values.

Optional
Type String
Default field_values.{name_of_field}

WARNING

Use this option with caution as wrong configuration may harm the integrity of the SCP instance.

field.triggersBriefingUpdate

If you want SCP to force the content apps state to reload the material data it has already loaded from SCP Core, you should set this fields to true.

Optional
Type Boolean
Default false
Not applicable for types: materials

field.conditions

Fields may require proper validation to help users adding correct values. You can add Conditions here to let SCP know what it should check for.

field.pass_through

todo

field.pass_through

todo

# `Materials` Field

The materials field type allows users to attach other materials to the current one. This field has some special options:

field.query

This configuration may contain a query definition which is used by SCP to search for eligible materials to be linked to this meta data field.

<?php

// CLIENT_CONFIG/config/fields.php

return [
    'related_material' => [
        'field' => [
            // ...
            'query' => [
                // search for material which have the same type as the current one
                'materialType' => '$selectedMaterial.material_type_id',

                // search for material created by the current user
                'created_by_showcase_user_id' => '$user.id'
            ],
        ]
    ],
];

Optional
Default false
ONLY applicable for type: materials

The query can contain dynamic variables which should follow the dot-notation and can refer to $user and $selectedMaterial.

field.maximum

This is the maximum of allowed materials to attach to this field.

Optional
Type Integer

# `Date` Field

Under the hood SCP uses the awesome Flatpickr (opens new window) which means that you can pass all kind of Flatpickr Options (opens new window) to the options array of the field definition to fully control how the Date fields works:

<?php

// CLIENT_CONFIG/config/fields.php

return [
    'reviewer' => [
        'field' => [
            // ...
            'type' => 'autocomplete',
            'settings' => [
                'route' => '/showcase-users/search',
                'display' => '%first% %last%',
                'value' => '%id%',
                'max' => 4
            ],
        ]
    ],
];

# `Autocomplete` Field

The auto-complete field is a very generic one which is mainly used to search for users. But it can be easily used to extend the Gui to search for some kind of data in JSON based APIs as well.

It supports the following options

field.settings.route

The route which is used by a HTTP Get request to get the JSON based data when the user enters something to the input.

field.settings.display

What should be displayed to the user when the results are consumed. You can pass over some tokens like %key% %another_key% which will use the JSON data from the Get request to display the given data.

field.settings.value

The value field also uses the tokens which are used for the field.settings.display property. The resulting value will be used and stored in SCPs database.

field.settings.max

Determines how much results will be displayed to the user once the Get results has been fetched.

<?php

// CLIENT_CONFIG/config/fields.php

return [
    'related_material' => [
        'field' => [
            // ...
            'type' => 'date',
            'options' => [
                // we want to also pick the time
                // see https://flatpickr.js.org/options/
                'enableTime' => true,
            ],
        ]
    ],
];

# Values Configuration

Some field types require setting a list of values from a user can choose from. This is typical for tag and select fields which are quite common.

Also text based fields can have a default value which will be used as a default text.

<?php

// CLIENT_CONFIG/config/fields.php

return [
    'language' => [
        'field' => [
            // ... some configuration
        ],
        'values' => [
            [
                /** This is a field value set */
                'filter' => [
                    'language' => 'switzerland'
                ],
                'values' => [
                    'de' => [
                        'name' => 'German',
                        'default' => true,
                    ],
                    'fr' => [
                        'name' => 'French',
                        'default' => false,
                    ],
                    // additional values
                ]
            ],
            [
                /**
                 * This is a field value set too, which is
                 * used if nothing else match
                 */
                'filter' => [],
                'values' => [
                    'en' => [
                        'name' => 'English',
                        'default' => true,
                    ],
                ]
            ],
        ]
    ],

    // add more fields
];

filter

A value set will be chosen by evaluating the given filter – if the filter matches the current material SCP select the configured values and makes them available to the use to choose from.

Required
Type Filter

values

The values key has to contain an associative array which needs to expose keys which are used by SCP to store the selected value. From the example above, selecting "German" will lead to a stored value de inside the database.

Required
Type [String => [ ... ]]

values.*.name

The name is used as label for the value the user is choosing from.

Required
Type String

values.*.default

If a value is set as default (true) it will be used as the a pre-selection.

Optional
Type Boolean
Default: false

# Defaults for text-based fields

Fields which are based on just a single value bool, textarea, text can have a default value too:

<?php

// CLIENT_CONFIG/config/fields.php

return [
    'description' => [
        'field' => [
            // some configuration
        ],
        'values' => [
            [
                'filter' => [], // matches always
                'value' => 'This is the default text',
            ],
        ]
    ],

    // add more fields
];

# Field Conditions (Validation)

You can set condition on fields to force the user to follow some rules while giving some input.

<?php

// CLIENT_CONFIG/config/fields.php

return [
    'approval_code' => [
        'field' => [
            // ...
            'type' => 'text',
            'conditions' => [
                [
                    /**
                     * This is a condition
                     */
                    'rules' => [
                        // which is using two different rules
                        'max' => 20,
                        'regex' => '^[0-9]{3}-[A-Z]+'
                    ],
                    // and will output this message if one of the rules
                    // are not followed by the user
                    'message' => 'Please follow the guideline 123-XXX'
                ],
                [
                    // here could come a new condition with an additional message
                ]
            ]
        ]
    ],
];

We use vee-validate (opens new window) under the hood – checkout their rules which can be used inside SCP natively.

Limited Support

Not all fields can make use of conditions – there is not a real list of which one can be used on why type, but with just common sense, you'll find the right answer 😃

# Examples of Rules

todo

<?php

// CLIENT_CONFIG/config/fields.php

return [
    'approval_code' => [
        'field' => [
            // ...
            'type' => 'text',
            'conditions' => [
                [
                    'rules' => [
                        'min' => 3,
                    ],
                    'message' => 'Your text is less than 3 characters long!'
                ],
                [
                    'rules' => [
                        'max' => 10,
                    ],
                    'message' => 'Your text is more than 10 characters long!'
                ],
                [
                    'rules' => [
                        'alpha' => [] // no options (default!)
                    ],
                    'message' => 'Your text does contain non alphanumeric characters'
                ],
                [
                    'rules' => [
                        'alpha_dash' => [] // no options (default!)
                    ],
                    'message' => 'Only alphanumeric values and underscores and dashes'
                ],
                [
                    'rules' => [
                        'alpha_num' => [] // no options (default!)
                    ],
                    'message' => 'Please only numbers and characters, no special chars'
                ],
                [
                    'rules' => [
                        'alpha_spaces' => [] // no options (default!)
                    ],
                    'message' => 'Only alphabetic characters and spaces please'
                ],
                [
                    'rules' => [
                        'between' => [] // no options (default!)
                    ],
                    'message' => 'Your numeric value needs to be between 1 and 5'
                ],
                [
                    'rules' => [
                        'digits' => [] // no options (default!)
                    ],
                    'message' => 'Numeric value with 5 digits please'
                ],
                [
                    'rules' => [
                        'email' => [] // no options (default!)
                    ],
                    'message' => 'You have to enter a valid email address'
                ],
                [
                    'rules' => [
                        'in' => ['first', 'second']
                    ],
                    'message' => 'Please use only one of the given values: first, second'
                ],
                [
                    'rules' => [
                        'not_in' => ['first', 'second']
                    ],
                    'message' => 'Please do not use one of the given values: first, second'
                ],
                [
                    'rules' => [
                        'max_value' => 10
                    ],
                    'message' => 'Your numeric value needs to be less or equal than 10'
                ],
                [
                    'rules' => [
                        'min_value' => 10
                    ],
                    'message' => 'Your numeric value needs to be at least than 10'
                ],
                [
                    'rules' => [
                        // for backslashes use \\\\ (four backslashes)
                        'regex' => '^([0-9]+)$'
                    ],
                    'message' => 'Only numbers please'
                ],
                [
                    'rules' => [
                        'url' => false // true = with http://
                    ],
                    'message' => 'Please enter a valid url (without http://...)'
                ],
            ]
        ]
    ],
];

todo

← Material Options Service Options →

# Fields

# Common Field Configuration

# Visual Options

# Behavioral Options

# Advanced Options

# Materials Field

# Date Field

# Autocomplete Field

# Values Configuration

# Defaults for text-based fields

# Field Conditions (Validation)

# Examples of Rules

# Signup Fields

# `Materials` Field

# `Date` Field

# `Autocomplete` Field