Change-Actions
Change-actions allow for a direct interaction with the server. They provide an alternative to forms, to send data to the server, without the need for an explicit submit action.
Introduction
Change-actions are a type of event-actions in which the action is performed on the server. They typically react on change, which is why they are called change-actions.
They are written as event-action attributes where the attribute value is the URL to be invoked when the event (usually a change event) takes place. They can be applied on form controls (INPUT, SELECT and TEXTAREA elements) or on their parent elements.
The server acknowledges the change with its response:
- Any success status code (generally 200, 202 or 204) without further content:
the change is accepted; - Any success status code with as response content a new value encoded in Json:
the control gets the new value the server returned; - Any success status code with as response content encoded in HTML:
the request scope or target gets replaced by the given HTML; - Any failure status code (400+ or 500+):
the change is rejected or failed, the control value reverts to the previous value.
Change-actions are meant to offer an alternative to forms, as they send any control value change to the server. Except they do not need a FORM element, they do not need a submit action, they send one control at a time and they do so as soon as a change event is received.
Handling change
Change actions are principally meant to handle change events. Their exact behavior depends on the type of control they are applied on:
Checkboxes or radio buttons
When the onchange-action attribute is placed on the checkbox or radio INPUT element, the change-action handles changes on the individual control:
<label>
<input type="checkbox" onchange-action="/SubscribeTo?NewsletterId=44" />
Subscribe to weekly newsletter
</label>In this example, when the checkbox is checked, a request will be issued to the following URL:
/SubscribeTo?NewsletterId=44&checked=true
If the checkbox is unchecked, the checked parameter will have the value false.
If the checkbox or radio button has a name and/or a value, those will be included as parameters as well:
<input type="checkbox" name="Newsletter" value="44" onchange-action="/SubscribeTo" />When checked, this checkbox will result in the following request URL being invoked:
/SubscribeTo?name=Newsletter&value=44&checked=true
If the checkbox is unchecked, the checked parameter will have the value false. The other parameters remain unchanged.
Group of checkboxes or radio buttons
When the onchange-action attribute is placed on a parent element of a checkbox or radio INPUT element, its behavior changes to handle groups of checkboxes or radio buttons. There will be no checked parameter anymore, and the values will be given for checked elements only.
An example:
<fieldset onchange-action="/DeliveryInfo">
<legend>Delivery mode</legend>
<input type="radio" name="Mode" value="LND" /> Over land </br/>
<input type="radio" name="Mode" value="SEA" /> Over sea </br/>
<input type="radio" name="Mode" value="AIR" /> In the air </br/>
<input type="checkbox" name="Options" value="Refr" /> Refrigerated <br/>
<input type="checkbox" name="Options" value="Expr" /> Express delivery
</fieldset>This example includes both a set of radio buttons and a set of checkboxes under the same change-action.
If the user chooses the "Over land" option, the following action is sent to the server:
/DeliveryInfo?name=Mode&value=LND&Mode=LND
The name parameter indicates the name of the changed control. The value parameter, its current value. The value is also made available through a name=value pair.
If the user switches to "Over sea", the following action is sent:
/DeliveryInfo?name=Mode&value=SEA&Mode=SEA
If the "Refrigirated" option is choosen, the server receives:
/DeliveryInfo?name=Options&value=Refr&Options=Refr
Notice that though a value has been choosen for Mode, it was not the subject of the current change-action. Only the value of the "Options" checkboxes is sent since it is on the Options that the change event occured. This is different from forms which send values of all their controls when they are submitted.
If also the "Express delivery" option is chosen, the server receives:
/DeliveryInfo?name=Options&value=Refr&Options=Refr&value=Expr&Options=Expr
Though only the "Express delivery" option was changed, the change-action sents to the server the current value of all checkboxes with the same name, in scope of the triggered onchange-action attribute.
If both checkboxes are unchecked, the following action is sent to the server when the last checkbox is unchecked:
/DeliveryInfo?name=Options
The name of the changed control is "Options", and there is no value.
Text inputs, textareas and selects
For other controls, the server receives a name parameter with the name of the changed control, a value parameter with its current value, as well as a name=value pair.
<input type="email" name="Email" onchange-action="/Update" />On change, the following action is sent to the server, if a value is entered:
/Update?name=Email&value=joe%40example.com&Email=joe%40example.com
If the value is cleared, the action is:
/Update?name=Email&value=&Email=
If the control element is named "name", the name=value pair takes precedence. If the control element is named "value", there will be no duplicate value parameter.
Multivalue selects
A multivalue SELECT element behaves much like a group of checkboxes, which makes them also interchangeable. The action URL contains a name parameter, as well as a value parameter and a name=value pair for each selected value:
<select name="Visited" multiple onchange-action="/Store">
<option>New York</option>
<option>London</option>
<option>Brussels</option>
<option>Bangkok</option>
</select>For instance, if the first two values are selected, the following action is sent to the server:
/Store?name=Visited&value=New%20York&Visited=New%20York&value=London&Visited=London
Handling input
On textual controls, the change event is raised when the control looses focus. To have the change-action called as soon as input is typed (with respect of an idle period of 0.8 seconds by default), use the oninput-change class or attribute (see Forms chapter for details).
The following example produces an auto-complete effect by issuing an action on input, that fills a DATALIST element linked to the input field:
<input type="text" list="items" class="oninput-change" onchange-action="/AutoComplete"
target="#items" browser-cache="on" />
<datalist id="items"></datalist>The input field has a list named "items".
The oninput-change class triggers a change event when input is detected. That change event translates into a call to "/Autocomplete", for instance, if the user enters "john" and then waits for 0.8 seconds, the following action is invoked:
/AutoComplete?value=john
Based on this request, the server is expected to return HTML content, which - due to the target="#items" attribute - will be inserted in the items list. The server could for instance return:
<option value="John Kennedy">
<option value="John Travolta">
<option value="Peter Johnsson">As a result, the datalist will appear offering these options to auto-complete what the user is typing.
The browser-cache="on" attribute allows the browser (or intermediate infrastructure) to cache the request. If the URL contains all the context of the request and security is not compromised, caching can be used to increase the response speed and limit the number of server requests. By default, caching is disabled on change-action requests.
Handling focus
Two change-actions do not react un change, but on focus: onfocus-action and onfocusout-action.
These focus actions are available on INPUT elements that are not checkboxes, radios or buttons, as well as on TEXTAREA elements, and can only be placed on the element itself.
They can for instance be used to format/unformat values:
<input type="text" name="Price" onfocus-action="/Unformat" onfocusout-action="/Format" />If the user enters the value "1000" and leaves the field, the /Format action will be triggered that could set the field content to "$ 1,000.00". When the field regains the focus, the /Unformat action will be triggered, which could return the field content into "1000".
To do so, the /Format and /Unformat actions must return a Json string object with the new field content. For instance:
"1000"Field substitution
The URL of an action can be whatever you want. The URL is then extend with the name and value of the changed control. To add values of neighbour controls, you can use field substitution.
For field substitution to work, the element holding the onchange-action attribute, must also have the class substitute-fields. The action URL can then contain references to other fields by placing their name between square brackets ([ and ]).
<input type="hidden" name="CID" value="345" />
<input type="text" class="substitute-fields" name="Name" onchange-action="/Process?Id=[CID]" />Here, when a change occures in the Name field, the "[CID]" part of the action URL will be replaced by the value of the "CID" named field (in this case, a hidden INPUT field). For instance:
/Process?Id=345&value=Jack&Name=Jack
When the control raising the change event is part of a form, only fields inside the form can be referenced. If the control raising the change event is not part of a form, the whole document is searched for fields to substitute.
When more than one matching field is found, only the value of the first one will be substituted.
Get or Post
By default, change-actions are sent to the server with the GET method. To send them using an HTTP POST method, add the method="post" attribute on the element with the onchange-action attribute:
<input type="email" name="Email" onchange-action="/Update" method="post" />Browser caching is disabled, but can (for GET requests) be enabled by adding the browser-cache="on" attribute on the element holding the change-action attribute.
Server responses
When the server processes a a change action, it can react in different ways.
No content
The most basic response from the server on a change action, is to return no content. It can therefore use the 204 "No content" response status code, but it can also just return status code 200 with no content.
In that case, the change is considered acknowledged. The server received and processed the change action (i.e. updated the database), and no further action is required.
Json content
If the server responds with a Json value (Content-Type response header must be set with value "application/json"), then this value is used to update the value of the control that triggered the change action.
As the Json value should be the value of the current control or control group, it should be either a string, or an array of strings.
The above /Format and /Unformat focus actions return a formatted or unformatted representation of the value by means of a Json string.
HTML content
The server can also choose to return HTML, as is the case in the above auto-complete example. In that case, the server sets the Content-Type response header to "text/html" and returns HTML code.
The element holding the change-action attribute should also have a target attribute referencing the element to hold the returned HTML by way of a CSS selector (relative CSS selectors are supported). If no target attribute is set, it is the element itself, having the change-action attribute, that will be used as target.
Error
If the server returns an error (HTTP status code 400+ or 500+), then the change that led to the change-action request, will be reverted. If a checkbox was checked, it will be unchecked again. The value of a textfield will be restored. Etc.
When an error occures during a change-action request, Sircl assumes the server could not process/persist the requested change, and therefore, the change must be undone.
Alert message
Independent of the type of response (no content, Json content, HTML or error), the server can also return an X-Sircle-Alert-Message response header with as value, text to show in an alert message dialog. For instance:
X-Sircl-Alert-Message: Data changed.
Styling
When a change-action server request is issued, the element holding the change-action attribute gets the action-pending class. As soon as the server request ends, this class is removed again.
This class can be used to style controls and control groups during the processing of a change action request:
<style>
.action-pending {
background-color: lightyellow;
}
</style>