Jimbo.js Reference

jimbo.js is the JavaScript library of the Festi Framework. It defines one global object: Jimbo.

This page lists the functions and the events of Jimbo. For the full flow between the server and the browser, read these pages first:

What `jimbo.js` needs

jimbo.js uses these libraries. The theme must load them before jimbo.js.

Library	Used for
jQuery	All functions.
jQuery UI (`dialog`)	The loading indicator, `Jimbo.ui.dialog`.
Bootstrap 3 JavaScript (`modal`, `tab`, `tooltip`)	DGS dialogs, tabs, the error of a radio input.
qTip2	Error tooltips at form fields, `Jimbo.dialog()`.
SmartNotification (`jQuery.SmartMessageBox`, `jQuery.smallBox`)	Message boxes and notifications.

The SmartAdmin theme loads all of them. A different theme must do the same. Jimbo.initAjaxFilters() also calls the function pageSetUp() of the theme.

Start

The theme calls Jimbo.init() one time, when the document is ready. A plugin script does not call it.

jQuery(document).ready(function () {
    Jimbo.init({
        lang: {
            'Ok': 'OK',
            'Cancel': 'Cancel'
        }
    });
});

Option	Default	Use
`base`	`'/'`	The base URL. The default URL of a store object.
`debug`	`false`	`true` writes the log of `Jimbo.i()` and `Jimbo.e()` to the browser console. Use it only on a development computer.
`lang`	`{}`	The translations for `Jimbo.lang()`.
`langIdent`	`'en'`	The language code for date components.
`loading.selector`	`'#loadingBar'`	The element of the loading indicator.

Jimbo.init() does these things:

It prepares the action links of each DGS list in the page.
It adds the validation to each form with the class f-db-form.
It fires Jimbo.EVENT_ON_INIT.

A second call of Jimbo.init() does nothing.

The SmartAdmin theme calls Jimbo.init() without options. To change an option in a project, set the property of Jimbo.options in a script of the project:

Jimbo.options.base = '/admin/';

To see the log of jimbo.js while you look for a defect, type Jimbo.options.debug = true in the browser console.

To run code after the start, listen to Jimbo.EVENT_ON_INIT, or use jQuery(document).ready() in a file that loads after the theme files.

Replies of the server

Function	Use
`Jimbo.response(data)`	Processes a reply of the server. Returns `true` if the reply has an action.
`Jimbo.loadJson(url, callback)`	Shows the loading indicator, sends a GET request, and gives the JSON to `Jimbo.response()`. Then it calls `callback(data)`.
`Jimbo.ajax(url)`	Shows the loading indicator and loads the URL in a hidden `<iframe>`. Use it for an `onAjax` method. The reply calls `Jimbo.response()`.
`Jimbo.loadForm(actionName, url, callback)`	Loads the HTML of a DGS form into the page. Fires `Jimbo.EVENT_BEFORE_LOAD_FORM` first.
`Jimbo.redirect(url)`	Opens the URL.

Jimbo.ajax() has one argument, a URL. It is not a function with request options. For a POST request, use jQuery.post() or jQuery.ajax(), and give the reply to Jimbo.response().

Jimbo.showLoading();

jQuery.post('/orders/15/comment/', {text: text}, function (data) {
    Jimbo.response(data);
}, 'json');

Actions of a reply

Jimbo.response() reads the key type of the reply and does the action.

`type`	What `jimbo.js` does
`alert`	Shows a message box with `title` and `messages`. Then opens `url` or reloads the page (`reload`), after `sleep` milliseconds.
`notifications`	Shows each item of `messages` as a notification.
`redirect`	Opens `url`.
`reload`	Loads the page again.
`formError`	Shows the errors at the form fields.
`callback`	Calls the function with the name in `name`. The function gets the reply. See The action `callback`.
`content`	Adds the HTML in `content` to the end of `<body>`.
`dialog`	Adds the HTML in `content` to `<body>` and opens it as a jQuery UI dialog.

A reply can also have these keys, with each action or without one:

Key	What `jimbo.js` does
`notifications`	Shows each item as a notification.
`js`	Runs the text as JavaScript, after the action.
`eval`	Runs the text as JavaScript, before the action.

