Skip to content

Commit af1bb2d

Browse files
TomJaegerTomJaeger
authored
Merge pull request #512 from aleppax/7.dev
added tables for properties and settings, examples
2 parents 2ef0e6a + 5138a2c commit af1bb2d

File tree

1 file changed

+158
-24
lines changed

1 file changed

+158
-24
lines changed

‎docs/development/models/channel-field.md‎

Lines changed: 158 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -20,32 +20,85 @@ lang: php
2020
## Properties
2121

2222
### Required
23-
24-
- `site_id`
25-
- `field_name`
26-
- `field_label`
27-
- `field_type`
28-
- `field_list_items` (can be empty)
29-
- `field_order`
23+
| Name | Validation | Type | Description |
24+
| ----------------------- |------------ | ---------- | ----------- |
25+
| `site_id` | required | integer | |
26+
| `field_name` | required, alphaDash, unique(installation wide), validateNameIsNotReserved, maxLength[32]| | |
27+
| `field_label` | required, maxLength[50] | | |
28+
| `field_type` | required, validateIsCompatibleWithPreviousValue, enum[checkboxes, colorpicker, date, duration, email_address , file, file_grid, fluid_field, grid, multi_select, notes, radio, range_slider, relationship, rte, select, selectable_buttons, slider, text, textarea, toggle, url] (or the name of a custom field type)| |validateIsCompatibleWithPreviousValue is used when modifying the field_type of an existing field. Please see [Fieldtype Compatibility Options](../addon-setup-php-file.md#fieldtypes) for more details. |
29+
| `field_order` | | integer | |
30+
| `field_list_items` | required (can be an empty string) | | The simplest of three mutual exclusive ways to populate a list of items is using a string with items separated by line breaks \n. Used with listing field types (Checkboxes, Multi Select, Radio Buttons, Select Dropdown and Selectable Buttons) when field_settings['value_label_pairs'] is not set and 'field_pre_populate' == 'n' (do not populate from channel entries)|
3031

3132
### Optional
33+
| Name | Validation | Type | Description |
34+
| ----------------------- |------------ | ---------- | ----------- |
35+
| `field_id` | | integer | |
36+
| `field_instructions` | | | |
37+
| `field_pre_populate` | enum[y,n,v] | boolString | if 'y' populate a list of items from channel entries. Used in conjunction with the two properties `field_pre_channel_id` and `field_pre_field_id` |
38+
| `field_pre_channel_id` | | integer | |
39+
| `field_pre_field_id` | | integer | |
40+
| `field_ta_rows` | | integer | height of a textarea field in rows |
41+
| `field_maxl` | | integer | max length of a text input field |
42+
| `field_required` | enum[y,n] | boolString | |
43+
| `field_text_direction` | enum[ltr,rtl] | | |
44+
| `field_search` | enum[y,n] | boolString | |
45+
| `field_is_hidden` | enum[y,n] | boolString | |
46+
| `field_fmt` | | enum[br,xhtml,none] | used only by some field types, 'br' stands for auto line break |
47+
| `field_show_fmt` | enum[y,n] | boolString | |
48+
| `field_content_type` | enum[all,any,image,integer,text] | | |
49+
| `field_settings` | | base64Serialized | Specific settings depending on the field type. See the following table. |
50+
| `legacy_field_data` | | boolString | |
51+
52+
## Field settings
53+
54+
The property `field_settings` consists in an array of settings that depend on the field type. Here are the most common settings for the standard field types. field settings are stored in the database column 'field_settings' as a base64 encoded string of the serialized array.
55+
56+
| Field types | Setting name | Values | Description |
57+
| ------------------- |------------ | ---------- | ----------- |
58+
| Checkboxes, Multi Select, Radio Buttons, Select Dropdown, Selectable Buttons | `value_label_pairs` | associative array | |
59+
| Color Picker | `allowed_colors` | enum[any,swatches] | |
60+
| Color Picker | `colorpicker_default_color` | | hex color code, or null |
61+
| Color Picker | `value_swatches` | array | array of hex color codes, used when `populate_swatches` is set to 'v' (value) |
62+
| Color Picker | `manual_swatches` | | hex color codes separated by line breaks, or null, used when `populate_swatches` is set to 'm' (manual) |
63+
| Color Picker | `populate_swatches` | enum[m,v] | 'm' manual or 'v' value |
64+
| Duration | `units` | enum[seconds,minutes,hours] | |
65+
| File, file_grid | `field_content_type` | enum[image,all] | |
66+
| File, file_grid | `allowed_directories` | 'all' (or integer for upload directory id) | required |
67+
| File | `show_existing` | enum[y,n] | When enabled, a drop down with existing files will be shown to authors. |
68+
| File | `num_existing` | integer | Maximum number of files to show in the drop down. |
69+
| File, Rich text editor | `field_fmt` | 'none' | |
70+
| file_grid, grid | `grid_min_rows` | integer | default 0 |
71+
| file_grid, grid | `grid_max_rows` | integer | |
72+
| file_grid, grid | `allow_reorder` | enum[y,n] | |
73+
| fluid_field | `field_channel_fields` | array | channel IDs used in the fluid field |
74+
| Notes | `note_content` | text | default is ''|
75+
| Notes | `field_hide_title` | bool | default is true |
76+
| Notes | `field_hide_publish_layout_collapse`| bool | default is true |
77+
| Range slider, value slider | `field_min_value` | integer | default to 0 |
78+
| Range slider, value slider | `field_max_value` | integer | default to 100|
79+
| Range slider, value slider | `field_step` | integer | default to 1 |
80+
| Range slider, value slider | `field_prefix`,`field_suffix` | | |
81+
| Range slider, value slider, Text input | `field_content_type` | enum[all,number,integer,decimal] | |
82+
| relationship | `channels` | array | channel IDs |
83+
| relationship | `expired`, `future` | | Allow expired or future entries in this relationships field |
84+
| relationship | `categories`, `authors`, `statuses`| array | limit the entries by categories, authors or statuses IDs |
85+
| relationship | `limit` | integer | Sets the number of entries displayed in the field's dropdown |
86+
| relationship | `order_field`, `order_dir` | enum[title,entry_date] , enum[asc,desc] | Default ordering of entries |
87+
| relationship | `display_entry_id` | enum[y,n] | |
88+
| relationship | `allow_multiple` | enum[y,n] | |
89+
| Rich text editor | `toolset_id` | integer | see Rich Text Editor addon for details, for a standard installation: 1 CKEditor Basic, 2 CKEditor Full, 3 Redactor Basic, 4 Redactor Full |
90+
| Rich text editor | `defer` | enum[y,n] | Defer Editor initialization |
91+
| Rich text editor, Textarea | `db_column_type` | enum[text,mediumtext]| Column type in database: TEXT(64Kb) MEDIUMTEXT(16Mb) |
92+
| Rich text editor | `field_wide` | bool | default true, full width |
93+
| Rich text editor | `field_show_fmt` | enum[y,n] | default 'n' |
94+
| Text input | `field_maxl` | integer | Maximum characters |
95+
| Text input, Textarea | `field_show_smileys` | enum[y,n] | |
96+
| Text input, Textarea | `field_show_file_selector` | enum[y,n] | |
97+
| Textarea | `field_show_formatting_btns` | enum[y,n] | |
98+
| Toggle | `field_default_value` | enum[0,1] | |
99+
| URL | `allowed_url_schemes` | array | example ['http://','https://'] |
100+
| URL | `url_scheme_placeholder` | | example 'http://' |
32101

33-
- `field_id` Key
34-
- `field_instructions`
35-
- `field_pre_populate`
36-
- `field_pre_channel_id`
37-
- `field_pre_field_id`
38-
- `field_ta_rows`
39-
- `field_maxl`
40-
- `field_required`
41-
- `field_text_direction`
42-
- `field_search`
43-
- `field_is_hidden`
44-
- `field_fmt`
45-
- `field_show_fmt`
46-
- `field_content_type`
47-
- `field_settings`
48-
- `legacy_field_data`
49102

50103
## Relationships
51104

@@ -60,7 +113,7 @@ lang: php
60113
- `getContentType`
61114
- `getSettingsValues`
62115
- `getAllChannels`
63-
- `validateNameIsNotReserved`
116+
- `validateNameIsNotReserved` the list of reserved words is in /ee/legacy/libraries/Cp.php: invalid_custom_field_names()
64117
- `validateIsCompatibleWithPreviousValue`
65118

66119
## Events
@@ -164,3 +217,84 @@ if ($result->isValid())
164217
$field->save();
165218
}
166219
```
220+
221+
### Populate a field compatible with list field types
222+
223+
For fields like Checkboxes, Multi Select, Radio Buttons, Select Dropdown and Selectable Buttons there are three ways to populate their options: value-labels pairs, manually or from other channel.
224+
225+
```php
226+
// populate manually
227+
$field->setProperty('field_list_items', "first\nsecond\nthird");
228+
// Validate and Save.
229+
```
230+
```php
231+
// populate with value-labels pairs
232+
$checkboxes_settings = array(
233+
'value_label_pairs' => array('winner' => 'first', 'player' => 'second', 'loser' => 'third')
234+
);
235+
// change field settings
236+
$changing_settings = $field->getSettingsValues()['field_settings'];
237+
foreach ($checkboxes_settings as $s => $s_value) {
238+
$changing_settings[$s] = $s_value;
239+
}
240+
$field->setProperty('field_settings', $changing_settings);
241+
// Validate and Save.
242+
```
243+
```php
244+
// or populate from other channel field
245+
$field->setProperty('field_pre_populate','y'); // default is 'n'
246+
$field->setProperty('field_pre_channel_id',4); //channel id
247+
$field->setProperty('field_pre_field_id',80); // field id
248+
// Validate and Save.
249+
```
250+
251+
### Create a relationship field
252+
253+
```php
254+
//Relationships with channel #4
255+
256+
//all properties are required
257+
$relata_properties = array(
258+
'field_label' => 'relata',
259+
'field_name' => 'relata',
260+
'field_type' => 'relationship',
261+
'field_list_items' => ''
262+
);
263+
264+
//all settings are optional
265+
$relata_settings = array(
266+
'channels' => array(4), // if missing relates to all channels
267+
'expired' => true, // if missing defaults to false
268+
'future' => true, // if missing defaults to false
269+
'categories' => array(), // if missing or empty allows relationships with all categories
270+
'authors' => array(), // if missing or empty allows relationships with all authors
271+
'statuses' => array('open'), // if missing or empty allows relationships with all statuses
272+
'order_field' => 'entry_date', // default is by title
273+
'order_dir' => 'desc', // default is ascending
274+
'display_entry_id' => null, //default is false
275+
'allow_multiple' => true, // default is true
276+
'rel_min' => 0, //Minimum number of related entries
277+
'rel_max' => null // Maximum number of related entries
278+
);
279+
280+
$field = ee('Model')->make('ChannelField');
281+
282+
$site_id = ee()->config->item('site_id');
283+
$field->site_id = $site_id;
284+
// field_order: increment the last field order number of fields belonging to this site
285+
$ordernumber = 1 + ee('Model')->get('ChannelField')->filter('site_id',$site_id)->order('field_order', 'DESC')->first()->field_order;
286+
$field->field_order = $ordernumber;
287+
288+
// field settings
289+
$changing_settings = $field->getSettingsValues()['field_settings'];
290+
foreach ($relata_settings as $s => $s_value) {
291+
$changing_settings[$s] = $s_value;
292+
}
293+
$field->setProperty('field_settings', $changing_settings);
294+
295+
// field properties
296+
foreach ($relata_properties as $p => $p_val) {
297+
$field->setProperty($p, $p_val);
298+
}
299+
// Validate and Save.
300+
```

0 commit comments

Comments
 (0)