Reactor Implementation Guide
Sortable allows records to be sorted.
Sortable( "dataFieldName" ; "sortFieldName" {; bgColor ; separatorColor; rowHeight ; advancedOptions } )
| 1 | dataFieldName | The name of the FileMaker field containing the data to be displayed for sorting, in "TableOccurrence::FieldName" format. The data stored in this field may be simple values, or it may be HTML code designed to give a certain rendered appearance in the sorter. |
|---|---|---|
| 2 | sortFieldName | The name of a field that will be used to adjust the order of the records. After each time the user moves a record to a new position, this field will be re-serialised to set the desired order. Note that the new values will start from 1, 2, ... etc., and only records that were displayed in the sorter will be updated. Therefore multiple records in the table may have a sort value of (for example) "1", and so the sort value will only make sense in the context of the correct found/related set of records. |
| 3 | bgColor (opt) |
Background color of the web viewer. Use any HTML-compatible color specification, .e.g. "green" or "#f2f3f4" |
| 4 | separatorColor (opt) |
Color of the separator lines used between rows in a simple vertical sorter. Use any HTML-compatible color specification, .e.g. "green" or "#f2f3f4" |
| 5 | rowHeight (opt) |
Height of each sortable element. Value should be a number, which will be interpreted as a height in pixels. |
| 6 | advancedOptions (opt) |
Parameter allowing advanced usage, e.g. specifying CSS overrides and special jQuery UI options. See below for further info. |
Example:
Advanced options can be passed to the BlackBox in the final optional parameter. Generally speaking, the use of advanced options requires a reasonable knowledge of CSS, JavaScript, and probably the behavior of the jQuery UI Sortable interaction module. If this is not you, stop reading now!
The value of the AdvancedOptions parameter must be a JSON-formatted object (see? told you!) containing any or all of the advanced parameters listed below.
Current advanced options are:
Note that in order to use the AdvancedOptions parameter, the bgColor and height positional parameters must be supplied. They can be given blank values, as in the examples below. If they do have values, these will be applied after the Advanced Options have been taken into account. e.g. if you specify a bgColor, it will be applied after any CSS overrides, and may supersede a background color supplied that way.
A block of CSS can be passed in order to extend and/or override the default CSS for the sorter (see below for the default CSS styles).
Example: specify a different background color for the sorting boxes by overriding the default rule.
Sortable( "Parameters::Name" ; "Parameters::sort_order" ; "" ; "" ; "" ; "{ css : '.ui-sortable li { background-color: lightblue; }' }" )
The jQuery UI sortable() method supports a number of optional parameters, some of which may be useful in advanced applications. These options can be supplied through the Sortable BlackBox's Advanced Options parameter by passing them as a quoted string named sortable_options.
Example: by default the Sortable BlackBox restricts dragging to up and down by using the jQuery UI Sortable option axis: 'y'. You can override this by passing that option yourself. Specify 'x' for left and right, or false to allow dragging in both directions (note that 'x' or 'y' should be quoted, but false should not: it's a JavaScript boolean value.)
Sortable( "Parameters::Name" ; "Parameters::sort_order" ; "" ; "" ; "" ; "{ sortable_options : 'axis : false' }" )
Example with both css and sortable_options specified:
Sortable( "Parameters::Name" ; "Parameters::sort_order" ; "" ; "" ; "" ; "{ css : '.ui-sortable li { background-color: lightblue; }', sortable_options : 'axis : false' }" )
A complex example: css (sourced from a FileMaker field) and sortable_options are used to present a 2-dimensional sorter with rectangular gray boxes.
Sortable( "Parameters::Name" ; "Parameters::sort_order" ; "" ; "" ; "" ; "{ css : '"& Settings::function_css &"', sortable_options: 'axis: false' }" )
The field Settings::function_css contains the CSS below. One very important feature is the use of float: left; to cause the sorter to work in two dimensions instead of just up and down.
.ui-sortable li {
list-style-type: none;
float: left;
border: none;
background-color: lightgray;
margin: 3px;
padding: 2px;
width: 40px;
}
.ui-sortable li.ui-sortable-helper {
border: none;
background-color: lightgray;
}
.ui-sortable li.ui-sortable-placeholder {
border: none;
width: 40px;
background-color: white;
}
NOTE: as well as option parameters, the jQuery UI Sortable interaction supports event and method parameters. Technically you can also use sortable_options to pass these through to the jQuery UI Sortable interaction, although this should be done with caution.
An example of this approach is the BackBox Builder function parameter sorter: it uses the jQuery UI Sortable interaction's update method to hook in an inline JavaScript function that checks the placement of optional parameters after each re-ordering operation, and when it is done, it calls the Sortable BlackBox's built-in update function, UpdateAfterSorting(), to finish the job of updating the FileMaker record data.
You can supply a piece of JavaScript code to be executed immediately after the Sortable BlackBox is initialised. (NB This is distinct from the 'start' event for the jQuery sortable interaction: that event only fires when the user starts dragging an object.)
The JavaScript code should be supplied as a single-quoted string, which will be eval()ed after the list items have been loaded and set up in the web viewer.
Example:
Sortable( "Parameters::Name" ; "Parameters::sort_order" ; "" ; "" ; "" ; "{ startup_code: 'alert( \'It has begun!\' );' }" )
The following advanced options allow you to place snippets of HTML in useful spots within the sorter:
The HTML element that becomes the sorter is a <ul> element. before_list_html and after_list_html allow you to place snippets before and after this element. start_of_list_html and end_of_list_html allow you to insert HTML elements that become, respectively, the first element inside the <ul>, and the last element before it closes.
NOTE:The visual layout behaviour of after_list_html is somewhat unpredictable, probably due to the way it interacts with DOM manipulations performed by the jQuery UI Sortable interaction. Probably best to be avoided.
Example: the BlackBox Builder uses a Sortable BlackBox that is customised in a number of ways for re-ordering function parameters. To display the name of the function (sourced from a FileMaker field), and also parentheses at either end of the parameter sorter, the following AdvancedOptions are used:
"start_of_list_html: '<span style=\\\"float: left\\\">"& Functions::canonical_name &"(</span>', "&
"end_of_list_html: '<span style=\\\"float: left\\\">)</span>', "&
Note that these are <span> elements, not <li>. A sortable_option AdvancedOption ( items: 'li' ) is also used to specify that only <li> elements are draggable, so these markers keep their place at the start and end of the parameter list.
html, body, ul, li { border: 0; margin: 0; padding: 0; }
html, body {overflow: hidden;background: white;
}
#sortable_list {
width: 100%; height: 100%;
position: absolute;
overflow: auto;
border: 0;
}
/* Default styles, which reproduce the appearance of a FileMaker portal with default font settings. */
.ui-sortable li {
line-height: 14px;
padding-top: 0px;
padding-bottom: 2px;
padding-left: 1px;
border-bottom: 1px solid black;
font-family: Helvetica; font-size: 11px; color: black;
white-space:nowrap;
background-color: white;
list-style: none;
}
.ui-sortable li.ui-sortable-helper {
border-top: 1px solid black;
border-bottom: 1px solid black;
background: rgba(255,255,255,.9);
color: rgba(68,68,68,.5);
}
ui-sortable li.ui-sortable-placeholder {
border-bottom: 1px solid black;
height: 14px;
background-color: #eee;
}
Comments