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. |
A theme loads all of them. Jimbo.initAjaxFilters() also calls the function pageSetUp() of the theme.
Load action-lock.js after jimbo.js. Without it, the grid actions are not held back. See Grid actions and ActionLock.
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.
A theme usually 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 avarat the top level of a script are properties ofwindow. Aconst, alet, and aclassare not. For these, writewindow.Orders = Orders;. - A function of an object gets the object as
this. - If
nameis not such a path, orwindowdoes not have the function,jimbo.jsthrows 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. |
A theme can use this event to show the notification in its own style.
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.
}
});
Jimbo.EVENT_ON_DISPLAY_CONTENT
The value is 'on_display_content'. Jimbo.prepareContent() fires it when a script puts new content into the page without a page load. The parameter is the DOM element that holds the new content.
The event fires before jimbo.js prepares the grid actions and before Jimbo.EVENT_ON_DISPLAY_STORE_FORM. Use it in a theme to set up its components in the new content, as the theme does on a page load.
jQuery(document).on(Jimbo.EVENT_ON_DISPLAY_CONTENT, function (event, root) {
jQuery(root).find('[rel=tooltip]').tooltip();
});
A theme starts its own components in the new content on this event.
Jimbo.EVENT_BEFORE_LOAD_LIST
The value is 'before_load_list'. dgs-list.js fires it before it fetches the rows of a grid. The parameter is an object. A listener can change it.
| Property | Content |
|---|---|
ident |
The name of the store of the grid. |
grid |
The DOM element of the grid. |
url |
The URL of the request. Change it to fetch a different URL. |
cancel |
Set it to true to stop the load. The grid and the address do not change. |
Jimbo.addListener(Jimbo.EVENT_BEFORE_LOAD_LIST, function (event, params) {
if (params.ident === 'orders' && hasUnsavedChanges()) {
params.cancel = true;
}
});
Jimbo.EVENT_ON_LIST_LOADED
The value is 'on_list_loaded'. dgs-list.js fires it after it puts the fresh rows into a grid. The event fires after Jimbo.prepareContent().
| Property | Content |
|---|---|
ident |
The name of the store of the grid. |
grid |
The DOM element of the grid. |
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(key) |
Starts a wait of the page and shows the loading indicator. key is optional. |
Jimbo.hideLoading(key) |
Ends the wait of key. Jimbo.response() calls it without a key. |
Jimbo.setLoadingIndicator(indicator) |
Sets the object that shows the waits. null sets the default again. |
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');
});
Loading keys
Each wait has a key. A call without a key uses Jimbo.LOADING_KEY ('jimbo'). Give your own key to a wait that ends in your own code. Then a hide of a different caller does not end your wait.
| Key | Caller |
|---|---|
'jimbo' |
Jimbo.loadForm(), Jimbo.ajax(), Jimbo.loadJson(), group actions, Jimbo.response(), and calls without a key. |
'dgs_list:<store>' |
DgsList, one key for each grid (DgsList.LOADING_KEY). |
'page_navigation' |
PageNavigation (PageNavigation.LOADING_KEY). |
'dgs_page_form' |
DgsPageForm (DgsPageForm.LOADING_KEY). |
Jimbo.showLoading('orders_totals');
jQuery.getJSON('/orders/totals/', function (data) {
Jimbo.hideLoading('orders_totals');
});
Loading indicator
The indicator is an object with two functions: show(key) and hide(key). Jimbo always gives the key.
- The default indicator,
Jimbo.defaultLoadingIndicator, is the modal loading bar of jQuery UI. It does not tell the keys apart. A hide ends all waits. loader.jssets its own indicator,PageLoader. It keeps each key as a separate wait. It hides the indicator only when all keys end.- The last call of
Jimbo.setLoadingIndicator()applies. The order of the scripts does not change this. A script that keeps a reference toJimbo.showLoadingalso uses the new indicator. - The global functions
showLoadingBar()andhideLoadingBar()stay for older scripts. They callJimbo.showLoading()andJimbo.hideLoading()without a key.
Jimbo.setLoadingIndicator({
show: function (key) {
jQuery('.my-loader').addClass('active');
},
hide: function (key) {
jQuery('.my-loader').removeClass('active');
}
});
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.jsexamines 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 classfield-invalid-value-messageafter the input. jimbo.jsexamines 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.optionsor a different store. store.optionscontains a copy ofJimbo.optionswith 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. |
Jimbo.closeStoreDialogs(store) |
Closes the open dialogs of the grid of the store. Each dialog of a grid has the attribute data-store="<store>". |
Grid actions and ActionLock
action-lock.js defines ActionLock. It holds back the grid actions while one action runs. Thus a second tap does not repeat a change or open a second form. The page has one lock. The key names the action that holds it.
| Function | Use |
|---|---|
ActionLock.lock(key, timeoutMs, onTimeout) |
Locks the page for the action key. Returns false when an action holds the lock, also the same action. timeoutMs and onTimeout are optional. |
ActionLock.unlock(key) |
Ends the lock of the action key. A key that holds no lock does nothing. |
ActionLock.isLocked(key) |
Returns true when the action key holds the lock. Without key, a lock of any action counts. |
Each lock ends at the latest after its time limit. Then ActionLock calls onTimeout. A hung request thus does not lock the page until a reload.
| Key | Action | Time limit |
|---|---|---|
Jimbo.ACTION_LOCK_FORM |
A link that loads a form (mode="default" or mode="right"). |
ActionLock.DEFAULT_TIMEOUT, 30 seconds. |
Jimbo.ACTION_LOCK_FRAME |
A link that runs in the hidden frame (Jimbo.ajax()). |
Jimbo.ACTION_LOCK_FRAME_TIMEOUT, 5 seconds. A download gets no load event of the frame. |
Jimbo.ACTION_LOCK_GROUP |
Jimbo.execGroupAction(). |
ActionLock.DEFAULT_TIMEOUT, 30 seconds. |
- The answer of the action ends the lock.
- A listener of
Jimbo.EVENT_BEFORE_LOAD_FORMthat setsoverrideends the lock of the form. ActionLockdoes not hide the loading indicator. When the time limit ends a grid action,jimbo.jscallsJimbo.hideLoading().
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.
Pages without a page reload
Prepare new content
Call Jimbo.prepareContent(root, defaultFormStore) after you put new content into the page. It does what a page load does for the content:
- It fires
Jimbo.EVENT_ON_DISPLAY_CONTENTwith the root element. - It prepares the grid actions and the group actions.
- It fires
Jimbo.EVENT_ON_DISPLAY_STORE_FORMwith the modenewwhen the content has a DGS form. The store comes from the<store>[performPost]field of the form, or else fromdefaultFormStore.
dgs-list.js and page-navigation.js call it after each swap.
dgs-list.js
dgs-list.js defines DgsList. A grid with the attribute data-ajax-list changes its rows without a page reload. Its filters, sort links and page links fetch the grid with popup=true. The script puts the fresh rows in place of the old rows and keeps the request in the address. A reload of the page thus shows the same grid.
Each load has these steps:
- It fires
Jimbo.EVENT_BEFORE_LOAD_LIST. A listener can change the URL or stop the load. - It closes the open dialogs of the grid with
Jimbo.closeStoreDialogs(). - It marks the rows as busy and fetches the grid.
- It puts the fresh rows in place and calls
Jimbo.prepareContent()for them. - It fires
Jimbo.EVENT_ON_LIST_LOADED.
When the fetch fails, the browser opens the page of the grid.
The theme sets its markup in DgsList.options. The script reads the options on each event.
| Option | Default | Use |
|---|---|---|
gridSelector |
'.b-db-table[data-ajax-list]' |
The grids that load without a page reload. |
rowsSelector |
'.b-dgs-container-rows' |
The element in a grid that holds its rows. |
filtersFormSelector |
'form.e-dgs-filters[data-store]' |
The filters forms. The data-store of a form is the store name of its grid. |
filterInputSelector |
'.e-dgs-field-filter' |
The filter inputs of a grid. They get the class form-control when the filter panel opens (FilterPanel.EVENT_OPEN). |
linkSelector |
'a[href]' |
The links in a grid that can change the sort order or the page. |
| Function | Use |
|---|---|
DgsList.load(ident, url) |
Fetches the grid of the store for the URL and puts its rows in place. |
DgsList.refresh(ident) |
Fetches the grid again for the current address. It returns false when the page has no such grid. |
page-navigation.js
page-navigation.js defines PageNavigation. A link to a different page of the same area opens without a page reload. The script fetches the page, puts its content in place of the current content, and adds a history entry. The title and the menu follow the page. Back and Forward swap the pages again.
The script does nothing until an area registers. An area registers from its own script:
window.pageNavigationAreas = window.pageNavigationAreas || [];
window.pageNavigationAreas.push({
pattern: /^\/shop\/\d+\/orders\//,
script: document.currentScript.getAttribute('src')
});
- A page takes part only when it loads the script of the area.
- A link outside the area loads the page.
- A link with the class
e-page-full-load(PageNavigation.FULL_LOAD_CLASS) always loads the page. Use it for a page that must load fully, for example a payment page that sends the user to Stripe. - The pattern must match the same prefix of both paths. Thus
/shop/1/orders/and/shop/2/orders/do not share the area. - The script adds the scripts and styles that the fetched page needs before the swap.
- A page with a different version of a loaded script or style loads the page.
The theme sets its markup in PageNavigation.options before the document is ready:
| Option | Default | Use |
|---|---|---|
contentSelector |
null |
The element that holds the content of the page. The theme sets it. Without it, no page is swapped in place. |
menuLinkSelector |
null |
The menu links. Each link must have an id. Without this option, the menu does not follow the page. |
After each swap, the script fires PageNavigation.EVENT_SWAP ('pagenavigation:swap') on document, after Jimbo.EVENT_ON_DISPLAY_CONTENT. Use it to close a menu or to update the page header.
| Function | Use |
|---|---|
PageNavigation.open(url) |
Opens the page as a link does: in place in the same area, else with a page load. |
PageNavigation.replace(url) |
Opens the page in place of the current history entry. |
PageNavigation.fetchPage(url, requiredScript) |
Fetches a page for a swap. The promise gives null when the page cannot be swapped in. |
PageNavigation.swapContent(page, defaultFormStore) |
Puts the content of a fetched page in place. |
PageNavigation.pushState(state, url) |
Adds a history entry for a swapped page. |
PageNavigation.markCurrentEntry(url) |
Marks the current history entry, so Back to it swaps the page in again. |
PageNavigation.getMenuState(), setMenuState(ids) |
Read and set the active menu links. |
PageNavigation.addPopStateHandler(handler) |
Lets a script take Back or Forward first. The handler returns true when it took it. |
dgs-page-form.js
dgs-page-form.js opens a DGS form as its own page, without a page reload. It uses PageNavigation. Cancel, a link back to the list, and Back show the list again as it was. A save shows the list again and refreshes only the grid of the store, so its filters, its sort order and its page stay.
A page registers a store from its own script:
window.dgsPageFormStores = window.dgsPageFormStores || [];
window.dgsPageFormStores.push('orders');
window.dgsPageFormStores.push({store: 'orders', actions: ['refund']});
The first form opens the Add and Edit forms of the store as pages. The second form opens the forms of other actions of the store.
The store answers a save with the action callback and the name Jimbo.onStoreRowsSaved. In PHP, use Festi\Theme\Store\StoreSaveRedirect of the theme package:
$saveRedirect = new StoreSaveRedirect('orders');
$saveRedirect->listen($formStore);
The object DgsPageForm starts when the document is ready. A script can also use it directly:
| Method | Description |
|---|---|
DgsPageForm.open(store, url) |
Opens the page at url in place of the list of store. |
DgsPageForm.onStoreRowsSaved(data) |
Answers a save. Jimbo.onStoreRowsSaved calls it. |
StoreSaveRedirect::setRedirectUrl($url) sets a different address to redirect to after the save, for example the new order. The callback gives it in redirectUrl. A form opened from its URL goes back to the list with a redirect, as the framework does.
Filter panels
filter-panel.js
filter-panel.js defines FilterPanel. It handles each filter panel of the theme: the Filters button, the applied filters as chips, and the form in a popup. The theme marks a panel with e-ui-filter-panel. A panel without this class has its own script, and FilterPanel does not touch it.
The script does these things:
- The Filters button and a click on a chip open or close the popup. Cancel closes it.
- A click outside the panel and the Escape key close each open popup. A click in a date picker or a select list of a filter does not close it.
- On a phone (
data-mobileon the panel) a tap on the dimmed page closes the sheet. - When a popup opens, the script fires
FilterPanel.EVENT_OPEN(filterpanel:open) on the panel.dgs-list.jslistens to it.
The attribute data-submit of the panel sets how the filters apply:
data-submit |
Search | Remove a chip, Clear Filters |
|---|---|---|
url |
Puts the form values into the page URL and opens it. The other parameters of the URL stay. | Sets the parameter of each chip to an empty value in the URL. |
| other value | Sends the form as it is. dgs-list.js can take the submit of a grid. |
Empties the inputs of each chip and clicks the submit button of the form one time. |
The data-field of a chip names its inputs. An input belongs to the chip when its name is the data-field, or starts with it and [, for example orders[filter][date][from].
The theme sets its markup in FilterPanel.options. The script reads the options on each event.
| Option | Default | Use |
|---|---|---|
panelSelector |
'.e-ui-filter-panel' |
The filter panels that this script handles. |
popupSelector |
'.modern-filter-popup' |
The popup with the form. |
toggleSelector |
'.e-filters-toggle, .filter-item' |
The elements that open or close the popup. |
cancelSelector |
'.btn-cancel' |
The elements that close the popup. |
removeSelector |
'.remove-filter' |
The remove button of a chip. Its data-field names the filter. |
clearAllSelector |
'.b-filters-clear-all' |
The Clear Filters button. |
appliedFilterSelector |
'.selected-filters .remove-filter' |
The remove buttons that Clear Filters reads. |
submitSelector |
'[type="submit"]' |
The submit button of the form. |
activeClass |
'active' |
The class of an open popup. |
outsidePopupsSelector |
date pickers and select lists | The popups on body that count as a part of the panel. |
| Function | Use |
|---|---|
FilterPanel.setOpen(panel, isOpen) |
Opens or closes the popup of the panel. |
FilterPanel.removeFilters(panel, fields) |
Removes the filters of the chips with these data-field values and applies the rest. |
DefaultTheme of the theme package loads this file.
Phone components
dgs-mobile-list.js
dgs-mobile-list.js defines DgsMobileList. It handles the phone layout of a DGS grid:
- A checked line shows the selection bar at the bottom of the grid. The bar shows the count of the checked lines. The close button of the bar unchecks all lines.
- A tap on an item of a sheet menu closes the sheet. The script catches the click on the way down, because an action link stops the click.
- A plugin can mark its main action
btn-primaryin the browser. The script then moves that action from the More menu to the header, before More. A More menu with no action left goes away. A header that already shows a main action stays as it is.
The script moves the main actions when the page is ready, after the scripts of the page, and on Jimbo.EVENT_ON_DISPLAY_CONTENT. DefaultTheme of the theme package loads it.
| Option | Default | Use |
|---|---|---|
gridSelector |
'.b-db-table' |
The grid. |
itemSelector |
'.i-grouped-item' |
The checkbox of a line. |
selectAllSelector |
'.i-select-all' |
The Select All checkbox. The count does not include it. |
selectionBarSelector |
'.b-dgs-selection-bar' |
The selection bar. |
selectionCountSelector |
'.b-dgs-selection-count' |
The count. Its data-caption holds the text, with %s for the count. |
selectionTitleSelector |
'.b-dgs-selection-title' |
The title of the group actions sheet. It gets the same text. |
selectionClearSelector |
'.b-dgs-selection-clear' |
The close button of the bar. |
sheetMenuSelector |
'.b-dgs-sheet-menu' |
A sheet menu. |
sheetMenuItemSelector |
'.b-dgs-sheet-menu > .dropdown-menu a' |
An item of a sheet menu. |
sheetCancelSelector |
'.b-dgs-sheet-cancel' |
The Cancel item of a sheet menu. |
mobileActionsSelector |
'.b-dgs-mobile-actions' |
The header actions of a phone grid. |
primaryActionClass |
'btn-primary' |
The class of the main action. |
activeClass |
'active' |
The class of a shown selection bar. |
openClass |
'open' |
The class of an open sheet menu. |
| Function | Use |
|---|---|
DgsMobileList.updateSelectionBar(grid) |
Shows the bar with the count of the checked lines, or hides it. |
DgsMobileList.promotePrimaryActions(root) |
Moves the main action of each phone grid in the root to the header. |
filters-bar.js
filters-bar.js defines FiltersBar. On a phone, the theme prints a bar over the filter panel. The bar shows the count of the applied filters. A tap on the bar folds or opens the row of applied filters. The row is open when filters are applied. The Add Filter chip clicks the Filters button of the panel.
The script does nothing for a panel without the bar. The theme prints the bar only for a phone, so you can load the script on each screen. Load styles/filters-bar.css with it. That file folds the row and hides an empty count. The look of the bar comes from the theme.
The panel calls prepareFiltersBar(document.currentScript) after its markup. The script also prepares each panel in new content on Jimbo.EVENT_ON_DISPLAY_CONTENT.
| Option | Default | Use |
|---|---|---|
panelSelector |
'.modern-ui-filter-wrapper' |
The filter panel. |
barSelector |
'.b-filters-bar' |
The bar, a child of the panel. |
countSelector |
'.b-filters-bar-count' |
The count on the bar. |
appliedFilterSelector |
'.selected-filters .filter-item' |
One applied filter. |
addFilterSelector |
'.b-filters-add' |
The Add Filter chip. |
filtersButtonSelector |
'.e-filters-toggle' |
The button that opens the filters form. |
foldedClass |
'b-filters-folded' |
The class of a folded panel. |
| Function | Use |
|---|---|
FiltersBar.prepare(element) |
Sets the count and the fold of the panel of the element. window.prepareFiltersBar is the same function. |
sheet.js
sheet.js defines Sheet. On a phone, each bottom sheet gets a grip at its top. Drag the grip up for a full-height sheet. Drag it down to shrink the sheet or to close it. A tap on the grip switches the height. A full-height sheet shows a close button at the left of the grip. Its label is Jimbo.lang('Close').
Festi markup marks a sheet with b-sheet and its close control with b-sheet-cancel. The theme registers the sheets of its libraries with Sheet.register():
Sheet.register({
selector: '.modal-content',
closeSelector: '[data-dismiss="modal"]',
openEvent: 'shown.bs.modal'
});
| Key | Use |
|---|---|
selector |
The sheets. Required. |
closeSelector |
The control in a sheet that closes it. The script clicks the first b-sheet-cancel or closeSelector control. |
getCloseControl |
A function that gets the sheet and returns its close control. It wins over closeSelector. |
openEvent |
A document event after which a sheet shows. The script prepares the sheets then. |
isWatched |
true for a sheet that shows without a click, for example from a reply of the server. The script watches the children of body for it. |
backdropSelector |
A tap on this element closes the top visible sheet of the registration. |
The script adds the grips when the document is ready, one time after each click, on Jimbo.EVENT_ON_DISPLAY_CONTENT, and after each openEvent. Load styles/sheet.css with it. That file has the grip, the full height and the drag. The theme gives the colour of the grip bar (.b-sheet-handle::before) and of the close button (.b-sheet-close).
| Option | Default | Use |
|---|---|---|
sheetSelector |
'.b-sheet' |
The Festi sheets. |
closeSelector |
'.b-sheet-cancel' |
The Festi close control. |
dragThreshold |
40 |
A drag shorter than this, in pixels, changes nothing. |
tapDistance |
5 |
A move shorter than this, in pixels, is a tap. |
| Function | Use |
|---|---|
Sheet.register(registration) |
Makes the elements of a library sheets. |
Sheet.prepareSheets() |
Adds the grip to each sheet that has none. |
Sheet.close(sheet) |
Shrinks the sheet and clicks its close control. |
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 functionJimbo.set<Type>Responseor 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
debugtotruein the code of a project. - Give the action
callbacka fixed function name thatwindowhas. - Do not use the class
f-formto submit a form without a page reload. Use the HUI form or the HUI dialog with anonAjaxmethod.