AdminWebModule JQuery plugins

The default EntityModule web resources add some JQuery based javascript plugins.

EntityModule object

All EntityModule and BootstrapUiModule javascript can be initialized by calling EntityModule.initializeFormElements(). This method optionally takes an argument that is the node in which the form elements should be initialized.

This is automatically done on document load, but when using AJAX fragment rendering, you usually want to re-initialize the DOM element that was updated.

Custom initializers

You can easily add a custom initializer function by adding it with EntityModule.registerInitializer( callback ). There is no need to manually execute your callback on document load, as that will happen automatically by the EntityModule.

Don’t execute your callback on document load and then add it to the initializers. Execution will happen automatically when calling registerInitializer().
Example registering a custom initializer that configures a sortable table to use AJAX loading
EntityModule.registerInitializer( function( node ) {
    $( '[data-tbl-type="paged"]', node )
        .on( "emSortableTable:prepareData", function( e, params ) {
            console.log( "enhancing the data", params );
            params['_partial'] = 'content';
        } )
        .on( "emSortableTable:loadData", function( e, params ) {
            console.log( "performing ajax load" );
            e.preventDefault();

            $.get( '#', $.param( params, true ), function( data ) {
                   $( '.pcs' ).replaceWith( data );
                   // initialize the form elements in the element just updated
                   EntityModule.initializeFormElements( $('.pcs') );
               }
            );
        } )
} );

Sortable tables

The default list views support paging and sorting of the pages, where client-side code is used to trigger reloading of the page.

Every table matching the selector [data-tbl-type="paged"] will be initialized for sorting and paging. A sortable table considers 3 default parameters:

  • page: page number

  • size: number of results a single page should have

  • sort: array of sort strings: field,direction (eg. name,ASC)

If a table is bound to a form (specified by the data-tbl-form attribute), paging or sorting will result in that form being submitted with the parameters being added as hidden form elements. If no form is bound, the current URL will be reloaded and the parameters added to the query string.

Customizing behaviour

You can hook into the default behaviour by using the events a sortable table emits or listens to.

Event Description Argument

emSortableTable:moveToPage

Trigger this event if you want to reload the data for a specific page.

Page number.

emSortableTable:sort

Trigger this event if you want to reload the data with different sorting. If the data is already sorted on the field specified, the sort order will be reversed.

Name of the field to sort on. Usually value of the data-tbl-field attribute.

emSortableTable:prepareData

Called after determining page number, result size and fields to sort on. Subscribe to this event if you want to expand or modify the parameters that should be submitted.

Parameter map containing: page,size and sort keys.

emSortableTable:loadData

Called after the parameters for the data have been prepared. Subscribe to this event if you want to provide a custom method of fetching the data (eg AJAX based). Note that you have to prevent the default execution if you provide your own mechanism.

Parameters that should be used for fetching the data.
Manually creating sortable tables

If you want to manually initialize a sortable table you can directly call the JQuery plugin emSortableTable() on any element.

You can easily create the valid structure for a sortable table using the EntityViewElementBuilderHelper. This allows you to create a SortableTableBuilder that builds a ViewElement that renders the right markup including all data attributes.

A valid sortable table requires several data attributes to be present on the DOM element:

Attribute Description

data-tbl

Unique id of the data table. Also used on column headings and pager control elements to specify the table they belong to.

data-tbl-form

(Optional) Name of the form that should be submitted when reloading the table data.

data-tbl-total-pages

Total number of pages in the result set.

data-tbl-size

Single page size.

data-tbl-current-page

Current page number (0 based).

data-tbl-sort

Current sort value. This is a JSON object structure containing the actual sort fields and their order. Depending on the the presence of custom Sort.Order.class attributes on the EntityPropertyDescriptor these field names will be the same as the property names.

data-tbl-field

Only used on heading cells that should be sortable. Specifies the field this column represents.

data-tbl-sort-property

Only used on heading cells that should be sortable. Contains the actual property name that is being sorted on. Usually the same as the field name.

data-tbl-page-selector

Used on a pager text field that contains the page number.

data-tbl-page

Used on any element that should navigate to a page on a click event. Contains the value of the page that should be navigated to.
« Web resources Javascript plugins Attributes overview »