JS Implementing

General Info

iQDesk Engine v.2.0 was conceived as pretty user friendly system to manage the work flow. Of course, no one user friendly interface cannot exist without a lot different JavaScript helpers, which makes the work interactive, when you're able to see everything, what is going in the system right now and right here. So for example, creating process of a simple item can be provided via redirecting user from current page to a page , which contains the create form, or it can be just simple modal window. Do you feel the difference? Or other example, when you no need to write some handlers to make the table column be sortable, but all what you need is to just add an simple attribute on <th> tag. All of these features, and even more, can be done with built in JavaScript libraries. So it seems like the time to learn more has come. Let's go one by one through all the built in JavaScript libraries, and you will see how simple to implement each of them.

One other important thing, what we think you should know is that iQDesk Engine v.2.0 uses the jQuery UI. It has included all the features, so you are free to use any jQuery UI plugin in your module. jQuery UI has included CSS styles which are adapted for the current color scheme.

Visual Helpers

General Info

Visual Helpers library provides the functionality to replace following default form elements for designed:

  • <input type="checkbox" /> being replaced with the clickable square.
  • <input type="radio" /> being replaced with the clickable circle.
  • <input type="file" /> being replaced with rounded rectangle with magnifier icon. this rectangle is clickable, and is ready to handle the drag files from outside of the browser.

Also one of the important functionality of Visual Helpers library is the initialization of the current state of sortable columns headings. It takes the given URL, and applies the sorting direction attributes according the sortable columns.

Another important functionality of Visual Helpers library is the initialization of datepicker fields.

Class and Functions

The class name of the Visual Helpers library is VisualHelpers. Once the work space of the system was rendered in the browser, the object visualHelpers will be created automatically. You can access all the class functions through this object, or create new object of VisualHelpers class.

VisualHelpers class has several functions which can be useful by you:

  • init() initialize all the view helpers - replacing form elements and handling sortable columns.
  • initDatepickers() initialize the detepicker fileds. Will catch all the fileds which have the class datepicker-field, and bind the datepicker for these fields.
  • initSortColumns() initialize the sorting attribute of sortable columns, by given URL.
  • replaceCheckbox() replaces the checkboxes.
  • replaceRadio() replaces the radio buttons.
  • replaceFile() replaces the file inputs.

To run all the helpers at once, you just need to call function init(). As we told, once the system is rendered in user's browser, the object visualHelpers will be created automatically, but besides of this, the function init() of this object will be called. It allows to apply all helpers on just created view. Also, when the new modal window being created and opened, the init() function will be called automatically, to apply all the helpers to just created elements. In the case, if you're going to change the view content on the fly, and you know, that changed content may have included elements, which should be taken by the Visual Helper class, then don't forget to call again init() function of VisualHelpers class.

Tabs

General Info

One of the interesting feature of iQDesk Engine v.2.0 is the tabs management on the view of your module. It allows to handle events of tabs clicks, display related content and etc. All of this functionality being provided by Tabs library. Also it handles the tabs event for mobile devices.

Functions of Tabs Class

The Tabs class has several functions, which allows you to define the Tabs object, and attach required events.

  • init(selector) initialize the object of Tabs class. Being called automatically on creating new object.
    Parameters:
    • selector defines the jQuery selector of the tabs wrapper.
    Read more about using initializing the Tabs object below.
  • bindEvents() binds the events of the current Tabs object.
  • displayTab(tab_name) displays the given tab container.
    Parameters:
    • tab_name the name of the tab container. ID of tab container should be in format "tab-[tab_name]"

Using

After loading the system, no Tabs class object will not be created automatically, you will have to create new object yourself, once you will need it. To define the tabs, first what you need is to create HTML markup of the following structure, which defines the tabs handler:

<ul class="tabs-list" id="[tabs_wrapper_id]"> //defines the tabs wrapper <li class="active"> //defines the single tab, apply "active" class if this is a current tab active <a href="#[tab_name]"> //defines the tab active link [tab_title] </a> </li> //repeat the <li> element so many times as many tabs you need </ul>

Right after this HTML markup, you have to create new Tabs class object, and bind required events:

