Using AJAX With Forms

AJAX provides the ability to update parts of a website page or form, without reloading the entire page. Some common scenarios for using AJAX with Oncord forms:

1. Show or hide form fields as the user is completing a form (often referred to as "conditional fields").

2. Show or hide the form's submit button, depending on whether the user has accepted some terms and conditions. 

3. Render a list of Products or Posts on the page, depending on what the user enters into a search box.

The Three Required Elements

1. When a user interacts with a particular page element, a JavaScript Event is triggered.
2. The JavaScript Event then triggers an AJAX Event.
3. When an AJAX Event is triggered, it is configured to update AJAX Region(s).  

JavaScript Events (such as a clicking a checkbox, or changing a text field), are used to trigger an AJAX Event.

When an AJAX event is triggered, the content within an AJAX Region is refreshed.

As a simple example, the following solution will show or hide a form field, depending on whether the user has ticked a checkbox.

<p>Tick the box below to see a block show or hide.</p> <forms:form> <ajax:event id="showhide_checkbox_ajaxevent" updateregions="showhide_ajaxregion" /> <forms:row label="Tick this box..."> <forms:checkbox id="showhide_checkbox" onclickajax="showhide_checkbox_ajaxevent" label="Click for More Options" /> </forms:row> <ajax:region id="showhide_ajaxregion"> <logic:if test="$showhide_checkbox.checked"> <forms:row label="And then these options show..."> <forms:editbox id="moreoptions" /> </forms:row> </logic:if> </ajax:region> <forms:row type="one_column"> <forms:submitbutton>Submit Enquiry</forms:submitbutton> </forms:row> </forms:form>


Line 5: An AJAX Event, which defines the AJAX region to be updated.
Line 8: A Checkbox, using a JavaScript onClick event to trigger an AJAX Event.
Line 11: The AJAX Region to be updated.
Line 12: A Logic IF test to determine whether the checkbox was checked.

Step One: A JavaScript Event

JavaScript Events can be added as an attribute to any Oncord UI Control, or HTML form element. 

Any JavaScript Event can trigger an AJAX event, however in most cases you will use one of the events shown below.

Important: With Oncord, you need to specify the native event name (eg. onclick), followed by "ajax". For instance, "onclick" becomes "onclickajax".

onChangeAjax: Triggers when an element has been changed. Useful for triggering an event when the content of a form text field has been changed.

onClickAjax: Triggers when an element has been clicked. Useful for triggering an event when a checkbox has been clicked.

onFocusAjax: Triggers when an element is in focus.

The JavaScript Event attribute is provided with the ID of the AJAX Event that will be triggered.

For example, onchangeajax="an_ajax_event_id".

The following example shows a checkbox using onclickajax to trigger an AJAX event with the ID "showhide_checkbox_ajaxevent" (more on AJAX Events below).

<forms:form> <forms:checkbox id="showhide_checkbox" onclickajax="showhide_checkbox_ajaxevent" label="Click for More Options" /> </forms:form>


Step Two: An AJAX Event

The <ajax:event /> control is used to define an AJAX Event, which defines the AJAX Regions to be updated when the event is triggered.

The updateRegions attribute defines the ID of the ajax region to refresh. You can refresh multiple AJAX Regions by separating their IDs with commas. 

As an example, the following AJAX event will update the AJAX region with the ID "showhide_ajaxregion".

<ajax:event id="showhide_checkbox_ajaxevent" updateregions="showhide_ajaxregion" />

Step Three: An AJAX Region

The <ajax:region> control defines a region to be updated / refreshed when an ajax event is triggered.

<ajax:region id="showhide_ajaxregion"> The Content To Be Refreshed </ajax:region>


Within an <ajax:region> it's common to use logic controls such as <logic:if> to run a test to determine the content that show be shown. 

An Example

As a simple example, the following solution will show or hide a form field, depending on whether the user has ticked a checkbox.

Line 3: An AJAX Event, which defines the AJAX region to be updated.
Line 7: A Checkbox, with a Javascript onclick event to trigger an AJAX Event.
Line 10: The AJAX Region to be updated.
Line 11: A Logic IF test to determine whether the checkbox was checked.

<p>Tick the box below to see a block show or hide.</p> <ajax:event id="showhide_checkbox_ajaxevent" updateregions="showhide_ajaxregion" /> <forms:form> <forms:row label="Tick this box..."> <forms:checkbox id="showhide_checkbox" onclickajax="showhide_checkbox_ajaxevent" label="Click for More Options" /> </forms:row> <ajax:region id="showhide_ajaxregion"> <logic:if test="$showhide_checkbox.checked"> <forms:row label="And then these options show..."> <forms:editbox id="moreoptions" /> </forms:row> </logic:if> </ajax:region> <forms:row type="one_column"> <forms:submitbutton>Submit Enquiry</forms:submitbutton> </forms:row> </forms:form>