The editor uses a similar form capability which allows one to create a form without having to write all the HTML tags needed to handle each widget. Actually, one widget may include many tags and it can be so complicated that attempting to rewrite those tags by hand each time would be really tedious.
The core system offers the basic widgets such as a simple text edit and image drag and drop area. We already support one widget extension called locale allowing the user to select a timezone. This is an external extension to the editor.
Each widget needs at least one attribute defining their type. These are defined in the <widget> tag. The <snap-editor> also includes other tags defining the first widget which should be given the focus first, the tab order, and a few other form wide choices.
'?' -- what the heck was I thinking?
content-modified The root tag defining forms using the Snap! editor plugin.
* owner -- define the owner of the form, the name of the plugin; it is often set to "output" although if you want to properly fail when your plugin gets uninstalled, you may want to use the name of your plugin.
TBD: The tag includes a list of comma separated REFID that limit the widgets that get cleared to those listed. If the list is empty, clear the entire form.
<focus> <snap-editor> refid Define which widget should be given focuson startup. The widget to be focused is referenced by the refid attribute. It references the identifier as defined by the id attribute of the widget tag. The focus tag is expected to always be an empty tag.
<taborder> <snap-editor> A list of identifiers giving the order in which widgets should be selected when the tab key is used. The list of identifiers is defined using the <tabindex> tags.
Note 1: some widgets do not yet support the tab key properly (i.e. timezone widget, radio button group).
<tabindex> <taborder> refid Defines the widget identifier at that position. The list of tab indexes is used to define the tabindex attribute of the different HTML input tags generated by Snap! for your form. The HTML tabindex numbers are automatically generated for you. The refid attribute references the id of a widget. There can be only one <tabindex> that reference a given refid or your table is considered invalid.
<drop> <snap-editor> Mark all widgets as accepting drops of files. It is also possible to mark a specific widget as accepting drops using the drop attribute of that <widget> tag.
<accesskeys> <snap-editor> The list of accesskeys. It is made in its own block to make it easy to see which key is used for what widget in a single place.
<key> <accesskeys> refid Defines the key that activates the specified widget. The widget is referenced by refid which should match one of the widget id attributes.
drop Define a widget with all of its parameters. This tag is what is used to add widgets to a form. All widgets are defined within a widget tag. Widgets are named using the id attribute. Each widget must have a unique id.
The different types of widgets are defined using the type attribute (see table below.) There is no default type.
When a widget corresponds to a field in the database, you can name it in the field attribute. This allows the editor to read the data before sending the form to the client and to write the data directly to the database when saving the form. The auto-save attribute is also needed for that purpose.
The widgets are transformed into HTML tags and added to your XML document that will later be parsed by your body parser. The path attribute is used to define the path in that XML document. The path is always relative. The widgets are always added in the /snap/page/body tag.
When defining a password field and you want to have a duplicate for verification (when you change your password) then you should define the identifier (id) of the duplicate widget. This is done using the duplicate-of attribute.
The difference between html, string, and plain is not always easy to grasp. In general, a text-edit widget is said to use html and a line-edit will be setup as using string. We also support a text-html type which is clearly HTML. However, the line-edit may end up with a tag and string will keep that tag intact. It may not be a problem for you, but in some situation you may want to not have the tag. In that case you want to use plain. How does this happen? Copy & Paste is probably the main offender in a line-edit. It could also be the browser that decides to transform an email into a mailto: anchor (Internet Exporer does that by default).
WARNING: changing the type of data of a widget means that any existing data is lost. The database has no information about the type of data from the old type so the edit cannot read the old data properly. If you need to change the type, it is safer to rename the field (see field attribute) and write an upgrade path which will load the old data, convert it, and save it back to the new field.
<label> <widget> lang The label of the widget is used to name a widget. By default this is the few words appearing just before an input widget. The lang attribute defines the language of the label. If undefined, the default language for that website is used. If the website has no default, "en" is assumed.
<background-value> <widget> The value appearing in the background of the widget when it is empty.
This value is often the name of the widget (i.e. username, password, email, address, zip code, etc.) so the user knows what to enter even if no label or description was given for that field.
<sizes> <widget> This tag includes a set of sizes / limits as defined below.
You may use the <max-lines> tag to enforce a maximum number of lines.
For images, the parameter is parsed as a <width>x<height> string and the dimensions of the image are checked using these dimensions.
<min> <sizes> Defines the minimum length (in characters) that this field can be. In most cases this is not defined. The default is zero (0) which means empty values are accepted. A minimum of 1 makes the field mandatory, although you probably want to use the <require> tag instead. The system may represent mandatory fields with a little red start (*) at the end of the label or after the field or with a different field color or shape. Note that the filters may also impose a minimum, but if not defined here, then no required flag appears.
You may use the <min-lines> tag to enforce a minimum number of lines.
* read-only -- the widget is visible, but it cannot be edited, however, it may still receive the focus so one can use the keyboard to select the content of the widget.
multiple Widgets that accept a file (marked with the drop attribute) can define parameters about the file using the <attachment> tag.
The attachment being saved in its own page, that page has to be assigned an owner and a type. By default the owner attribute is set to the "attachment" plugin. Similarly, by default the editor uses "attachment" for the type of the page. The type attribute can be used to change the type of the page.
The identification attribute defaults to "attachment/public". It represents the permission to use for the attachment page in the database. This is expected to be a relative path that is appended to the path types/taxonomy/system/content-types/... The system defines "attachment/private" which can be used to only allow logged in users to access the content.
By default, the filename sent by the browser is used to save the attachment. If only one file is accepted in that widget, then the force-filename can be used to always give a specific name to that attachment. Note, however, that the extension of the original filename is kept. In other words, if you drop image.png and then image.jpg, you still get two distinct attachments.
<help> <widget> lang The long description for this field. In most cases this is a small help that appears under the widget so the user knows what to enter in that field. If empty, no such box is added to the widget. The lang attribute can be used to define the language of this field text. The default is the website default language. If no defaults are defined, "en" is used.
name A regular expression used to match the input. If the regex is not matched then the value is refused. The match attribute can be used to inverse the result when set to "no" (the default is match="yes").
IMPORTANT NOTE: The regular expressions, even if defined to refuse an empty string, do not prevent an empty entry (so one can use "^[0-9]+$" for an integer but that does not prevent "" to be viewed as valid in the editor. This is because the regular expressions do not get checked when the input is empty.) To force the user to have something in such a field, make sure to use the <required> tag.
<min> <filters> mode Minimum value allowed. The mode attribute defines the type of check: string, integer, float are allowed.
<max> <filters> mode Maximum value allowed, the field is expected to be numeric. The mode attribute defines the type of check: string, integer, float are allowed.
<uri> <filters> match Check whether the input is a valid URI. The check allows the URI to be entered without a protocol, the test prepends "http://" and tries again if the test of the value as is fails.
The following example accepts odd numbers only.
<extensions> <filters> Specify a list of allowed file extensions for a dropdown / file widget.
Note: this does not work very well at this point.
<tooltip> <widget> Define a small description shown when the widget is hovered and/or focused.
The editor makes use of jQuery to display the tooltip giving us a lot of flexibility over the title attribute of HTML tags. For example, our tooltip text can include HTML tags and they can appear forever in a specific location including a separate area created for that purpose.
<value> <widget> default The current value of the widget (current in the database.) This value appears as the default value and can be used by the Reset button to restore the form to the way it was loaded. Note that the Reset to Default button would use the <default> value instead.
value Define a sub-item within a <value> or a <preset> tag. These are used for widgets such as dropdown widgets to define each possible entry in the dropdown.
The default attribute can be defined to mark that specific item as the default.
The class attribute are additional HTML classes to be added to the final widget HTML.
The value attribute defines the value to be saved in the database. This can be completely different from the display string of the dropdown (which by default would be saved in the database if no value attribute is defined.) It is especially useful when you are to translate the content of the widgets.
<default> <widget> The default value of the widget. This is what you would have by default at the start. If undefined, the empty string is used as the default. This value is used when a user clicks on a Reset to Defaults button.
<preset> <widget> The <preset> tag is used by the dropdown to define the default (preset) items of the dropdown. The value repsents one of the items of the preset and as such it cannot define these values.
<require> <widget> Whether content in this widget is required. The text in that tag must be "required" too. We may add support for other texts at a later time.
<classes> <widget> A widget can be assigned additional HTML classes. This tag includes those classes each separated by a space as they would otherwise appear in the class attribute of an HTML document.
<mode> <snap-editor> action This tag forces the action set to "edit". This is most often used for plugin setting forms.
auto-save What happens when the Save command is received by the server.
The <on-save> tag uses the redirect attribute to define the destination URI. On a successful save the user is redirected to that page.
The target attribute is the same as the HTML anchor target attribute. Only we support _top, _parent, and _self for now. The meaning is the same.
The allow-edit attribute can be set to "no" in which case the editor darkens the whole screen while saving the data of this form. It is usually safer to set this flag to "no" although it defaults to "yes" since by default we expect the user to be able to further edit their data while saving.
The different types of widgets are defined in the following table. This is defined in the type attribute of the <widget> tag. The type attribute is mandatory and it has no default.
image-box An area where the user can drop image files. Files that do not represent an image are refused immediately.
dropdown A list of item on can choose in a dropdown popup. Some dropdowns may allow the user to type an entry.
The dropdown popup will always open in the top most window. This allows the dropdown to appear as if it were leaking from IFRAMEs.
Dropdown popups that are too large to be displayed on the current viewport (browser window too small) will be changed to use multiple columns or include a sliderbar. Which to use can be defined by declaring the algorithm tag for that widget.
checkmark One checkmark widget. It can be unselected or selected.
text-edit A widget allowing users to write formatted text. The format is of course defined using HTML tags and the editor is used to set those up.
line-edit A widget allowing users to write one line of text, in most cases, plain text.
button Define a button although at this time we generally directly define an anchor in the parser instead of using these buttons. We may ameliorate the use of the button at some point to make it much more useful to have buttons in the widget definition files.
custom The special type "custom" is used with widgets that are dynamically defined. The editor does not really do much with those other than output the data (i.e. <value> tag) defined by the dynamic code.
hidden A hidden widget is similar to a line-edit except that it is always sent back to the server when we save the form (contrary to the silent widget that does not get sent back.) It is always sent back because it will never change otherwise.