Warning ! this module is no longer supported
( Please read this before considering using it)

Description

The form example below illustates what the field group library is all about: it groups a few related fields and attach them parametrable behavior. One of the fields play a special role; we call it the field group controller. So, what can be do once field are grouped ? Here is a sample list:

How to use it

Declaring groups

You can use one of those 3 possibilities, depdending on which is the best in your case:

  1. implicit membership : group all fields within a continuous portion of the document. In this case, the root node of this portion will contains the "mjstype=fieldGroup" attribute, and at least one of the child element will have the "mjstype=fieldGroupController" attribute. This is the easiest way of creating groups. Note that the value of the msjtype attribute is case insensitive: mjstype="FIELDGROUP" and mjstype="fieldGROUP" would work equally. This is the simplest approach, and is recommended for use when possible.

    mjstype=fieldGroup
    Identifies the root node of the field group (all fields within the group will have this element as ancestor)
    mjstype=fieldGroupController
    this field identifies the "group controller" that manages the state of the "field group" by disabling/enabling members according to its value.
    Your form should look something like this: 
    <form ...>
    <fieldset mjstype="fieldGroup"> <!-- Root node of the field group -->
        <legend>
            <!-- this checkbox controls the whole fieldset -->
            <input mjstype="fieldGroupController" name="food"
               type="checkbox" value="checkbox">
               Edit this group
        </legend>
        ...
        <label>Which fruit?</label><input type="text" name="fruit">
        ...
    </fieldset>
<form>
  2. explicit membership : attach group members and controller(s) to groups via the "mjsgroup=groupName" attribute. This mecanism is useful when the group members are disseminated across the document. All elements having the same "mjsgroup" attribute belongs to the same field group. If an element needs to be part of multiple groups, you can declare them using the "&" separator: "mjsgroup=group1&group2".
  3. explicit members : the last possibility you have is to enumerate group members at controller level through the "mjsmembers=idElem1&IdElem2&IdElem3" attribute. This attribute gives a "& separated list of ID, which identify every element within the group. This also impose you to add ID attributes to every member obviously.

    HTML 
    <input mjstype="fieldGroupController" mjsmembers="eulaOk" ...>
<input id="eulaOk"...>
    UI

Attaching behaviors

By default, the framework attaches the bahavior "enable" to every field group controller. This behavior controls group members editability. You can change this by adding a "mjsgroupmode" attribute, which may contain the following value:

mjsgroupmode=enable / mjsgroupmode="enable&clear"
Set the enable behavior. When adding "clear", it also empty member content (your server program will receive empty value for disabled dields within this group).
mjsgroupmode=copy
Only valid when the controller is a checkbox, and group members are also checkboxes. It copies the state of the controller into members.
mjsgroupmode=check
Only valid when the controller is a button or a link, and group members are checkboxes. It set all members to "checked" state.
mjsgroupmode=clear
Only valid when the controller is a button or a link. It empty the content of all members.
mjsgroupmode="code=<javascript code>;"
Only valid when the controller is a button or a link. Perform the given javascript code for every member. In the javascript code, 'this' matches the member it runs for.

Restrictions & traps

  1. the current version only support controllers as checkboxes, radio buttons and buttons
  2. Remember that client-side controls shall not be taken as reliable for data verification purposes: while this library offers a better user experience, it doesn't take the place of proper data validation by your server!

Styling disabled elements

BEWARE: dynamic styling works very differently depending on browsers. The following example has been successfully tested on mozilla and IE, but opera do not seem to handle it at all.

Some web browsers render disabled fields in a way that is either not pleasing, or without the visual cues a user would need to recognize that the fields are actually disabled. To compensate for this, you may want to dynamically associate a CSS class with disabled items. This framework provide automation for this, As you can see in the example below, we use CSS declarations to make the field content invisible by applying identical color on text and background:

HTML 
<fieldset mjsDisabledClass="demoDisabledTest" mjstype="fieldGroup">
    <legend>
        <input mjstype="control" type="Checkbox" value="checkbox" ...>
        Edit this group
    </legend>
    <table>
    ...
UI
Edit this group
Field 1
Field 2

While the classes themselves are defined as you would any other CSS class (in an external linked sheet, or in a <style> tag), the dynamic effect is set up with custom attribute "mjsDisabledClass" in which the value correspond to the apporpriate CSS classes. The class is applied to individual members of the group when they get disabled.

For the above example, we use the following CSS:
// Render disabled controls
// Using 'mjsDisabledFieldGroupClass=Disabled'

.MyDisabledClass input 
{
    background-color: #F0F0F0;
    color: #F0F0F0;
}

Of course, this is just an example. You may want to try using variations in display or visibility properties to remove the fields from view.

Because these "mjsdisabledclass" attributes are inherited from parent nodes, you can define them once for the whole group, or even once for the whole document wherever it is convenient, such as an arbitrary block element containing the whole group, or within the <body> tag for example.

Alternately, you may prefer the use of the javascript API to define the value in all your documents (see the API paragraph, further in this page)

Technical notes

How it works

At initialization time (after the document is fully loaded), the module parses the DOM tree and searches elements having a relevant attribute vis a vis the field group feature. It uses this information to build its internal structure which describe how groups are organized (members, controllers and behaviors). It also attaches necessary callbacks (click, change) so thet user interactions trigger the right behaviors.

JavaScript API

mjs_setDisabledClass(className)

Defines a CSS class name for individual fields that get disabled by this API. Note that a declaration at the HTML element level prevails to the values set via this function.