jimbo.js opens a url only if it is a path of the website, or an http: or https: URL. For a different scheme, such as javascript: or data:, it throws an error. This applies to the actions alert, notifications, and redirect.

The action `callback`

name is the name of a function, or a path with dots to a function of an object: onOrderSaved, Orders.onSaved. jimbo.js reads the path from window. It does not run name as JavaScript.

The function, or the first object of the path, must be a property of window. A function declaration and a var at the top level of a script are properties of window. A const, a let, and a class are not. For these, write window.Orders = Orders;.
A function of an object gets the object as this.
If name is not such a path, or window does not have the function, jimbo.js throws an error and calls nothing.

window.Orders = {
    onSaved: function (data) {
        jQuery('#order-' + data.idOrder).addClass('m-saved');
    }
};

Your own action

For a type that is not in the table, Jimbo.response() calls the function Jimbo.set<Type>Response(data), if it exists. The first letter of the type becomes a capital letter. An underscore starts a new word.

// The reply {"type": "ordersHighlight", "selector": "#row-5", "color": "red"}
Jimbo.setOrdersHighlightResponse = function (data) {
    jQuery(data.selector).css('background-color', data.color);
};

See Add your own action.

Events

Jimbo has an event bus. It uses jQuery events on document.

Function	Use
`Jimbo.addListener(eventName, callback)`	Adds a listener. The callback gets the jQuery event and then the parameters.
`Jimbo.fireEvent(eventName, params)`	Fires an event with one parameter. The parameter can be an object, an array, or a simple value.
`Jimbo.fireEvent(eventName, param1, param2)`	Fires an event with two parameters.

Jimbo.addListener('orders_changed', function (event, params) {
    console.log(params.idOrder);
});

Jimbo.fireEvent('orders_changed', {idOrder: 15});

The listener gets each parameter as it is. An array is one parameter. jimbo.js does not divide it into different arguments.

Jimbo.addListener('orders_selected', function (event, ids) {
    console.log(ids.length); // 3
});

Jimbo.fireEvent('orders_selected', [15, 16, 17]);

Jimbo.addListener('orders_moved', function (event, idOrder, idFolder) {
    console.log(idOrder, idFolder); // 15 4
});

Jimbo.fireEvent('orders_moved', 15, 4);

For more than two values, give one object.

Some events give an object that the listener can change. A changed property tells jimbo.js to skip its default behavior. The listeners run before jimbo.js reads the property.

Jimbo.EVENT_ON_INIT

Fired at the end of Jimbo.init(). No parameters.

Jimbo.EVENT_ON_DISPLAY_STORE_FORM

Fired by the DGS form template when a DGS form is in the page.

Parameter	Content
`store`	The ident of the store.
`mode`	The mode of the action.

Use this event to start the JavaScript of the form fields.

Jimbo.addListener(Jimbo.EVENT_ON_DISPLAY_STORE_FORM, function (event, params) {
    if (params.store !== 'orders') {
        return;
    }

    jQuery('.f-db-form-orders .e-field-color').each(function () {
        // Start the component of the field here.
    });
});

Jimbo.EVENT_OPEN_DIALOG

Fired by the DGS form template and by the HUI dialog template when a dialog opens. No parameters.

jimbo.js listens to this event to add the validation to the form of the dialog.

Jimbo.EVENT_BEFORE_CLOSE_DIALOG

Fired by the DGS form template when the dialog of a DGS form starts to close.

Parameter	Content
`event`	The Bootstrap event `hide.bs.modal`. Call `event.preventDefault()` to keep the dialog open.

Jimbo.EVENT_BEFORE_LOAD_FORM

Fired by Jimbo.loadForm() before it loads a DGS form. The parameter is the options object. A listener can change it.

Property	Content
`actionName`	The name of the DGS action.
`url`	The URL of the form.
`data`	The data that `jimbo.js` sends with the request.
`callback`	The function that runs after the load.
`override`	Set it to `true` to stop the load. Your listener then loads the form.

Jimbo.options.formOptions contains the options of the last call.

