Documentation: xw-browse-API

The helper-plugin "xwctrl" serves for initialization of xw-browse, as well as – if used without parameters – for access to the xw-browse-API.

Initialization of xw-browse at the placeholder (here: <div id="idbrowse"/>):
$("#idbrowse").xwctrl( { ctrlType: "browse", ... } );

Parameters (properties of initialization-object):

• ctrlType (Type: String)
  For the xw-browse the string "browse" must be passed always.
• rows (Type: jQuery)
  The browse-rows as XML-elements, encapsulated in a jQuery-object; each XML-element represents a row. The raw data for the cells of a row can be contained as attributes of the XML-row-element and/or in its direct child elements. However, the API is only completely usable if all values are contained as values of child elements. The assignment of cells to columns is done by the XML-meta-description (see property "meta"). Special cases (e.g. multiple attributes/child elements at one cell or presentation of special values as graphics) as well as special formatting of non-standard-datatypes (not covered by "meta") can be achieved by an own formatting function.
• meta (Type: jQuery)
  Meta informations about the rows (property "rows") as XML, encapsulated in a jQuery-object; "meta" describes how to deal with values of "rows". An example can be found in element "xw-meta" at tab "XML" at Demo 1.

  The element encapsulated in "meta" (its name doesn't matter) defines the meta information in its direct child elements (cardinality is given in brackets) as follows:

  col-elements (1-n)

  Example:

  <col dt="int" grp="false" h="ID" s="pk"/>
  <col dt="date" h="Start" s="startdate"/>

  The col-elements describe the columns of the browse, as well as their order. Following attributes are evaluated:

  • dt (Type: string, Default: string)
    Datatype of column-values; if formatter "xw.format" is used, the standard datatypes will be evaluated.
  • grp (Type: bool, Default: true)
    Flag for columns containing numerical values, whether digits of values shall be grouped according to the current localization (e.g. thousands separator as in "1,000,000" with english locale).
  • scale (Type: int, Default: 2)
    Scale of floating-point numbers (amount of decimal places).
  • h (Type: string)
    Column headline; if notation ":resourceGroup:resource" is used, a javascript-defined resource is used as headline (see "Internationalization").
  • s (Type: string)
    Simple selector to retrieve a column value of an XML-row. Possible selectors are the name of a direct child element of a row (to select the contained textnode-value) or – if the desired value is contained as row-attribute – the attribute's name with prefix "@" (e.g. "@attname"). Other selectors are not allowed. As far as no additional attribute "class" is given at the col-element, the string given with "s" is used as CSS-class-name for the column, e.g. to define the column's width with CSS.
  • class (Type: string, Default: {Wert aus Attribut "s"})
    If the string given with "s" shall not be used as CSS-class-name for the column (for each cell contained in the column and for the column headline), a divergent CSS-class-name can be defined here.

  sort-elements (0-2)

  Example:

  <sort ascending="false" s="startdate"/> 

  The optional sort-elements define how the XML-rows are sorted - this allows the correct setting for the sort-arrows after initialization. Up to two sort-elements are allowed to express a max. two-stage sorting. If the xw-browse-property "initialSort: true" is set during initialization, the browse's rows are actively sorted according to its sort elements. Otherwise the rows are assumed to be already sorted (e.g. because they are selected with SQL "order by" at server-side) for reasons of optimisation and efficiency.
  Following attributes will be evaluated:

  • s (Type: string)
    Simple selector for access to a column value (see col-elements). The datatype of the corresponding col-element (that with the same selector) will be regarded for sorting.
  • ascending (Type: bool, Default: true)
    Ascending sort?
  • cs (Type: bool, Default: false)
    Sort is case sensitive?

  key-elements (1-n)

  Example:

  <key s="pk"/>

  key-elements describe a (potentially compound) key, which identifies uniquely a row. They are used for API-function selKeys() (delivers key-values of selected rows). As an alternative selected rows can be delivered by API-function selElements(), which returns complete rows. Keys are especially important, if "entity-Events" for "business entities" shall be used (see property "datatype" and "Business Entities" below).

  Attribute "s" at the key-element is – unlike the "s" in sort-elements – a simple selector, working like the selector for col-elements. The keys may – but don't have to – be defined as columns by the col-elements, i.e. they don't have to be visible in the xw-browse.

  xw-browse uses the selector "s" additionally as name for the key. The name must be usable as javascript-property-name. If the selector is not appropriate for this purpose or a divergent name is desired, the name can be notated as additional attribute "name" instead.

• datatype (Type: string)
  

  Optional: define an entity-datatype. If used, xw-browse reacts to events "entities-deleted" and "entity-updated", i.e. corresponding rows are deleted or updated when the events occur.

  The given name of the datatype must be usable as CSS-class-name since it is added as CSS-class-attribute (with prefix "xw-datatype-") to xw-browse (to the HTML-placeholder-DIV).

  See "Business Entities" below.

• selectFirstRow (Type: bool, Default: true)
  Select first row of xw-browse after initialization?
• initialSort (Type: bool, Default: false)
  When "true" (and the meta-description contains sort-elements), xw-browse will be sorted during initialization. The default ist "false", because in many cases the rows are already sorted (by SQL) at the server-side.
• singleSelection (Type: bool, Default: false)
  When "true", the xw-browse is restricted to single-selection. Otherwise, multiple rows can be selected at a time.
• browseResizable (Type: bool, Default: true)
  Shall the xw-browse be resizable by mouse? If "true", it can be resized by dragging the right or bottom edge as well as the bottom right corner. Requires jQuery UI-plugin "Resizable".
• colsResizable (Type: bool, Default: true)
  Shall the columns be resizable in their widths by dragging their delimiters? Requires jQuery UI-plugin "Resizable".
• colsSortable (Type: bool, Default: true)
  Allow drag and drop of column headlines to resort the columns? Requires jQuery UI-plugin "Sortable".
• extraSpaceVertScroll (Type: bool, Default: true)
  The width of xw-browse is computed automatically. When "true", some extra space for a possible vertical scrollbar is added.
• maxRowsPerPage (Type: int, Default: 15)
  The height of xw-browse is computed during initialization and when adding rows. maxRowsPerPage controls how many rows are visible at a time; if the browse contains more rows, it doesn't grow anymore and get a vertical scrollbar instead.
• brwsMinWidth (Type: int, Default: 40)
  Least width of xw-browse in pixel (can't be resized smaller).
• brwsMinHeight (Type: int, Default: 47)
  Least height of xw-browse in pixel (can't be resized smaller).
• attribNameSel (Type: string, Default: "xwuisel")
  Selected rows are internally marked with an attribute directly in the XML-rows. In the unlikely case of a name collision (a data-attribute in the XML-rows has same name), a divergent name for the mark-attribute can be defined here.
• tabIndex (Type: int, Default: 0)
  Sets the HTML-attribute "tabindex" for the xw-browse. The tabindex controls order of focusing, when "next" HTML-element is made active by tab-key.
• connectButtons (Type: bool, Default: false)
  When "true", the xw-browse will be connected to buttons defined in an HTML-button-browse (see demo 2 "Button-Browse"). The buttons will be prepared to react to the events "xwSelChanged" and "xwDoStdButton" (see "Events"). When selection changes, the enabled-state of the buttons is recomputed/set; a double-click on a row simulates a subsequent click on the first button (provided it is enabled). "xwSelChanged" is already triggered after initialization to set the correct enabled-states to the connected buttons. Buttons are expected to be already initialized jQuery UI-Buttons. If other buttons shall be used, the object xw.buttonState can be replaced with an appropriate object.
• formatter (Type: function)
  Return: string|null
  Function for formatting cell values. The formatter "xw.format" can be used to handle standard datatypes (see library xw.js).
  If no formatter is set, the raw data of the XML-rows will be rendered.

The properties ctrlType, rows and meta are mandatory. Setting a formatter is optional; for dealing with standard datatypes, the standard formatter "xw.format" must be set (see demo) or can serve as base for an own formatter.

The meta-description allows to specify a datatype per column (attribute "dt" in col-elements). xw-browse uses that information – in conjunction with localization – for correct formatting of raw data, as well as for correct sorting. The "standard datatypes" are documented here and are interpreted by the formatter xw.format and by the internal sort-function.

xw-browse can be globally localized by setting a locale-object as follows:

xw.locale = { 
  name: "de", 
  currency: "\u20AC", 
  decimalSep: ",",
  decimalGroup: ".",
  dateOrder: [2, 1, 0],
  dateSep: ".",
  bool: ["nein", "ja"]
};

Default is the english locale with currency EURO; however, currency is not relevant for xw-browse.

xw.locale = { 
  name: "en",
  currency: "\u20AC",
  decimalSep: ".",
  decimalGroup: ",",
  dateOrder: [1, 2, 0],
  dateSep: "/",
  bool: ["no", "yes"]
};

For xw-browse, the active locale controls how the standard datatypes are formatted.

There is a feature for multilingual sites in order to define text-resources in the currently active language with Javascript. The resources are organized in resource groups:

xw.i18n.brwsHeader = { 
  number: "nummer",
  course: "Kurs",
  fee: "Gebühr €"
};

xw-browse allows to use resources for column headlines by defining the headlines in the column-meta-information with the special notation ":resourceGroup:resource":

<col dt="int" grp="false" h=":brwsHeader:number" s="pk"/>
<col h=":brwsHeader:course" s="name"/>
<col dt="money" h=":brwsHeader:fee" s="fee"/> 

To avoid problems with special characters, the resource groups should be directly embedded in <script>-tags in the HTML-page (with its charset). Empirically, a simple way to avoid encoding problems is to use "utf8"-charset everywhere.

If the feature shall not be used (e.g., because you need a headline that starts with a colon), the first colon must be doubled ("::brwsHeader:number" will not be replaced with a resource, but the text ":brwsHeader:number" is set as headline).

Of course, resource groups can be used in own code, too; to access a resource, use a function-call like:

var myText = xw.i18n.resolve(":brwsHeader:number");

If a string, which doesn't match the above notation for resource-access, is passed to the resolve-function, the string itself is returned.

The API is a "plain object", whose properties are the functions described below. Access to the API (here for the browse-placeholder <div id="idbrowse"/>) can be achieved after initialization with
var browseApi = $("#idbrowse").xwctrl();

The API offers following functions:

• cloneRows (Type: function)
  Return: jQuery
  Creates a copy of all contained XML-rows, returned encapsulated in a jQuery-object. Potentially contained selection-attributes are removed from the copy.
• colMeta (Type: function)
  Return: object-array
  Returns the meta information for columns in an array of plain objects; additionally to the column-infos given at initialization time (see col-elements), the objects have a property "width" with the current column widths (in pixels).
• deleteRows (Type: function)
  

  Deletes the XML-rows which correspond to the keys in the passed key-array.

  Column-values of the XML-rows must be contained in direct child elements of the rows (not in attributes).

  Parameters:

  • key (Type: object-array)
    Array of "plain objects" with key-value-pairs identifying the rows to be deleted, e.g. [{ pk: "7" }, { pk: "12" }]; values must be passed as "string".
• deleteSelected (Type: function)
  Deletes selected rows from the browse.
• findRow (Type: function)
  Return: jQuery|null
  

  Finds the (first) XML-row which matches the key and returns it, encapsulated in a jQuery-object. Returns null if none is found.

  Column-values of the XML-rows must be contained in direct child elements of the rows (not in attributes).

  Parameters:

  • key (Type: object)
    "plain object" with key-value-pairs identifying the desired row, e.g. { pk: "7"}; values must be passed as "string".
• insertRows (Type: function)
  

  Adds (multiple) new rows (sorted, where required) to the browse. See the demo for an example.

  Parameters:

  • r (Type: jQuery)
    The new XML-rows, encapsulated in a jQuery-object.
  • selFilter (Type: {jQuery-filter-parameter})
    

    Optional: defines, which rows are to be selected after insertion. selFilter is passed to jQuery-function "filter" to find the rows to be selected (rows().filter(selFilter)).

    The function xw.filter() can be used to build a filter for searching XML-rows with a certain column-value (e.g. xw.filter("pk", "7") delivers the filter to find rows, which contain the value "7" in column "pk".

• jqItem (Type: function)
  Return: jQuery
  Delivers the jQuery-object encapsulating the xw-browse ($("#idbrowse") in the sample).
• optimalWidth (Type: function)
  Recomputes the browse metrics regarding optimal width of browse and horizontal scroll-area. Mainly used internally, the only known external use-case is the following:
  The xw-browse (or the containing area) may be hidden and is made visible (e.g. in a tab-panel). Such panels should call the function at all contained xw-browses when getting activated:
  panel.find(".xw-browse").each(function () { $(this).xwctrl().optimalWidth() });
  The reason is, that zooming of the browser-window (e.g. with keys Ctrl-"+"/"-") doesn't modify the width of scrollbars proportionally; that can lead to a suboptimal presentation.
• redraw (Type: function)
  Redraws the rows (e.g. to reflect updated XML-rows).
• replaceRows (Type: function)
  

  Replaces the rows of the browse with the passed XML-rows. When required, the browse is sorted afterwards.

  Parameters:

  • r (Type: jQuery)
    The new XML-rows, encapsulated in a jQuery-object.
• rows (Type: function)
  Return: jQuery
  Delivers all XML-rows (no copy), encapsulated in a jQuery-object.
• selAll (Type: function)
  Selects all rows in the browse, provided multi-selection is allowed.
• selElements (Type: function)
  Return: jQuery
  Delivers the selected XML-rows (no copy), encapsulated in a jQuery-object.
• selKeys (Type: function)
  Return: object-array
  Delivers the keys of the selected XML-rows as an array of "plain objects". The function needs a correct key-element-definition at browse initialization for proper use. The name (or selector) given in the key-elements is used as property name in the plain objects, e.g. [{pk: "3"}, {pk:"7"}] is returned, if a simple key with name "pk" was defined and the rows with pk=="3" und pk=="7" are selected. The properties always have Javascript-type "string".
• setInnerWidth (Type: function)
  

  Sets the inner width (width of horizontal scroll-area) of the browse.

  Parameters:

  • brWidth (Type: int)
    Width in pixels
• setLocalStyle (Type: function)
  

  Sets a local CSS-property, only valid for this browse (a HTML-style-element is inserted inside the browse-HTML; the selector is prefixed with the browse-ID; if the browse-placeholder doesn't have an ID, a unique ID is created and assigned).

  Parameters:
  • selector (Type: CSS-Selector)
    CSS-Selector, to be prefixed (notionally) with the browse-ID.
  • sdef (Type: string)
    style-definition(s)

  Example: If the column "startdate" was defined in the meta-information for this xw-browse, the call

  browseApi.setLocalStyle(".startdate", "width: 60px");

  adds the CSS-property "#idbrowse .startdate {width: 60px}" to the style-element inside the browse (this sets the columns width). If a style is set again, an already contained style with same selector is overwritten.

• setSelRowsVal (Type: function)
  

  Sets the passed value at all selected rows for the given column. Column-values of the XML-rows must be contained in direct child elements of the rows (not in attributes).

  Parameters:

  • el (Type: string)
    Name of the xml-row-child-element, where the column-value is to be replaced. If the child element doesn't exist at a row, it will be created.
  • val (Type: string)
    Column-value to be set.
  • opt (Type: object)
    Optional: "plain object", whose properties control the behaviour:
    • toggleBoolIfSingle (Type: bool, Default: false)
      Only for columns of type "bool": if { toggleBoolIfSingle: true } is passed and exactly one row is selected, parameter "val" is ignored. Instead of setting the passed value "val" the current value is read and inverted (a current column-value of "true" is set to "false" and vice versa).
    • splitLines (Type: bool, Default: false)
      Only for columns of type "string" with potential multiple-lines-content. If { splitLines: true } is passed, possibly in "val" contained newline-characters ("\n") are evaluated to split the value into multiple "line"-child elements, which are set as column-value. See xw.select() with option "allLines=true".
• sort (Type: function)
  Sorts the browse according to the current sort-settings.
• unselAll (Type: function)
  Unselects all rows of the browse.

The following events are triggered by the xw-browse:

• xwSelChanged
  The selection of rows changed. The event is also triggered after initialization, provided xw-browse was initialized with "connectButtons:true".
• xwDoStdButton
  A row has been double-clicked (whereby it also was selected) or the return-key was pressed and at least one row is selected. If xw-browse was initialized with "connectButtons:true", the event is evaluated by xw-browse itself ("click" is triggered for the first button of the button-browse, provided the button is "enabled").
• xwMenu
  

  A selected row was right-mouse-clicked; if an unselected row is clicked, no event is triggered (the browser's regular context menu is shown instead).

  In the event-handler with parameters (e, browse, li) the XML-row (encapsulated in a jQuery-object) can be accessed with

  var row = li.data("xd");

Here "Business Entities" mean data records (rows), which are tagged with a certain datatype (e.g. "customer") and have unique keys.

xw-browse can be initialized with property "datatype", where the name of an entity-datatype can be passed; this defines that the contained rows are of this certain datatype. When entities-deleted- or entity-update-events occur, the xw-browse automatically reacts with deletion or update of rows. In order to find affected rows, a correct key-definition is required at the meta-information (see initialization, property "meta").

See here for more information to business entities.