Form options
Form section defines editing fields and actions used for data edit. Form options can be divided into three groups.
- general form options, define common options for creating form dialog
- actions, define actions that can be performed on document when editing
- form fields, form tabs with fields which define data entry fields
title: optional
field: field_name
new: Title for new document
edit: Title for edit document
Default form dialog title consists of operation (Edit, New), collection name (translated) and document ID (think copy+paste). When editing, the dialog title may also include value of field, which best describes the value of the document. This is the usual name or description field.
Example:
field: subject
result title => Edit : Page : Plugins page : 52a393d6835d1b00c5000026 # where Plugins page is the value of subject field.
Additional new and edit options can be used, when you want to use your own text for dialog title.
height: optional
Height of form dialog in pixels. By default, the form dialog is resized to the size of the currently selected tab. If you want to manually set form height, it may be set by height parameter. Behavior of height was improved, and this option might be obsolete.
actions: required
Actions are required because at least one action (back) must be defined on every edit form. There are 5 predefined standard actions which can be defined as actions: standard. These actions are:
- back (Go back, discard entered changes)
- save (Save changes and resume editing)
- save&back (Save changes and go back to index)
- new (New action). Start editing new empty document. Changes to current document are not detected, so user must first choose save action, otherwise changes to current document will be lost.
- enable, disable (This action only appears when a document has active field defined. It is used to toggle the value of active field)
In addition to standard action, there are other actions that might be performed before the document is saved and or after the document is saved. These methods must be defined in drgcms_controls in addition or instead of standard dc_before_save or dc_after_save callbacks.
type: submit
Will create an action which acts like standard save action, except that some additional parameters may be set which affect standard program execution. Example:
form: actions: type: standard 10: type: submit caption: Approve icon: thumbs-o-up title: Save and approve document params: after-save: approve
In the above example, document will be submitted to standard cms_edit controller action and will call DrgcmsControls::MyModel approve method after document is successfully saved. Be aware that in this case, standard dc_after_save action will not be executed. You can also use before-save to perform operations before the document is saved.
This is the way to call additional actions which are defined in the DrgcmsControls file. Standard Rails way would be to create another controller action and add route to routes.
type: ajax
This will be AJAX (asynchronous background call) type action. Call options are the same as options in other actions. In the example below, simple form is used to trigger PDF document creation. Action will call MyReports::report_no_1 method, pass start_date and end_date as parameters and wait for AJAX call to return. The AJAX return will commonly trigger open PDF document command.
table: dc_dummy title: Enter starting and ending date for report form: actions: 1: type: ajax method: post controller: my_reports action: report_no_1 caption: Run report icon: cog fields: 10: name: start_date type: date_picker caption: Start date 20: name: end_date type: date_picker caption: End date
type: script
JavaScript will be executed when action is selected. In the example below is form embedded into iframe. When Back action is selected, the parent window is reloaded.
The same functionality can also be achieved when submitting data by defining params:after-save option. This can be shown on the second (type: submit) code example.
form: actions: 1: type: script caption: Back js: parent.location.href=parent.location.href 5: type: submit caption: Save and update params: after-save: return_to parent.reload
fields: required or tabs: required
Fields on a data entry form are usually arranged continuously from top to bottom. Alternatively, they can be grouped on tabs. Tabs are horizontally arranged on the top of the form. When the user clicks on tab, data entry fields which are defined under tab are displayed and can be edited. Fields on a previously displayed tab are hidden to the user.
Below is an example of form with fields option:
form: title: field: caption actions: standard fields: 10: name: caption type: text_field html: size: 30 20: name: picture type: file_select html: size: 50
This simple form has two data entry fields. First field (caption) is type of text_field with size of 30. The second field name is picture and is type of file_select. And its size is 50. A list of field types supported by DRG CMS is described in the next chapter. The list includes all basic data entry field types (text_field, text_area, check_box, select ...) as well as some specific data entry types (html_field, multitext_autocomplete, date_picker, ...). If needed, you may extend data entry field types with your own data entry types.
form: title: field: caption actions: standard tabs: tab1: 0: columns: 2 10: name: caption type: text_field size: 30 20: name: date type: date_field 20: name: picture type: file_select size: 50 colspan: 2 tab2: 10: name: body type: html_field options: "height: 420, toolbar: 'basic', allowedContent: false"
Our resulting form will have 2 tabs. 1tab and 2tab. Numbers are here to ensure that tabs will be displayed in wanted order. First tab will have entry fields displayed in two columns per row. Tab captions can also be localized. All you need is define translations for tab names in localization files.
en: helpers: label: model_name: 1tab: Common 2tab: Content
Now that we have seen how data entry fields are defined, let's see the type of data entry fields that are available in DRG CMS.