Jimbo.addListener(Jimbo.EVENT_BEFORE_LOAD_FORM, function (event, options) {
    if (options.actionName === 'edit') {
        options.url += '&source=list';
    }
});

Jimbo.EVENT_CALL_ERROR_FIELD

Fired for each item of fields in a formError reply, before jimbo.js shows the tooltip.

Property	Content
`input`	The jQuery object of the field.
`message`	The error message.
`override`	Set it to `true` to stop the tooltip. Your listener then shows the error.

Jimbo.addListener(Jimbo.EVENT_CALL_ERROR_FIELD, function (event, data) {
    data.override = true;

    data.input.next('.field-invalid-value-message').remove();
    data.input.after(
        jQuery('<div class="field-invalid-value-message"></div>').text(data.message)
    );
});

Jimbo.EVENT_CALL_GROWL

Fired by Jimbo.growlCreate() before the notification shows.

Property	Content
`caption`	The caption.
`description`	The text.
`persistent`	The third argument of `Jimbo.growlCreate()`.
`stop`	Set it to `true` to stop the default notification. Your listener then shows it.

The SmartAdmin theme uses this event to show the notification as a SmartAdmin small box.

Jimbo.EVENT_ON_DISPLAY_WIZARD_STEP

Fired by Jimbo.ui.wizard each time a wizard step shows, also for the first step. The parameter is the wizard object.

Property	Content
`currentStep`	The index of the step. The first step is 0.
`totalSteps`	The number of steps.
`tabPanes`	The jQuery object of the step panes.
`storeIdent`	The ident of the store.

Jimbo.addListener(Jimbo.EVENT_ON_DISPLAY_WIZARD_STEP, function (event, wizard) {
    if (wizard.currentStep === 2) {
        const pane = wizard.tabPanes.eq(wizard.currentStep);
        // Start the components of the third step here.
    }
});

Messages and indicators

Function	Use
`Jimbo.showMessage({title, message})`	Shows a message box with the button "Ok". `message` is text or an array of lines.
`Jimbo.growlCreate(caption, text, persistent)`	Shows a small notification. Fires `Jimbo.EVENT_CALL_GROWL`.
`Jimbo.displayDialog(title, message, callback, confirmCaption, cancelCaption)`	Shows a confirmation box. Calls `callback()` if the user confirms.
`Jimbo.showLoading()`	Shows the loading indicator of the page.
`Jimbo.hideLoading()`	Hides the loading indicator of the page. `Jimbo.response()` calls it.
`Jimbo.showLoadingBar(selector, options)`	Shows a loading indicator above one element. The element must have an `id`.
`Jimbo.hideLoadingBar(selector)`	Hides the loading indicator of that element.

Jimbo.displayDialog(
    Jimbo.lang('Remove the order?'),
    '',
    function () {
        Jimbo.loadJson('/orders/15/remove/');
    }
);

Jimbo.showLoadingBar('#orders-totals');

jQuery('#orders-totals').load('/orders/totals/', function () {
    Jimbo.hideLoadingBar('#orders-totals');
});

Jimbo.dialog(content, title) and Jimbo.confirm(options) show a qTip2 dialog. They are older functions. For a new dialog, use the HUI dialog on the server and the action content.

Forms

Submit without a page reload

jimbo.js has no handler that submits a form with the class f-form, and none will be added. A form with this class does a usual submit with a page reload.

To submit a form without a page reload, use the HUI form or the HUI dialog on the server. They submit into a hidden <iframe>, an onAjax method replies, and the reply calls Jimbo.response(). See Response.

Validation

jimbo.js adds validation to each form with the class f-db-form. The DGS forms and the HUI dialog have this class.

The validation uses the HTML attributes of the inputs: required, pattern, type, min, max, maxlength.
When the user submits the form, jimbo.js examines each input. If an input is not valid, the form does not submit.
An input that is not valid gets the CSS class m-field-invalid-value. The message shows in an element with the class field-invalid-value-message after the input.
jimbo.js examines an input again on each change.

Attribute of the input	Use
`data-error-message`	The message when a required input is empty.
`data-mismatch-message`	The message when the value has an incorrect format.
`data-inputmask`	The input mask (the Inputmask library).

