Quick links: Content - sections - sub sections
EN FR

The html generator relies on jquery. Specifically some fields and its javascipt depend heavily on it. It is the default jelix generator for jForms. html is the name to give to {form} and {formfull} template plugins, if needed.

Usefull CSS classes

Here is a reference of classes attributes generated by jforms.

  • jforms-table : class of <table> generated with formfull
  • jforms-submit-buttons : class of <div> generated with formfull, and containing submit/reset buttons
  • jforms-submit : class of each submit
  • jforms-reset : class of each reset
  • jforms-hidden : class of each hidden field
  • jforms-error-list : class of error messages list(ul) .
  • jforms-label : class of each <label>
  • jforms-required : class of each required control <label>
  • jforms-error : class of each <label> and fields whose controls are erroneous
  • jforms-readonly : class of each readonly controls
  • jforms-value : class of <span> displaying fields value.
  • jforms-help : class of <span> containing help llinks.
  • jforms-chkbox : class of each <span> wrapping a checkbox widget of a checkboxes control.
  • jforms-radio : class of each <span> wrapping a radio widget of a radiobuttons control.
  • jforms-ctl-xxx : class of each checkbox of a checkboxes control, class of each radio of a radiobuttons control (xxx equals ref of current control).
  • jforms-captcha-question : class of each <span> wrapping a captcha question...
  • jforms-table-group : class of a <group> control table.
  • jforms-choice : class of an items list in a <choice> control.
  • jforms-item-controls : class of each <span> wrapping an item widget of a <choice> control.
  • jforms-submit-buttons : class of <div> generated with formfull, and containing submit/reset buttons
  • jforms-submit : class of each submit
  • jforms-reset : class of each reset

.jforms-table {}
.jforms-hidden {}
.jforms-error-list {}
.jforms-label {}
.jforms-required {}
.jforms-error {}
.jforms-readonly {}
.jforms-value {}
.jforms-help {}
.jforms-chkbox {}
.jforms-radio {}
.jforms-ctl-xxx {} /* xxx must be replaced by your control ref */
.jforms-captcha-question {}
.jforms-table-group {}
.jforms-choice {}
.jforms-item-controls {}
.jforms-submit-buttons {}
.jforms-submit {}
.jforms-reset {}

Customizing messages display

jForms deals with two types of messages :

  • error messages generated by form checking
  • help messages accessible through interrogative point

those messages defaultly display in an alert box.

You can customize this behaviour. Transmit your own javascript messages display function to form or formfull plugins.

Error messages display

To customize display of error messages, you shall define a javascript object implementing 3 methods:

  • start, called when checking process starts.
  • addError, called when an error is found. it receives a jFormsControl argument, which contains infos about the erroneous control, and an error code. the latter equals 1 if user has not edited a required control, 2 if its content is invalid.
  • end, called when checking process ends.

You're obviously free to do whatever you need/want in those methods. As for example, you could add the error messages to an error lists ( <ul> located in your html page):


function MyErrorDecorator(){
}

MyErrorDecorator.prototype = {
    start : function(){
    },
    addError : function(control, messageType){
        var message='';
        if(messageType == 1){
            message = control.errRequired;
        }else if(messageType == 2){
            message = control.errInvalid;
        }else{
            message = "Error on '"+control.label+"' field";
        }
        var item = document.createElement("li");
        item.appendChild(document.createTextNode(message));
        document.getElementById("errors").appendChild(item);
    },
    end : function(){
    }
}

Then, declare your MyHelpDecorator object as fourth argument of form or formfull:


  {form $form, 'mymodule~default:save', array(), "MyErrorDecorator"}
   ...
  {/form}

Details about jFormsControl object passed to addError (named control above), and its properties:

  • name : control or field name
  • label : its label
  • datatype : its data type (type attribute in your XML file)
  • required : boolean, true if required
  • readonly : boolean, true if readonly
  • errInvalid : invalid error message defined in your XML file
    • errRequired : required error message defined in your XML file
  • help : help message defined in your XML file

Help messages display

As for error messages, your javascript object displaying help messages is equivalent except that only one method is required: show. show will be called with an help message to be displayed as argument.


function MyHelpDecorator(){ }

MyHelpDecorator.prototype = {
    show : function(message){
        document.getElementById("help").firstChild = document.createTextNode(message);
    }
}

Then, declare your MyHelpDecorator object as fifth argument of form or formfull:


  {form $form, 'mymodule~default:save', array(), "", "MyHelpDecorator"}
   ...
  {/form}

Note that here "" is passed as error decorator. This way, jForms will use its default errorDecorator. Of course, if you have your own, you'd better pass it as argument also.

jQuery and your application

HTML generator forces jQuery inclusion on every HTML response including a jForm. Thus, if you already link to jQuery script elsewhere in your appplication, such as in your common response, you should take care to include the very same script. Otherwise, your user will download it twice.

Example in a common respsonse :


  $this->addJSLink($GLOBALS['gJConfig']->urlengine['jelixWWWPath'].'jquery/jquery.js');