var [object_name]=new Tabs("#[tabs_wrapper_id]").bindEvents();

And the last what you have to do is define tab container:

<div id="tab-[tab_name]" class="tab-container"> //place here content, which is related to this tab </div>

Let's take a look on the highlighted expressions:

  • [tabs_wrapper_id] defines ID of the tabs wrapper. You can select any ID you would like.
  • [tab_name] defines the name of the tab container. ID of tab container should be in format "tab-[tab_name]"
  • [tab_title] defines the title on tab. Can be static or translated text. If you're going to sell your module online, you should use translated text.
  • [object_name] is user defined name of the object of Tabs class.

As you can see nothing difficult to define tabs handlers and bind events. In other words, you have to:

  1. Create HTML markup of the tabs
  2. Create Tabs class object
  3. Create HTML markup of tabs' containers

One of the other important feature of handling clicking on tabs is the parsing of action link's attribute href. There are 3 different types statements you can put into this attribute:

  1. href attribute is "#". In this case nothing will happen. No tab container will be displayed, no opening new page will happen.
  2. href attribute is "#[tab_name]". In this case related tab container will displayed.
  3. href attribute is typical link on the some page. In this case this link will opened in the parent window.

Popups

General Info

Popups is a kind of modal windows, but this type of modal windows doesn't load any content through AJAX, and creates the content of modal window on the fly. The primary purpose of using this type of modal windows is to display the system alerts, like "warning", "notification" and "confirmation" alerts. The Popups feature is presented in iQDesk Engine v.2.0 as class Popup. It has several functions to help you create your own alert on the fly.

Functions of Popup Class

  • init(params) initialize the object of Tabs class. Being called automatically on creating new object. The constructor of this class passes all the given parameters into this function.
    Parameters:
    • params defines the parameters of creating object. It should be presented as static object, with defined following options:
      • params.type defines the type of new popup. Can be "warning", "notification" or "confirmation".
      • params.title defines the title of new popup.
      • params.message defines the internal message of new popup.
      • params.buttons defines the buttons which will displayed on the popup window. This property should be presented as array of static objects, each element of this array should has following structure:
        • params.buttons[n].title defines the title of the button.
        • params.buttons[n].type defines the type of the button. Can be "confirm" or "close".
        • params.buttons[n].params defines the parameters of this button. Should be presented as the static object with following structure:
          • params.buttons[n].params.href
            • defines the "href" attribute of this button.
          • params.buttons[n].params.onclick
            • defines the "onclick" event of this button.

No other function is presented in the Popup class, but this single function enough to make the work in iQDesk Engine v.2.0 interactive.

Using

Let's take a simple example of how to create a new popup:

var [object_name]=new Popup({ type:[popup_type], title:[popup_title], message:[popup_message], buttons:[ { title:[button_title], type:[button_type], params:{ href:[button_href], onclick:[button_onclick] } } //define here so many buttons as you wish ] });

All highlighted expressions were explained above, so you should know what every of them should mean. Just one new thing is [object_name]. It defines the Popup object name. As you can see, creating of new popup takes not many lines of code. After performing these lines, popup will automatically being displayed in the user's browser with nice animation.

One thing on which you could pay attention is the parameters like [popup_title] or [popup_message] or [button_title] should be translated as every other text rows in the system. But how we can get translations of texts in JavaScript? We took care about this, and you can get all the translated texts using the global object lang. The using is pretty simple: lang['text_to_translate'] will return the translation of the "text_to_translate" accordingly the current language. So seems like now you know enough to ask the user, who will use your module, about every thing you want.

Inline Confirmations

As we told, in iQDesk Engine v.2.0 we're following the idea of interaction with user on every action he does. So for these reason was buil the Popup class, but let's imagine if you need to ask a lot of confirmations, when user does some action, seems like it will be difficult to write the handling functions for each type of confirmation popup in your module. That's why we did an special feature which allows you to make the link or button to have confirmation popup before perform action. Let's see how it's simple to implement the inline confirmation.

Let's take for example a simple link, which does some action, which requires confirmation on the user side.

<a href="[some_action_url]"> [link_title] </a>

Now all what you need is to add the class popup-action and few simple attributes to <a> tag. They are:

  • popup-type defines the type of your popup, is it confirmation or some alert. Can be "notification", "warning" or "confirmation".
  • popup-title defines the title of your popup. Can be static or translated text. If you're going to sell your module online, you should use translated text.
  • popup-message defines the message of your popup. Can be static or translated text. If you're going to sell your module online, you should use translated text.
  • popup-buttons defines the built in buttons. Should have following format: [button_1_type]:[button_1_title],[button_2_type]:[button_2_title],...,[button_n_type]:[button_n_title]
    [button_1_type]:[button_1_title], [button_2_type]:[button_2_title], ..., [button_n_type]:[button_n_title] are the same parameters as when you create popup using the Popup class.

Ok, let's merge all of this info and see how will the link look after implementing the inline confirmation.

<a href="[some_action_url]" class="popup-action" popup-type="confirmation" popup-title="[confirmation_title]" popup-message="[confirmation_message]" popup-buttons="confirm:[yes_button_text],close:[close_button_text]" > [link_title] </a>

As we told, nothing difficult to put inline confirmation on the every link or button you want. No one of these attributes is required. Default values are:

  • popup-type="notification"
  • popup-title=lang['notification'] related on defined type of the popup.
  • popup-message=""
  • popup-buttons="close:[close_button_text]"

Hiding Elements

General Info

One of the special type of containers in iQDesk Engine v.2.0 is the hiding elements. Good example of one hiding element can be the listing view sidebar. If you try to click the header with the arrow icon of the sidebar, then you will see that the whole sidebar will be hidden with nice animations. This way helps to good organize the work space, helps to hide the elements, saving the space. Of course, the example with the sidebar is just one of the ways how to implement hiding elements in your module. Besides the vertical elements, you also can apply the same hiding effect for the horizontal elements. To apply the hiding effect for any element you may want, you just need to add few special attributes for the hiding handler and the handled element. also for these purposes was created special Hideable library. So let's take a look on the functions of this class, and let's see how to implement them to make your hiding elements.

Functions of Hideable Class

  • init() initialize the object of Hideable class. Being called automatically on creating new object.
  • bindEvents() attaches all the required events on the hiding elements and on their handlers.

Using

Hideable class in iQDesk Engine v.2.0 has the auto-created global object _hideable. Initialization of this object occurs on rendering the system in the user's browser. So you can access the function of this class through this object, or you can create new object of this class. Now let's see how to define which elements will be hideable, and which elements will handle their hiding. First you need to add the id attribute to the element which you want to be hideable and add the class vertical-hideable or horizontal-hideable to this element. Then you need to decide, which element will control the hiding of related container, add to this element a simple attribute data-related-to="[id_of_hiding_element]" and class vertical-hideable-handler or horizontal-hideable-handler. That's all, after defining these attributes, all the events will be handled automatically, and you will be able to hide the hideable element by clicking his handler. As you noted, there are two different types of classes which you can define for the given elements vertical-hideable or horizontal-hideable and vertical-hideable-handler or horizontal-hideable-handler. As you can see the class names starts with "vertical" or "horizontal", this word defines how the element hides: as vertical element or as horizontal element. Ok, now let's repeat all what you read above with a simple example of hiding element.

<div class="vertical-hideable-handler" data-related-to="[id_of_hiding_element]"> //define hideable element handler [text_on_handler] <div> <div class="horizontal-hideable" id="[id_of_hiding_element]"> //define hideable element //place here the content of the hideable element </div>

This example pretty clear shows how you should create your HTML markup to make the hiding element. One other thing we would like to pay your attention on, is the case when you will add the content dynamically. Let's imagine you have added the same HTML markup, but after the initialization of the _hideable object, in this case you have to reinitialize this object by calling the function _hideable.init().bindEvents();. It will catch all the new added hiding elements, initialize them and bind all required events.

Form Validation

General Info

Every form, which the user fills in the iQDesk Engine v.2.0 will be validated before submit it to the server. No matter, the form being sent through regular submitting or AJAX. For this purpose, in the system was created special FormValidator class, which allows to perform validation of the form before submitting. This class allows to define different rules for the different fields, and go through all the validation rules one-by-one. Also, this class is written so, you're able to extend the predefined rules with your own. So let's see what the functions class provides us.

Functions of Hideable Class

  • init() initialize the object of FormValidator class. Being called automatically on creating new object.
  • validate(form) validates the form, which specified as jQuery selector or JavaScript object in single parameter of this function. Returns the boolean TRUE if the form passed validation successfully, and FALSE if the form didn't pass validation. Besides of this, form takes the predefined error handler element on the form, and put there the error, if form didn't pass the validation.
    Parameters:
    • form defines the jQuery selector or JavaScript object of dom element, which represents the form, which should be validated.
  • validateField(field,rules) validates the given field with given rules. Return boolean TRUE if field validated successfully, or FALSE if field not pass the validation.
    Parameters:
    • field defines the jQuery selector or JavaScript object of dom element, which represents the field, which should be validated.
    • rules defines an array of rules, which be used for validate value of this field. Each element of this array should have following structure:
      • rules[n].type defines the type of validation. Read more about built in iQDesk Engine v.2.0 validation rules below.
      • rules[n].params defines an array of additional options to validate. Every element of this array is a simple value of related parameter.
  • getValidationRules(field) collects the validation rules and their additional parameters of the given field from defined attributes. Returns the array, which has the same structure as wrote above.
    Parameters:
    • field defines the jQuery selector or JavaScript object of dom element, which represents the field, which should be taken for parsing rules.

Using

As you can see, FormValidator class provides a lot of functions to validate every form you want. But how to use it on the real form. Firstly, what you should know, is that public object formValidator will be created on rendering the system in the user's browser, so you can access all the functions of this class by calling it directly from this object. Other important thing, is that you can go two different ways how to force the form validation. 1st way is to write own handlers to catch the event when the form is going be submitted. 2nd is the inline way, which doesn't require any coding, just define special attributes for the form and for the form's fields. If you're going to use 1st way, then you're enough experienced developer, and we think that given info about this class is already enough to create own handlers to validate form. Now we would like to pay attention exactly on the 2nd way.

As we told, you have to put special attributes for the form and fields to force the form be validated. Let's take a simple example to highlight these special attributes.

<form method="[form_submitting_method]" action="[form_action_url]" validate-form="true" validation-error="[validation_error_text]"> //define the form element <input type="text" name="[field_name]" required-field="true" validation="[[rule_type]:[parameter_1]:[parameter_2]:...:[parameter_3]]" validate-on-checked="[checkbox_id]" validate-on-selected="[select_id:select_value]" /> //define the form field <div class="form-error-handler" error-handler="true"></div> //define the form error handler element </form>
  • [form_submitting_method] defines method of submitting form. Can be "post" or "get".
  • [form_action_url] defines the URL which receives the submitted form fields.
  • validate-form="true" special attribute, which defines that this form should be validated before submitting.
  • validation-error="[validation_error_text]" special attribute, defines the text of the error which will be displayed if the form will not pass the validation. In iQDesk Engine v.2.0 used the single-error type of alerting errors. It means, that errors will not be displayed under the each not correct field, but one general message will be displayed.
    • [validation_error_text] defines the text of the error. Can be static or translated text. If you're going to sell your module online, you should use translated text.
  • [field_name] defines the name of the field.
  • required-field="true" special attribute, which defines that this field should be validated before submitting.
  • validation="[[rule_type]:[parameter_1]:[parameter_2]:...:[parameter_3]]" special attribute, which defines the rules, which the field should pass before submitting.
    • [rule_type] defines the name of the validation rule. Read more about predefined validation rules in iQDesk Engine v.2.0 below.
    • [parameter_1], [parameter_2], [parameter_n] define additional options for given validation type. Read more about predefined validation rules and their options below.
    You can add more than one rule for one field.
  • validate-on-checked="[checkbox_id]" defines that this filed should be validated only in the case if the given checkbox is checked.
    • [checkbox_id] defines the ID of the checkobx, which should be checked to force validate this field.
  • validate-on-selected="[select_id:select_value]" defines that this filed should be validated only in the case if the given select has selected specified option.
    • [select_id] defines the ID of the select, which should be checked to force validate this field.
    • [select_value] defines the value of the given select, which should be selected to force validate this field.
  • <div class="form-error-handler" error-handler="true"></div> represents the HTML markup of the handler for the validation errors.

Using the example above, you can create the form which will be validated each time when user will click submit. Now you probably would like know, how the from will be intercepted on submit. Let's back for a few chapters above, and remember the public object _events which being created automatically on displaying the system in user's browser. Exactly the class Events catchs the event of submitting form, which has attribute validate-form="true". So now it's time to take a look on predefined validation rules in iQDesk Engine v.2.0.

Predefined Validation Rules

  • not-empty checks if the field value is not empty.
  • not-null takes the integer value of the given field and checks, that this value will not match 0.
  • positive-number takes the integer value of the given field and checks, that this value greater or equal 0.
  • negative-number takes the integer value of the given field and checks, that this value less than 0.
  • limited-number takes the integer value of the given field and checks, that this value is in the given limit. Limit being defined by additional parameters:
    1. parameter defines the lowest limit of the number.
    2. parameter defines the biggest limit of the number.
  • email checks if the field value matchs the email pattern.
  • match-field checks if the field value matchs the value of the field, specified in additional parameter:
    1. parameter defines the ID of the field which should be compared with the given field.
  • checked checks if the given field is checkbox or radio input, and it's checked.
  • extension checks if the given field is file input and selected file extension maths the specified extension in the additional parameter:
    1. parameter defines the allowed extensions. Can have multiple extensions, divided by comma.
  • at-least-one-checked checks if the given field is checkbox and at least one of the fields with the same validation rule is checked.
    1. parameter defines unique identifier for the checking checkboxes.

Extending Validation Rules

As we told above, you have an awesome ability to extend predefined rules by your, and even more, you can redefine the predefined rules! So how to extend the validation rules? Class FormValidator contains the property rules. this property is presented by the array. Key of each this array is the type name of validation rule, and the value of element is the function, which will be called when the FormValidator class will do the validation of the field. Also remember, that you have auto created object formValidator of this class. So all what you need is to append to the formValidator.rules new element which will have the key, defining the validation type name, and which will have the value represented by a function. Let's see on the simple example, to understand how this feature should be used:

formValidator.rules[[validation_type_name]]=function(field,value,params){ if (![condition_of_corrent_field]) return false; return true; }
  • [validation_type_name] defines the unique name of your new validation type.
  • field contains the passed JavaScript dom element of the currently validating field.
  • value contains the passed value of the currently validating field.
  • params contains the passed additional parameters, which were defined in the currently validating field.
  • [condition_of_corrent_field] defines the primary condition, which checks that the given field value and parameters, satisfy requirements.

As you can see, it's pretty simple to define your own validation rules. All what you need, is to create in "assets" folder of your module new JavaScript file, put in this file your validation rules, and include this file in the view file of your module. If you're going to create your module based on the other module, firstly check, if the same rules, as you want to add, already added in other modules. In the case if they are already added in some other module, you don't need to write them again, just include their JavaScript file in your view file, and enjoy extended validation rules.

Ajax Submitting Form

General Info

In iQDesk Engine v.2.0 every form can be submitted two ways: regular or through AJAX. In this chapter we're going to explain how to force the form be submitted through AJAX. There is not a special library for manipulation this feature, the submit action will be intercepted by the built in Events class. Let's see what you should do to make the AJAX form.

Using

Let's take a look on the simple example, how to convert typical boring form into the AJAX form. Pay attention on the highlighted expressions.

<form method="[form_submitting_method]" action="[form_action_url]" ajax-form="true" callback="[ajax_callback_function]"> //define the form element <input type="text" name="[field_name]" /> //define the form field </form>
  • [form_submitting_method] defines method of submitting form. Can be "post" or "get".
  • [form_action_url] defines the URL which receives the submitted form fields.
  • ajax-form="true" special attribute, defines that this form should submitted through AJAX.
  • callback="[ajax_callback_function]" special attribute, defines callback function on success form submitting.
    • [ajax_callback_function] user defined function, which will be called after success response from the server. Can pass any values which you want to pass. But one of them is required:
      response should be passed into the defined function, if you want to operate with the server response. Will contain the text response from the server.
  • [field_name] defines the name of the field.

After you specify all of these special attributes, your form will be sent through AJAX. Don't forget to specify any callback function, because in other case, if you will not specify anything, after complete request, the form will back the active state, without any changes. We advice to use the function, which will replace the current form with some success message. It will make your module clear for using by users. Dont' forget, to create good module and to be successfull iQDesk Engine developer, you should follow the idea of maximum interactivity with users.

Tooltips

General Info

Following the idea of maximum interactivity with users, iQDesk Engien v.2.0 has the feature which allows you to build a tooltips for every element you want. This feature is not presented in some special class, and all what you need is to put single inline attribute to the element, on which you want to show the tooltip. Sounds pretty simple, but in fact it gives a lot of benefits of using your module. Imagine, you have a listing view of some data, and of course every row contains the one cell, in which you place the action buttons, which allow to manage this record. In this cell, you can put a links with clear names like "Update" or "Delete", but it firstly will look bad, also you can meet the problem of not enough space. That's why in built in modules we uses the icons instead of the text. It helps to save the space and make the table look good, but some icons can be difficult to understanding by users. So in this case tooltip is the perfect tool to help user to recognize, what will happen if he will click this icon. So, now you know at least one way, how you can use the tooltips in your module. So let's see how you can use this feature.

Using

Let's take s simple example of HTML markup which displays the icon button with tooltip.

<a href="[action_link]" tooltip-text="[your_tooltip_text]"> //define the button element <i class="typcn typcn-edit"></i> //define the icon element </a>

As you can see it's a pretty simple HTML markup. And as you already noted there is just one custom attribute on the link element. But let's wait and go through all the highlighted expressions one-by-one.

  • [action_link] defines the link which should be processed after clicking on this link.
  • tooltip-text="[your_tooltip_text]" defines the text of your tooltip.
    • [your_tooltip_text] defines the text what user will see on the tooltip. Can be static or translated text. If you're going to sell your module online, you should use translated text.

As you know now, to attach the tooltip to the element, all what you need is to specify the special attribute tooltip-text, which should the text, which you would like to display on the tooltip. You no need to worry about placing the tooltip, we took care about it and it will be calculated automatically, based on the current screen direction (ltr or rtl). Tooltip will be displayed only on the hover action, when user moved mouse pointer on the element. The handler of this event is defined in the built in Events class, so you also don't need to worry about how to catch this event.

Sorting Tables

General Info

We already touched couple times the topic of sorting tables, in the chapter "Model" of "Server-Side Coding" section, and the chapter "Visual Helpers" of this section, but now it's time to explain, how to make the heading cell of the table be active for sorting. iQDesk Engine v.2.0 has no special class for managing the sortable columns in the table, and in contrast to a lot of other presented sorting mechanisms in the products of other developers, our system don't use the JavaScript sorting. We feel it stupid, because to sort the table using JavaScript you should load all the records in table at once, it smacks by madness, no? That's why we decided to use serve-side sorting, and use the event catchers on the front-end to intercept the clicking on the sorting column headers. So let's take a look how you can define sortable column header.

Using

Below is presented a simple example of one sorting column header. Pay attention on the custom attributes.

<th sort-column="[table_sort_column]" sort-direction="[current_sort_direction]"> [column_title] </th>

Highlighted special attributes helps the script to understand, that this column can be sorted, and define current direction of sorting.

  • sort-column="[table_sort_column]" defines the column header be active for sorting.
    • [table_sort_column] defines the database table filed, which will be used in sorting statement. Be careful, this value should fully match with the table field name in the database, because in other case it can cause the fatal error of your module.
  • sort-direction="[current_sort_direction]" defines the current direction of sorting. You should define this attribute only for the one table header, which is really sorted for now. For example, if you taking records from the database sorted by [field_name] in direction [sorting_direction], then in the view file of your module you should specify "sort-direction" attribute with value [sorting_direction] exactly for the column header linked with [field_name]. But if user clicked the sorting at least one time, then you no need to specify this attribute at all, the Visual Helper library will recognize current sorting parameters and set up required attributes.
    • [current_sort_direction] defines the direction of sorting. Can be only "asc" or "desc".

Ok, now you know, that to define the column header as active for sorting, all what you need is specify couple special attributes. It's clear. But what about catching the click event on the header? Don't worry about it. Built in Events class took care about it. It catches the event of click on the sortable column header, and refreshes the page with new $_GET parameters, which your model should get and prepare correct output records for the view file. Specific $_GET variables after clicking on sortable column header are:

  • sort-column contains the database table's field name, which is being used for sorting.
  • sort-direction contains the direction of sorting. Can be "asc" or "desc" only.

Batch Events Handling

General Info

The last important front-end feature of iQDesk Engine v.2.0 is the handling of batch events. What is it? It's simpler to explain on some little example. Imagine, you have a listing view, which has a lot of records, you need to delete some of them. Of course, in this case you can add the delete action button related to the each record, but how many time you will spend to delete 10, 20 or 50 records? Seems like it will take a lot of time. Exactly in this case, the batch events will help you. Now, the same case, but near each record you have the checkbox, and once you have ticked all the records you want to delete, the button (for example "Delete Selected") will be displayed, and clicking on this button will delete all selected records. It will save your time, and thousand of your nervous.

Using

So how to define these checkboxes and how to hide/display the batch action button if related checkboxes are selected or not. Let's take a look on the simple example.

<a href="[batch_action_url]" id="[batch_action_button_id]" style="display:none;"> //define the batch action button or link <i class="typcn typcn-trash"></i> [batch_action_button_title] </a> //.................... <input type="checkbox" batch-handler="[unique_batch_set_identifier]" batch-related="[batch_action_button_id]" name="[checkbox_name]" value="[checkbox_value]" /> //define the checkbox which will be taken for the batch event

Now let's see on the highlighted expressions:

  • [batch_action_url] defines the batch action URL.
  • [batch_action_button_id] defines the ID attribute of the batch action button.
  • style="display:none;" defines, that by default this button is hidden, until at least one related checkbox is checked.
  • [batch_action_button_title] defines the title of the batch action button. Can be static or translated text. If you're going to sell your module online, you should use translated text.
  • batch-handler="[unique_batch_set_identifier]" special attribute, defines the unique ID of the batch set.
    • [unique_batch_set_identifier]
      • defines the unique ID of the batch set. As you can imagine on the one view of your module can be placed a lot of different checkboxes, but you need to handle only few of them to be in part of batch action. So this ID defines the system ID of the checkboxes set, which will be used for batch action.
  • batch-related="[batch_action_button_id]" defines relation between this checkbox and related batch action button.
    • [batch_action_button_id]
      • defines the ID of the batch action button, which is related to this checkbox, and to the whole set of checkboxes related on one batch action.
  • [checkbox_name] defines the field name, which should be sent to the [batch_action_url].
  • [checkbox_value] defines the field value, which should be sent to the [batch_action_url].

As you can see, the process of setting batch events handlers can be splited into few simple steps:

  1. Create a batch action button HTML markup
  2. Create a HTML markup of the checkbox related to this action
  3. Setup ID of the batch action button, put the same value in batch-related of related checkbox and define unique ID of batch set

You no need to worry about handling the events, like the check or uncheck the checkbox, the built in Events library took care about all of this. Once at least one checkbox from the batch set will be checked, the Events library will catch it and will display the batch action button. Once the Events library will find that no one of batch set's checkbox is checked, the batch action button will be hidden automatically. One thing you have to take care about, is the what to do with selected checkboxes from the batch set. Meaning you should write an event handler for the batch action button, which will collect all the checkboxes from the batch set, and will send them to [batch_action_url].

Well, now you know all about built in JavaScript features of iQDesk Engine v.2.0. We pretty sure, this knowledges will help you to create amazing module, and you will find a lot of ways to use all of these features in your module!

©2014 iQDesk. All rights reserved.