Home » Implementation » Feature Requirements » Editor feature [core] » Widget feature

Widget Definitions (Form)

Sat
12/01/12
WARNING: We are deprecating this plugin. The editor works great in all browsers so we do not see the need to support two similar capabilities, one of which is limited to what the browser is willing to offer us (and thus all of our additions would need to be programmed as in the editor and we would have yet another duplicate!)

I'm just starting work on the widgets as I want to have a form to register and log in as a user.

These forms are very simple, but I want the full capabilities in the forms to be available (Even if we don't have all the possible widgets.)

Different widgets will have different parameters and I would imagine that third party widgets will also have their own additional parameters. Here we list parameters defined in the Core widgets.

The widgets need at least one attribute with their type. These are defined in the snap-form tag which also includes other tags defining which widget should have the focus first, the tab order, and a few other form wide choices.

Tag Parent Attributes Comments & Example
<snap-form> root method The root tag defining forms in Snap! The method attribute can be used to change the method to GET instead of POST. Although in most cases it is not a good idea to use a GET for complex form (other than a search...)
<auto-clear> <snap-form> timeout The amount of time the user has to fill out the form before it automatically gets cleared. This is used for forms with sensitive data (i.e. passwords, credit card numbers, etc.) TBD: The tag includes a list of refid that limit the widgets that get cleared.

<snap-form>
  <auto-clear timeout="15min">password</auto-clear>
  <widget id="secret" type="password">...</widget>
</snap-form>
<focus> <snap-form> refid Define which widget should be given focus (may be overwritten with a GET parameter.) The widget to be focused is defined the widget with the identifier (id) as defined in the refid attribute of the focus tag. The focus tag is expected to always be an empty tag.

    <focus refid="login"/>
<taborder> <snap-form>   Define a list of tab indexes giving the order in which widgets should be selected when the tab key is used. The list of tab indexes is defined using <tabindex> tags.

<taborder>
  <tabindex refid="login"/>
  <tabindex refid="password"/>
</taborder>
<tabindex> <taborder> refid Defines the widget 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 index 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.

The system can help you find widgets that should be referenced in the list of tabindex tags and are missing.

<tabindex refid="name"/>
<accesskeys> <widget>   The list of accesskeys. It is made separate to make it easy to see which key is used for what widget in a single place.

<accesskeys>
  <key refid="email">e</key>
</accesskeys>
<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.

<key refid="email">e</key>
<widget> <snap-form> id
type		 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. The different types of widgets are defined using the type attribute (see table below.) The default type is "text".

<widget id="email" type="text">
  <default>contact@m2osw.com</default>
</widget>
<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 for that website is used. If the website has no default, "en" is assumed.

<label lang="fr">Votre nom :</label>
<background-value> <widget>   The value appearing in the background of the widget when it is empty. This is not supported in all browsers and in general requires JavaScript to run.

This value is often the name of the widget (i.e. username, password, email, address, etc.) so the user knows what to enter even if no label or description was given for that field.

<background-value>enter your email</background-value>
<sizes> <widget>   This tag includes a set of sizes as defined below.

<sizes>
  <min>10</min>
  <max>60</max>
  <width>30</width>
  <height>5</height>
</sizes>
<max> <sizes>   Defines the maximum length (in characters) that this field can be. If not defined, an infered 256 characters is enforced by the core system in order to prevent potential problems.

<max>60</max>
<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. 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.

<min>10</min>
<height> <sizes>   The expected height of the input widget. By default this is in characters (number of lines.) You may specify the unit after the value. We support two units: "px" (pixels) and "em" (font metrics, i.e. characters.)

<height>120px</height>
<width> <sizes>   The expected width of the input widget. By default this is in characters.You may specify the unit after the value. We support two units: "px" (pixels) and "em" (font metrics, i.e. characters.)

<width>80em</width>
<state> <widget>   The state of the widget. By default widgets are enabled. The following are the different available states:

  enabled -- the widget is editable
  disabled -- the widget is visible, but not editable (grayed out)
  visible -- the widget is visible, but not displayed as editable (usually only text fields to display some text in a form)
  hidden -- a hidden field with a value

<state>disabled</state>
<description> <widget> lang The 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. Then 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.

<description>Please enter your complete email address in this field.</description>
<help> <widget> lang The 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. Then 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.

<help lang="en-US">Please enter your complete email address in this field. The email address must include your user name and your domain name separated by the @ character.</help>
<filter> <widget> mode Define a set of parameters that constrain the possible data entry in this field. The mode defines how the data is being checked. The mode can be defined as one of the following values:

  immediate -- immediately check, this is the default
  blur -- check when losing focus
  fieldset -- check when existing the fieldset
  post -- checked just before posting

The primary reason for using a mode other than the default (immediate) is to be able to check several values to determine whether the value is acceptable.

<filter mode="blur">
  <regex>[0-9]+</regex>
</filter>
<regex> <filter> match 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".

<filter>
  <regex match="no">some-bad-word</regex>
</filter>
<min> <filter> mode Minimum value allowed. The mode attribute defines the type of check: string, integer, float are allowed.

<filter>
  <min>0</min><!-- positive only -->
</filter>
<max> <filter> mode Maximum value allowed, the field is expected to be numeric. The mode attribute defines the type of check: string, integer, float are allowed.

<filter>
  <max>100</max>
</filter>
<validate> <filter>   Run the validate code and if it returns true, it is considered valid. The code is written in JavaScript and it has access to all the fields in the form (however, other fields should NOT be accessed if you defined your filter with mode immediate.)

The following example accepts odd numbers only.

<filter>
  <validate>
   <[DATA[return (value % 2 == 1);]]>
  <validate>
</filter>
<latest> <widget>   List of latest values for a dropdown feature.1

<latest>
  <value>Blah</value>
  <value>Foo</value>
</latest>
<value> <latest>   One of the latest values. Any number of <value> can appear. The order is kept. We may offer a sort feature in some way although by default the order is expected to be newest to oldest (top to bottom.)

<value>Blah</value>
<value> <widget>   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 its defaults.

<value>Current Value</value>
<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.

<default>Default Value</value>
<select> <widget>   Offer a way to select a set of values. The values can be grouped. The filter <min> and <max> tags are used to define how the select behaves. When both are one (1) then exactly one entry must be selected. This can be represented by radio buttons. When <max> is undefined, then any number can be selected. This is represented by check boxes. The widget type attribute can be used to define how the select should be displayed (buttons, list, dropdown, etc.)

Note that either way you could use an HTML list widget, but HTML lists are notoriously unfriendly.

<select>
  <group name="Country">
    <value>US</value>
    <value>Canada</value>
  </group>
  <group name="Continent">
    <value>North America</value>
    <value>Europe</value>
  </group>
</select>
<group> <select> name Group a set of values. The name attribute defines the name of the group (in a dropdown it appears in bold non-indented.)

<group name="Country">
  <value>US</value>
  <value>Canada</value>
</group>
<value> <select>   The value of this entry. This is the words that appear for that possible selection.

<value>Canada</value>
<value> <snap-form> name A named value defined in the form as a whole. This value is never sent to the client. It is generally used to verify that the client does not temper with some of the widget values because if it does then we know that the POST is from a hacker and we can ignore it. This tag is used by any value that is to be kept secret by the server.

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 defaults to text if undefined.

Type Comments
text A simple text field. By default only 1 line of text. The number of lines can be increased using the <sizes> tag. If larger than 1, then in HTML a textarea is used.
password A simple text field displayed as a password. This means the text is not visible as you type it. Instead the computer shows you bullets or stars as you type your password, but not the password itself.
clear-password Similar to a password, but the field let you see what you type. It changes only once you exit the field (on blur.) If you come back to the field, what you typed reappears.
number The user can only type digits, eventually accepts a sign and decimal digits after a decimal point. By default this is a text field, but it could also be displayed using a slider, +/- buttons, etc.
list A selection using a list (<select> tag in HTML,) checkboxes, radio buttons. The minimum and maximum definitions are used to determine the exact type (i.e. exactly 1 selection can be radio, drop down, list were only one item can be selected, etc.)
date A date parameter which generally appears as a dropdown calendar where you can select a date. Depending on the date format and the different types of dates you offer in that field, the field may also be directly editable, or each parameter (day, month, year) may be drop down lists.
file Allow for a file selection (Browse or drop down). This forces the form to a multi-encoding scheme so all the data can be sent to the server (although if we use AJAX that doesn't matter as much.)
button Define a button that the user can click on. Note that buttons can be created using links and CSS, so this is not automatically a HTML button in the final form.

 

  • 1. This can be a problem with most browsers that already offer a dropdown of their own. We can circumvent this by changing the name of the fields each time the user goes to the form or by developing our own widget in JavaScript.

Snap! Websites
An Open Source CMS System in C++

Contact Us Directly