Function	Use
`Jimbo.util.validateInputs(inputs)`	Examines the inputs (a selector or a jQuery object). Returns `true` if all are valid.
`Jimbo.util.doAttacheFormValidation()`	Adds the validation to each `f-db-form` in the page. Call it after you add a form to the page yourself.
`Jimbo.util.getFormData(selector)`	Returns the values of all inputs in the element, as an object: input name to value.

if (Jimbo.util.validateInputs('#step-1 :input')) {
    Orders.showStep(2);
}

Errors from the server

A reply with the action formError shows errors that the server found. See ACTION_FORM_ERROR.

Data Grid Store (DGS)

The store object

Function	Use
`Jimbo.getDataGridStoreInstance(ident, options)`	Returns the object of a store. The first call makes it.
`store.fireBackendEvent(eventName, params, callback, onError)`	Sends an event to the store on the server.
`store.getActionUrl(action, params)`	Returns the URL of a store action.

The DGS list template makes the object with the URL of the list (baseUrl). Thus on a list page, Jimbo.getDataGridStoreInstance('orders') is sufficient.

Option	Default	Use
`baseUrl`	The option `base` of `Jimbo`	The URL of the store.
`eventUrl`	`baseUrl`	The URL for `store.fireBackendEvent()` and `store.getActionUrl()`.

The options belong to that store only. They do not change Jimbo.options or a different store.
store.options contains a copy of Jimbo.options with the options of the store.
Only the first call for an ident makes the object. A later call returns the same object and ignores options.

const store = Jimbo.getDataGridStoreInstance('orders');

store.fireBackendEvent('EVENT_ORDERS_RECALCULATE', {idCustomer: 15}, function (response) {
    console.log(response.data);
});

See Fire a backend event of a DGS.

The list

jimbo.js prepares each link with the class e-db-action in a DGS list:

Attribute of the link	What `jimbo.js` does on a click
`mode="default"` or `mode="right"`	Loads the form of the action into a dialog (`Jimbo.loadForm()`).
`data-dialog="true"`	Shows a confirmation box and then calls the URL. The attributes `data-dialog-title`, `data-dialog-message`, `data-dialog-confirm-button-caption`, and `data-dialog-cancel-button-caption` set the texts.

The DGS templates write these attributes from the schema. You do not write them.

Function	Use
`Jimbo.onDisplayList()`	Prepares the action links again. Call it after you replace the HTML of a list.
`Jimbo.execGroupAction(element, url)`	Sends the selected rows (`.i-grouped-item:checked`) to the URL with a POST request.
`Jimbo.isDialogOpen()`	Returns `true` if a Bootstrap dialog is open.

Wizard

Jimbo.ui.wizard controls a DGS form with wizard steps. The form template calls Jimbo.ui.wizard.init(). On each change of step, the wizard sends the backend event EVENT_JIMBO_WIZARD_STEP_CHANGE to the store and fires Jimbo.EVENT_ON_DISPLAY_WIZARD_STEP.

Other functions

Function	Use
`Jimbo.lang(ident)`	Returns the translation from the option `lang`. If there is no translation, it returns `ident`.
`Jimbo.is(selector)`	Returns `true` if the page has an element for the selector.
`Jimbo.isCallable(value)`	Returns `true` if the value is a function.
`Jimbo.i(...)`	Writes to the console log, if `debug` is `true`.
`Jimbo.e(...)`	Writes an error to the console, if `debug` is `true`.
`Jimbo.util.fillString(text, values)`	For each key of `values`, replaces the first `%key%` in the text with the value. A second `%key%` with the same key stays in the text.

Rules

Use jQuery, not $, in your scripts.
Give each reply of the server to Jimbo.response().
Do not change jimbo.js. Add a function Jimbo.set<Type>Response or a listener in a file of your plugin.
Start the names of your actions and events with the name of your plugin.
Start the JavaScript of DGS form fields in a listener for Jimbo.EVENT_ON_DISPLAY_STORE_FORM.
Do not set the option debug to true in the code of a project.
Give the action callback a fixed function name that window has.
Do not use the class f-form to submit a form without a page reload. Use the HUI form or the HUI dialog with an onAjax method.