All you need to do is include the following:
<script src="jquery.js"></script> <script src="sugar.min.js"></script> <script src="widgets.min.js"></script>
And then use the proper classes and attributes to apply the widgets.
You need a class .integer:
<input class="integer"/>
The widget prevents invalid numbers being entered.
Optionally you can specify a data-range:
<input class="integer" data-range="0,100"/>
If a value outside the range is entered, an .error class is applied.
Note you can use a data-range also for numbers, dates, times, and strings.
All you need is a class .number:
<input class="number"/>
The widget prevents invalid numbers being entered.
Optionally you can specify a data-range:
<input class="number" data-range="0,100"/>
If a value outside the range is entered, an .error class is applied
Apply a class .slider to any .integer or a .number field and add a data-range attribute:
<input class="number slider" data-range="0,100,1"/>
It will display a slider on top of the input field.
It automatically figures out the precision (number of digits) from the range.
The third argument of the data-range is optional.
This widget requires "sugar.js".
Requires one of the following classes: .date, .time, .datetime plus, most importantly, a data-format attribute which must be in the "sugar.js" format. For example:
<input class="date" data-format="{dd}/{MM}/{year}"/>
<input class="time" data-format="{HH}:{mm}:{ss} {TT}"/>
<input class="datetime" data-format="{dd}/{MM}/{year} {HH}:{mm}:{ss} {tt}"/>
Note that despite the arbitrary representation for date/time/datetime, the actual value of the field is always expected to be in ISO format. On submission of the form, the data will be submitted in ISO format. If you optionally specify a data-range, the values of the range should also be in ISO format. The idea of the widget is to completely decouple the UI representation with the server-side handling (which must be in ISO format). To internationalize the widget, set the locale using "sugar.js".
You can specify a regex validator for any field (including dates) with a data-regex. For example you can specify a 5 digit zip code:
<input data-regex="^(\d{5})?$"/>
You need the class .tags.
<input class="tags" value="one;two;three" data-options="four;five" data-separator=";"/>
It will display dismissible tags on top of the input field.
The data-options is optional and lists suggested tags. It is not a constraint. To constrain tags simply use jQuery to hide the input field.
The data-separator is optional and defaults to ";".
You need a class .stars.
<input class="stars">
It will replace the input field with the standard 5 stars
The simplest way to use the autocomplete widget is the following:
<input class="autocomplete" data-source="[['one'],['two'],['three']]" data-mode="simple"/>
In this case the options are in an array of arrays of single options.
The data-source can be the name of a JS variable which contains the source:
<input class="autocomplete" data-source="myoptions" data-mode="simple"/> <script>myoptions=[['one'],['two'],['three']]</script>
Or, it may be be an URL which will fetch all the options in JSON at once:
<input class="autocomplete" data-source="url:options.json" data-mode="simple"/>
Or, it can be the URL of a search API which returns matches in JSON (always in the same 2d array format):
<input class="autocomplete" data-source="search:endpoint?s={1}" data-mode="simple"/>
({1} will be automatically substituted by the text typed in the input field).
The data-mode specifies the mode of operation of the autocomplete. When data-mode is "simple" then the autocomplete can contain any of the available options or any arbitrary text. When the data-mode is "keyed" then the value is replaced with a key that corresponds to the text being displayed, for example a record id. In this case the data-source must have two columns representing the text and the corresponding key, for example:
[['one',1],['two',2],['three',3]]
A third option for data-mode is "chained". This allows autocompleting of multiple words in arbitrary long text, one after the other.
The autocomplete widget uses a binary search client-side, enabling it to efficiently search milions of items even if they all sent via json at once. It can also autocomplete text containing spaces.
If you use a library that manipulates the DOM, the calendar and slider may break, in which case you should re-apply them when new input elements are injected in the DOM:
jQuery('.date,.datetime,.time').calendar();
jQuery('.slider').slider();
These functions take no argments.
jQuery(selector).change(function(){...});
To set the value of a widget (calendar, stars, tags) you can use the set event:
jQuery(selector).trigger('set',value);
Most of the widgets do not require styling as they adopt the style of the underlying element. They are easy to re-style with regular CSS and should work with any CSS framework without too much trouble. Here we are using them with stupid.css.