Creating a component¶
The best way to create a component is probably by looking how other components are built up, and copying from them. In addition, this guide will help you to better understand what is going on.
Terminology¶
Please remember the following terminology, in addition to the basic terminology:
- A component is a complete set of PHP, HTML, JS & CSS code that defines the behaviour of a specific type of user input, being for instance a text field, checkbox or heading.
- A field is an instance of a component added to a form, complete with filled-in configuration values such as field name (=technical name!), field title (as shown to users), and things like placeholders, default values, required status, visibility conditions et cetera.
- A field value is an object entirely devoted to reading, parsing, validating and saving the value a user submitted to a field.
Additionally:
- The structured storage methods
toStructured()
andfromStructured()
define how the value of the field should be registered in PHP. The structured format is a mixed format: it may be e.g. an int, string, (multi-dimensional) array, et cetera. - The flat storage methods
toFlat()
andfromFlat()
define how the value of the field should be stored in the database. It has a more restricted format:toFlat()
should return a one-dimensional array of data, where each entry in the array corresponds to one column in the database table created for the form. A component may use any number of entries in the flat representation; either 0, 1 or more, as desired.
Directory structure¶
A component has a specific directory structure:
src
├── js (or css)
│ ├── {view_name}.js (e.g. form.js)
│ └── {layout_name}-{view_name}.js (e.g. bootstrap4-form.js)
├── locale
│ └── {locale_name}.yml (e.g. en_US.yml)
├── view
│ └── {layout_name} (e.g. bootstrap4)
│ ├── form.mustache
│ └── submission.mustache
├── config.yml
├── {view_name}.css (e.g. form.css)
├── {view_name}.js (e.g. form.js)
├── {component_name}Component.php
├── {component_name}Field.php
└── {component_name}Value.php
Here, view_name
can be either form
, submission
, builder
or all
. When using a specific view, the js/css file is only included when required (i.e., when that view is loaded).
When using all, the js/css file is always included whenever the component is used.
You can put a general JS or CSS file in the root src
dir, or put it in the js/css subdirectory. Additionally, you can place JS and CSS files in the js/css subdirectory with a filename {layout_name}-{view_name}.js/css
to specify code for a specific layout.
In the locale folder, you can add translations in multiple languages. Note that the keys used in this file also need to be registered in the config.yml
file.
In the view folder, all HTML code is situated, using Mustache as templating engine, in PHP as well as in Javascript. For each supported layout, you should add two view files, form.mustache
and submission.mustache
.
The file config.yml
defines the general properties of your component.
The three PHP files contain the PHP code of your extension. The component file contains general functionality, the field file contains functionality for fields (component instances in the form), and the value file contains functionality for parsing, validating and processing submitted values.
Specifics¶
Components come with a relatively large number of options you can use, hence we split this guide into four sections: