Microformats¶

Field validation¶

Usage:

<label class="cm-email cm-required" for="elm_id">Field name:</label>
<input type="text" name="test" value="Y" id="elm_id" />

Element label, assigned to the validated element with parameter for, is required for validator of the form fields.

Microformat of the field validation is defined in the class attribute of the element label, and classes can be combined. The label, even if it is hidden, must have a description, as this description is used in the message about the incorrectly entered field. Within these messages the following placeholders can be used:

[field] - replaced by a label description, if one parameter is passed to the message generation function, for example:

var msg = 'The field [field] is not valid';
this.form_message(msg, lbl);

[field1], [field2] - replaced by a description of main and additonal labels, if two parameters are passed to the message generation function, for example:

var msg = 'The field [field1] do not match field [field2]';
this.form_message(msg, lbl1, lbl2);

[extra] - additional data that is to be displayed in the message:

var msg = 'The field [field] should be set to the following format: [extra]';
var extra = '1AB-CF5';
this.form_message(msg, lbl, null, extra);

• cm-required - the element is required to be filled out. If assigned to a check box, the check box is to be checked.
• cm-email - the element value must be a valid e-mail address.
• cm-phone - the element value must be a valid telephone number.
• cm-zipcode - the element value must be a valid zip code (every country has its own zip code format, so the pattern is to be defined in the country table, but so far manually - the method $.ceFormValidator('setZipcode', {...})).

Example:

<script type="text/javascript">
Tygh.$.ceFormValidator('setZipcode', {
 US: {
         regexp: /^(\d{5})(-\d{4})?$/,
         format: '01342 (01342-5678)'
 },
        CA: {
        regexp: /^(\w{3} ?\w{3})$/,
        format: 'K1A OB1 (K1AOB1)'
        },
        RU: {
        regexp: /^(\d{6})?$/,
        format: '123456'
        }
});
</script>

• cm-value-integer - assigned to a form element (input, textarea, etc.). Checks if the element value is a valid integer number while it is being filled.
• cm-value-decimal - assigned to a form element (input, textarea, etc.). Checks if the element value is a valid decimal float-point number while it is being filled.
• cm-integer - the element value must be an integer.
• cm-password - necessarily assigned to a pair of elements, their values must be the same.
• cm-multiple - at least one value of the element select is to be selected.
• cm-all - selects all options of the element select before sending a form.

Example:

<label for="a" class="cm-custom (check)"><input type="input" id="a" value="" />
<script type="text/javascript">

    function fn_check(id)
    {
        return (1 == 1) ? true : 'Not valid';
    }
</script>

The function accepts only one parameter - ID of the validated element.

• cm-regexp - checks the value for consistency with the regular expression. The regular expression is defined through the method $.ceFormValidator('setRegexp', {}).

Example:

<label for="a" class="cm-regexp"><input type="input" id="a" value="" />

<script type="text/javascript">
Tygh.$.ceFormValidator('setRegexp', {
        'elm_id': {
        regexp: "^[A-Za-z]+$",
        message: "Please, use only alphabetical signs"
        }
};
</script>

• cm-numeric - checks whether the value is a number with the help of autoNumeriс plugin. Plugin documentation: http://www.decorplanit.com/plugin/

Example:

<label for="a" class="cm-regexp"><input type="input" id="a" value="" />
<script type="text/javascript">
    regexp['a'] = {regexp: "^[A-Za-z]+$", message: "Please, use only alphabetical signs"};
</script>

Form processing¶

<form class="cm-ajax">
</form>

The microformat is defined by CSS class of the tag form. Classes can be combined.

• cm-ajax - the form will be sent by AJAX. For the correct work there should be a hidden element with the name result_ids:

  <input type="hidden" name="result_ids" value="id1, id2" />
  

• cm-ajax-full-render - can be used only with cm-ajax. Forces the whole page to be reloaded.

• cm-no-ajax - if this class is assigned to the submit button of the form, then when clicking on the button, the form will be sent in an ordinary way, even if the class cm-ajax is assigned to the form.

The events are used for pre/post AJAX-form submission. To declare the event, use the following rules:

• Pre-call: 'ce.formpre_[FORM_NAME]', [form, clicked_elm].
• Callback: 'ce.formpost_[FORM_NAME]', [form, clicked_elm].

Where:

• form - object, indicating the sent form.
• clicked_elm - object, indicating an element, that forced the form sending.
• [FORM_NAME] - name of the sent form.

Example:

$.ceEvent('on', 'ce.formpre_add_to_cart_form', function(form, elm) {
  // Some code here
});

• cm-check-changes - checks if there are unsaved changes in the form before submitting. If there are unsaved changes, a warning is displayed.

Automatically assigned to all POST-method forms in the admin panel:

if (_.area == 'A') {
   frms.filter('[method=post]').addClass('cm-check-changes');

• cm-disable-empty - assigned to a form. All non-obligatory unfilled fields will not be submitted. Used, for example, during product search to omit submitting multiple undefined parameters.
• cm-disable-empty-files - assigned to a form. All non-obligatory unfilled file fields will not be submitted.
• cm-failed-field - automatically assigned to a form field after a submit to highlight incorrectly entered data.
• cm-no-hide-input - allows to submit an empty input value even if the form has class cm-disable-empty.
• cm-trim - assigned to a label. Trailing spaces are removed from the value of the bound input during the validity check.

Form reset¶

• cm-reset-link - upon clicking on an element with this class the form values will be set to their default values. Used in the product search form.

Form fields content selecting¶

• cm-select-text - when clicked, the elements with the select method will be highlighted (textarea, input). Makes copying to buffer easier.

Form reload¶

• cm-reload-form – assigned to a form element. When this element is changed, the given form will be reloaded using a GET-request.

Pickers in forms¶

• cm-ajax-content-input - used, for example, in a picker when a search request is entered to enable autocompletion. An AJAX request for autocomplete is sent with the delay of 500 ms after the input is stopped. The received content is loaded in the container stated in the rev attribute. The autocomplete pattern is taken from the value parameter.

  Example: Vendor selecting through a picker in Multi-Vendor.

• cm-ajax-content-more - when the element becomes visible (for example, in a big drop-down list), additional content is loaded.

  Example: Vendor selecting, when the number of options is big, through a picker in Multi-Vendor.

• cm-cancel - when a button with this microformat is clicked, all picker fields are set to their default values.

• cm-clone - used for item adding to a picker without it getting closed (e.g. without an AJAX-request).

  Example: On the promotion page upon adding multiple products/categories from a picker. Assigned directly to the empty string, that is cloned upon item adding.

• cm-dialog-opener - assigned to an element that must open a dialog. The dialog container is defined in the rev parameter.

  Example: Products -> Categories. The Edit link has this class.

• cm-dialog-closer - assigned to an element that must close a dialog.

  Example: The Cancel button in pickers.

• cm-dialog-keep-in-place - not yet implemented.

• cm-dialog-auto-open - when a page is visited, this class automatically opens a dialog box. It is used in the administration panel in the welcome screen.

• cm-dialog-auto-size - used together with cm-dialog-opener. The width and height of a dialog box depend on content when this class is used.

• cm-dialog-auto-width - used together with cm-dialog-opener. The width of a dialog box depends on content.

• cm-dialog-switch-avail - unselects all selected checkboxes in a dialog box.

• cm-js-item - when adding an element to a form from a picker (for example, product adding to a gift certificate) this class is assigned to the container, where the added element resides.

• cm-picker-options - product options will be received upon product transfer from a picker, if this class is assigned:

  <tbody id="{$data_id}" class="{if !$item_ids}hidden{/if} cm-picker-options">
  

Sending a form with a click on any NON-input[type=submit] element¶

Usage:

<input type="radio" name="a" value="b" class="cm-submit" />

The microformat is defined by CSS class of the element. Classes can be combined.

• cm-submit - the form, to which this element is assigned, will be sent after the element is clicked.

  In order to submit a form with a click on a non-button element:

  • Assign the microformat cm-sumbit to the element.
  • In the data-ca-dispatch attribute, provide the dispatch to which the form is submitted (in the format dispatch[controller.mode]).
  • Optional, only if the element is outside the form to submit: In the data-ca-target-form attribute, provide the form name or id.

Sending a form to a new or a parent window¶

Format:

<input type="submit" name="a" value="b" class="cm-new-window" />
<input type="submit" name="a" value="b" class="cm-parent-window" />

The microformat is defined by CSS class of the tag input. Classes can be combined.

• cm-new-window - when clicked, a new window will be opened and the form will be sent there.
• cm-parent-window - when clicked, the form will be sent to a parent window.

Form submitting prohibition¶

Usage:

<input type="submit" name="a" value="b" class="cm-no-submit" />

The microformat is defined by CSS class of the tag input. Classes can be combined.

• cm-no-submit - the form, to which this element is assigned, won’t be sent after the element is clicked.

Skipping field validation in a form¶

Format:

<input type="submit" name="a" value="b" class="cm-skip-validation" />

The microformat is defined by CSS class of the tag input. Classes can be combined.

• cm-skip-validation - when clicking on an element, the form to which this element belongs is sent without validating the elements values.

Form hiding¶

• cm-hide-inputs - input elements with this class are displayed as plain text (not editable).

  Example: Used in Multi-Vendor in forms for vendors to display the fields they can’t edit as text.

• cm-hide-save-button - assigned to a tab where the buttons (not necessarily Save buttons) with this class should be hidden.

Checkboxes in forms¶

Format:

<input type="checkbox" name="check_all" value="Y" class="cm-check-items" />
...
<input type="checkbox" name="product_ids[]l" value="1" class="cm-item" />
<input type="checkbox" name="product_ids[]l" value="2" class="cm-item" />

<a href="#" name="check_all" class="cm-check-items on">Check all</a>/<a href="#" name="check_all" class="cm-check-items off">Uncheck all</a>

There are 2 types of checkboxes manipulation:

• Via the main checkbox
• Via links

The control element must have the name check_all and the class cm-check-items. If the control element is a link, the classes on and off are to be also specified (they turn on and off all checkboxes).

Manageable elements must have the class cm-item.

The class cm-process-items can be assigned to the button sending the form. In this case when the button is clicked on, the corresponding group of checkboxes will be checked to find out whether the checkboxes are off or on. If none of them is on, a message will be displayed.

<input type="checkbox" name="check_all" value="Y" class="cm-check-items-group" />
...
<input type="checkbox" name="product_ids[]l" value="1" class="cm-item-group" />

Links¶

There is a microformat that allows to execute AJAX request when clicking on a link. Format of this link:

<a class="cm-ajax" href="https://www.cs-cart.com" data-ca-target-id="pagination_contents">Ajax link</a>

The microformat is defined by CSS class of the tag a. Classes can be combined.

• cm-ajax - AJAX request will be executed when clicking on a link.
• cm-comet - the form is refreshed using the Comet model.

Example: database back-up form.

• cm-delete-row - when clicking on the element with this class, the nearest parent element tr is deleted. It is used to delete a row in a table.
• cm-row-item - assigned to a table row. Used for container identification together with cs-delete-row.
• cm-ajax-cache - allows to cache AJAX requests, should be used together with cm-ajax.
• cm-ajax-force - allows to execute js code from the ajax response for the second time. It should be used together with cm-ajax.

When it is necessary to click on an element with the known ID, you can use a link with the class cm-external-click. ID of the element that should be clicked on is specified in the parameter data_ca_scroll of the link:

<a class="cm-external-click" data_ca_scroll="external_elm">Push me</a>

• cm-external-focus - passes focus to an external element when an element with this class is clicked. The external element ID is defined in the rev parameter.
• cm-smart-position - used for container positioning (for example, the Select currency list in the administration panel).

Notifications¶

• cm-auto-hide - a notification with this class will automatically fade out. The timeout is set in Settings -> Appearance.
• cm-notification-close - assigned to a notification close button. On click the notification is either removed from the form or a notification removal AJAX-request is sent.
• cm-notification-container - assigned to a notification container.

Other elements¶

• cm-confirm - when clicked, confirmation of the action will be requested.

• cm-noscript - this element will be shown only if javascript support is enabled in a browser.

• cm-focus - elements with this class get focus when a page is loaded.

  Example: Focus is on the login field, when the entry form is loaded.

• cm-opacity - assigned to a removed table row making it translucent.

  Example: A cloned and then removed “row” upon product image adding. The removal from the page is executed on page reload, until that the “row” remains translucent.

• cm-uploaded-image - assigned to a div element with an uploaded image. Used for uploaded images count.

• cm-wysiwyg - assigned to a textarea. Provides an editor for advanced text formatting.

• cm-row-status-[current status code] - assigned to a row in list (the <tr> element). Indicates the current status code of an item (e.g. a for Active, d for Disabled, etc.)

• cm-autocomplete-off - removes the chance of autofill from a field. It is used in the password input field.

Popups¶

The microformat popup-box is available for popups. It allows to close a popup with a click outside its area.

Format:

<div class="cm-popup-box">
...
</div>

To hide a popup with a click on some element inside its area, it is necessary to define the class cm-popup-switch for this element.

Format:

<div class="cm-popup-box">
<strong class="hand cm-popup-switch">Close</strong>
...
</div>

• cm-select-option - used in the administration panel for the bootstrap popup.
• cm-popover - initializes popover bootstrap (http://getbootstrap.com/2.3.2/javascript.html#popovers).

Switching combinations¶

To switch combinations (for example, to display/hide all elements of the tree) the microformat cm-combinations is used:

<img src="" id="on_cat" class="cm-combinations" />
<img src="" id="off_cat" class="cm-combinations hidden" />

ID here is used ONLY to group these two elements. Also, there is an ability to group combinations (for instance, several trees on a page). To do this it is necessary to add a suffix:

<img src="" id="on_abc" class="cm-combinations-a" />
<img src="" id="off_abc" class="cm-combinations-a hidden" />
...
<img src="" id="on_cat" class="cm-combination-a" />
<img src="" id="off_cat" class="cm-combination-a" />
<a href="#" id="sw_cat" class="cm-combination-a">
...
<div id="cat">
</div>

In this case, when clicking on the upper images, only combinations from the group ‘a’ will be shown/hidden.

Sorted list¶

Such list can be seen, for example, on the currency edit page: when a row is dragged, its position is changed.

• cm-sortable assigned to a container of sortable rows (cm-sortable-row).

  Example: Currency list in the administration panel.

• cm-sortable-id-* - an ID of a particular row in a cm-sortable container. A value after cm-sortable-id- is passed in a request and used to store changes.

• cm-sortable-row - assigned to a draggable table row. The row must be placed in a cm-sortable container.

File uploader¶

• cm-fu-file - assigned to a uploaded file block in the file uploader (filename and a remove cross are shown in a block). If there is no file, a block is hidden. Otherwise shown.
• cm-fu-no-file - assigned to an element that enables file uploading. Any file uploader can be considered as an example.