How to create a structure
The point of having a form is usually to read and/or write data to the database. So, if to which you wish to read/write doesn't exist already, you should create it. Then, you can use the Form Builder and follow it's own guide, or do it the hard way and continue here.
Creating the structure
Creating the structure is the easiest part. All you have to do is an insert into the structures table and specify an alias.
Creating the fields
You have to create an association between database fields and html fields. That is done through the structure_fields table. The tablename and field fields are pointers to the database.
The plugin and model fields are an abstraction level. The information you need to provide should be related to where you will put your table model into cake and the name you will give it. If your model is named MyModel and is put into the MyPlugin plugin, then you have to provide "MyPlugin" as the plugin name and "MyModel" as the model name.
For the other fields
- language_label
- The label that represents your field. Ex.: Temperature
- language_tag
- A tag that will be next to your field. Ex.: If you have a temperature field, you can specify Celcius as a tag to give an indication of what kind of input is expected.
- type
- The type of your field. For a list of available types, head over to Form Elements
- setting
- Special indications for your field. The syntax is [setting_name]=[value]. Each setting must be separated by a comma. Here are the available settings.
| Setting name | Use |
|---|---|
| cols | Used for textarea, defines the width in term of characters. |
| rows | Used for textarea, will defines the height in term of characters. |
| size | Used for input of type text and number, defines the width in term of characters |
| maxlength | On supported browser, the maximum number of inputable character into an input field of type text or number |
| url | On autocomplete fields, defines where to send/get the autocomplete data |
| tool | If the value is "csv", will add a field where it is possible to specify a file. If the value is an url, a tool icon is added at the right of the field. Clicking the icon opens a pop-up that is meant to help the user pick a value for the field. The url is the address of the pop-up. |
| class | The only currently supported value is "range". It will add a "range" button at the right of the field in search form. Clicking on it converts the field to a "from X to Y" type, allowing to search the reference with a range of values rather than a specific one. |
- default
- The value that will be shown by default in that field when in add mode.
- structure_value_domain
- If your field is a checkbox or a select, you probably want to bind it to a structure value domain. Structure value domain binds a database value to a textual representation. That way, a checkbox can be recorded as either 0 or 1 into the database and displayed as Yes or No into ATiM.
- language_help
- This is the untranslated text that will appear in the help bullet.
Note: If the field you wish to use already exists but with wrong parameters, those can be overridden into structure_formats.
Binding the fields to the structure
The last step is about associating your fields to your structure. This is done through strucure_fields. The first fields of this table are pretty straight forward. They are structure_id and structure_field_id. You need to respectively put the id of your structure and the id of your structure_field.
Then you can set display_column and display_order. The former is an indication of which column will old your field and the later is an indication of the order. Note that they are not absolute. Say you have a form with only two fields, one is defined as column 1, order 1 and the order as column 3, order 3. There will be no empty line nor empty column separating them. They will be on the same line side by side. The way it works is that column and order are simply used in an SQL ORDER BY clause. Also, in a datagrid, all fields will be side by side based on the same ORDER BY column, order.
Afterward you can specify in which forms your field should appear or not. This is done by the flag_add, flag_edit, flag_search, flag_addgrid, flag_editgrid, flag_index and flag_detail fields. Note there is also flag_add_readonly, flag_edit_readonly and flag_addgrid_readonly, flag_editgrid_readonly. As their name suggests, if they are set to true, the field will be present but not editable.
Should you want to override some settings that were defined in structure_field, you can do so with by setting the proper flag_override_* to true and using the matching field to provide the override value.
