Event-Actions

Event-Actions and Action-Events allow adding behavior in reaction to events without the need for writing client-side (Javascript) code, or perform post-backs to the server. They help making websites and applications more interactive.

Anatomy

Event-actions are a Sircl extension to HTML providing default actions on events. Event-actions can occure as class or as attribute. The name is made up by concatenating the event name with the action name, separated by a dash. The trigger element of the event is the element the event-action is placed on. If the action requires a subject or object, it is described in the attribute value.

For instance, the onclick-show event-action is triggered by the click event on the element it is written on. The action is to show (unhide) some page element(s). The page elements to show are descibed by means of a CSS selector attribute value of the event-action:

<button type="button" onclick-show="#moreinfo">Click me for more info</button>
<p id="moreinfo" hidden>
  More information...
</p>

Some event names start with on, while others start with if. The difference is that an on-event-action is only triggered when the event occures, while an if-event-action is triggered when the event occures, but is also evaluated when te page (part) is initialized (after being loaded). For instance, in the following example the "phone" input field will intially be disabled because the checkbox is not initially checked:

<label>
  <input type="checkbox" ifchecked-enable="#phone" />
  I have a phone
</label>
<br/>
<input id="phone" type="text" placeholder="Phone number" />

There is also something as action-events, where the action name comes before the event name. The action is applied on the current element, while the trigger of the event is described in the value of the action-event attribute. For instance: enable-ifanychecked. It is typically used to enable a button when one or more checkboxes are checked to select elements the button should act on.

Overview

The following section provides an overview of the existing event-actions and action-events in the core and extended libraries.

The core library (sircle.js) contains the core functionality of issueing and handling Ajax requests, page part loading, Multi Page and Single Page mode, routing, error handling and extensibility.
It contains a limited set of event-actions to provide the basic support for server-side rendering without the need for writing Javascript.

The extended library (sircl-extended.js) provides additional event-actions allowing to limit the server interactions and provide higher interactivity.

Other libraries, such as the Bootstrap extensions or the Change Actions also define event-actions which are described in their respective chapters.

Note: In future versions of Sircl, features can be "promoted" and moved from the extended library (or other additional libraries) to the core library. This is not considered a breaking change as the extended (and other additional) library requires the core library to be present.

Click related event-actions

Onclick actions

Onclick events are triggered when an element is clicked on.

In the following example, clicking the button makes the button be replaced by a set of options:

<button onclick-show="#extopt" onclick-hide=":this"> More options </button>
<div id="extopt" hidden>
  <label><input type="checkbox"> Option 1</label><br/>
  <label><input type="checkbox"> Option 2</label><br/>
  <label><input type="checkbox"> Option 3</label><br/>
</div>

Ondblclick actions

Ondblclick events are triggered when an element is double-clicked on.

In the following example, double-clicking the image will load help information in the DIV element with the help id. Notice how the target attribute can be used to indicate where to load the content.

<img src="/lib/images/help.png" ondblclick-load="/GetHelp" target="#help"/>
<div id="help"></div>

Keyboard related event-actions

Onkeykey actions

Onkey<key> events are triggered when the given key is pressed wihin the scope of the element holding the onkey event-action attribute. They only exist for specific keys: the Enter key and the Escape key, and allow to define or override default key behaviors in forms and dialogs.

In the following example, pressing Enter will not delete, but update the data:

<form onkeyenter-click="#updbtn">
  <input name="Name">
  <button id="delbtn" type="submit" formaction="/Delete?id=4">Delete</button>
  <button id="updbtn" type="submit" formaction="/Update?id=4">Update</button>
</form>

Onkeydown actions

Onkeydown events are triggered when a key or keycombination is pressed on the keyboard anywhere on the page. They are page-wide events. The action (to click), is performed on the element holding the onkeydown event-action attribute whereas the key to capture is the value of the attribute.

The following example shows a pagination control where the ← (left arrow) and → (right arrow) keyboard keys can be used to navigate between the pages:

<nav>
  <ul class="pagination">
    <li><a href="#" onkeydown-click="ArrowLeft">Previous</a></li>
    <li><a href="#">1</a></li>
    <li><a href="#">2</a></li>
    <li><a href="#">3</a></li>
    <li><a href="#" onkeydown-click="ArrowRight">Next</a></li>
  </ul>
</nav>

Key code can be any character (alfanumeric or symbol) on the keyboard, the function keys "F1", "F2", etc. or special keys as "Enter", "Escape", "ArrowUp", "ArrowDown", "ArrowLeft", ArrowRight", "Home", "End", "PageUp", "PageDown", "Insert" and "Delete". The code can be prefixed by "Alt+", "Ctrl+" and/or "Shift+" in that order.

Form related event-actions

Onchecked actions

Onchecked events are triggered when a radiobutton or checkbox is checked interactively.

The following example opens a dialog when the checkbox is checked. It uses a hidden button to open the dialog in reaction to a click event:

<label><input type="checkbox" onchecked-click="#opendlgbtn">Accept these conditions</label>
<button id="opendlgbtn" hidden onclick-showdialog="#dlg">(hidden)</button>
<dialog id="dlg" class="dialog-modal">
  Thanks for accepting these conditions.
</dialog>

Onunchecked actions

Onunchecked events are triggered when a radiobutton or checkbox is unchecked interactively.

Ifchecked actions

Ifchecked events are triggered when the page or part is loaded and the radiobutton or checkbox is checked, and when the radiobutton or checkbox is checked interactively.

In the following example, a "VAT Number" field is only visible if the checkbox is checked:

<label><input type="checkbox" ifchecked-show="#vatinfo"> Has a VAT number</label>
<div id="vatinfo" hidden>
  <input type="text" name="VAT" placeholder="VAT Number"/>
</div>

The #vatinfo element is initially hidden to avoid "flickering". Because ifchecked-* event-actions are also evaluated on initialization, you can leave the #vatinfo element hidden even if the checkbox is intially checked. The #vatinfo will in that case be unhidden on initialization.

Ifunchecked actions

Ifunchecked events are triggered when the page or part is loaded and the radiobutton or checkbox is unchecked, and when the radiobutton or checkbox is unchecked interactively.

In the following example, Express delivery requires Postal delivery to be checked:

<label><input id="pdel" type="checkbox" ifunchecked-uncheck="#xdel"/> Postal delivery</label><br/>
<label><input id="xdel" type="checkbox" ifchecked-check="#pdel"/> Express delivery</label>

A different way to implement this dependency is by disabling Express delivery when Postal delivery is not choosen:

<label><input type="checkbox" ifchecked-enable=".req-pd" ifunchecked-uncheck=".req-pd"/> Postal delivery</label><br/>
<label><input type="checkbox" class="req-pd"/> Express delivery</label>

Ifvalue actions

Ifvalue events are a special type of change events that may act depending on the value of the changed control.

Ifvalue events exist in 2 kinds which are typically used together to obtain a certain behavior:

• Ifvalue events that are triggered independent of the value of the event source element, and
• Ifvalue events that are triggered for a specific value of the event source element.

They are implemented as classes, where the classname contains the control name (and for the value specific kind also the expected control value). For instance, an Ifvalue event to show a "State" selection control when the control named "Country" has the value "US", would look like:

<select name="Country" class="ifvalue-events">
    <option value="CA">Canada</option>
    <option value="US">Unites States of America</option>
    <option value="..">...</option>
</select>
<br />
<select name="State" class="ifvalueCountry-hide ifvalueCountryisUS-show">
    <option value="AL">Alabama</option>
    <option value="AK">Alaska</option>
    <option value="AZ">Arizona</option>
    <option value="..">...</option>
</select>

The Country control has the class ifvalue-events. This class is required to support Ifvalue events. Without this class, the Country control would not raise Ifvalue events.

The State control has the class ifvalueCountry-hide. This is a value independent Ifvalue event: it is triggered on page initialize and on change of the Country control. As a net result, because it does not care about the value of the Country control, and because it is evaluated on initialization (when the page (part) is loaded), the State control would be hidden.

But the State control also has the class ifvalueCountryisUS-show. This is a value specific Ifvalue event (tiggered when the value is "US"). And value specific Ifvalue events are always evaluated after the value independent Ifvalue events. As a result, would the "US" option have been initially selected on page load, the State control would remain visible.

Whenever a change event occures on the Country control, given it has the ifvalue-events class, it will search and process value independent Ifvalue events found on other elements, that refer to its own control name. Doing so, it will encouter the ifvalueCountry-hide class on the State control and hide the State control. Then it will search for value specific Ifvalue events, and encounter the ifvalueCountryisUS-show class on the State control. If the Country control has the value "US", it will then make the State control visible.

Whenever a control that has the ifvalue-events class searches for Ifvalue events, it searches within a scope. By default, this scope is the current FORM the control is in. If the control is not in a form, then the BODY element is the scope. You can override the scope by using an ifvalue-scope attribute on the control having the ifvalue-events, with a CSS selector value pointing to the scope.

Following Ifvalue events are defined, where <Name> is to be substituted by the name of the input control to look for changes on, and <Value> is to be substituted by the value to look out for:

To test on an empty value, remove <Value>, replacing it by nothing. In this sample, the "Buy a ticket" option is always enabled (because of the ifvaluetransp-enable class), except when no transportation option has been choosen yet (because of the ifvaluetranspis-disable, which orders to disable the control when the transp control has value "" (empty string or nothing)).

<select name="transp" class="ifvalue-events">
    <option value="">(choose)</option>
    <option value="car">By Bus</option>
    <option value="train">By Train</option>
</select>
<br />
<input type="checkbox" class="ifvaluetransp-enable ifvaluetranspis-disable" /> Buy a ticket

Some server side frameworks generate form control names containing special characters. It is generally not a problem to address control names and values with special characters from within ifvalue action-event classes, as long as they do not contain a space character. For instance, if you have a control named "Item.Customers[12].Discount", and you want to check a checkbox if the discount has value "12.5%", then you should use the class ifvalueItem.Customers[12].Discountis12.5%-check.

Note that Ifvalue event senders should be controls with unique names. If controls sharing their name with other controls (as is usual for radiobuttons and is common for checkboxes) are used as sender of Ifvalue events, the effects of Ifvalue events may not match your expectations.

Ifvalid actions

Ifvalid events are triggered on form validation, if the form is valid.

Ifvalid event-actions can be applied on any validatable input element, or on a parent of a group of such elements, including on the FORM element.

Note that the ifvalid event-actions operate in 2 directions. For instance, the ifvalid-addclass attribute will add the given class if the element is valid, but will also remove the class if the element is invalid.

Combined with the ifinvalid-addclass event-action attribute, you can choose whether the class should be set when the element is valid, or when it is invalid.

Ifinvalid actions

Ifinvalid events are triggered on form validation, if the form is invalid.

Ifinvalid event-actions can be applied on any validatable input element, or on a parent of a group of such elements, including on the FORM element.

Note that the ifinvalid event-actions operate in 2 directions. For instance, the ifinvalid-addclass attribute will add the given class if the element is invalid, but will also remove the class if the element is valid.

Combined with the ifvalid-addclass event-action attribute, you can choose whether the class should be set when the element is valid, or when it is invalid.

In the following example, a message is shown when the textbox, which is required, does not contain a value:

<input type="text" name="name" required ifinvalid-show="#info" />
<div id="info">Please enter your name</div>

Onchange actions

Onchange events are triggered when form controls have their value changed. Text fields trigger a change event when the value is changed and the field looses its focus.

In the following example, because of the onchange-submit class, as soon as the user chooses a color, the form is submitted. And because the form also has a target class, it is the target of the request, and the content returned by the server will replace the current content of the form:

<form action="/SaveColor" class="onchange-submit target">
    <label><input type="radio" id="col" value="R">Red</label>
    <label><input type="radio" id="col" value="G">Green</label>
    <label><input type="radio" id="col" value="B">Blue</label>
</form>

Oninput actions

Oninput events are triggered by text inputs and textareas when input is recorded.

Onsubmit actions

Onsubmit events are triggered by the submission of a form.

Their action lasts for the duration of the form submit only, and is reverted after the form is submitted.

While submitting this form, all submit elements (matches of the ":submit" CSS pseudo-class) inside the form are disabled:

<form action="/Submit" class="onsubmit-disable">
    <button type="submit">Submit</button>
</form>

Pointer & Cursor related event-actions

Onfocus actions

Onfocus events are triggered when an element receives the focus.

When the following textbox receives the focus, all of its text will be selected:

<input type="text" value="Jane Doe" class="onfocus-select">

Onfocusout actions

Onfocusout events are triggered when an element looses the focus.

Onhover actions

Onhover events are triggered when the pointer moves over the element.

Note that the onhover event-actions operate in 2 directions. For instance, the onhover-addclass attribute will add the given class when the pointer moves over the element, and remove the given class when the pointer move out of the element.

While the :hover CSS pseudo-class allows styling the element on hover, the onhover-addclass also allows styling other elements on hovering the current element. Here, when hovering over the BUTTON element, the #storeinfo DIV element gets styled:

<style>
    .bright {
        color: red;
        font-weight: bold;
    }
</style>
<button type="button" onhover-addclass="bright on #storeinfo">Store</button>
<div id="storeinfo"> Stores the data.</div>

Load related event-actions

Beforeload actions

Beforeload events are triggered before initiating the loading of a page part.

In the following example, the hyperlink loads news in the .news DIV element. When the request is initiated, a "Getting news..." message is made visible:

<a href="/News" target="#news">Get news</a>
<div id="news">
    <div class="beforeload-show" hidden>Getting news...</div>
</div>

Onload actions

Onload events are triggered when a page part is loaded.

When the following example code is loaded, a second request is send to the server to retrieve latest news. The response is then inject in the DIV element, replacing it's current content:

<div onload-load="/LatestNews">
   Loading latest news...
</div>

View related event-actions

Ifinview actions

Ifinview events are triggered when the page or part is loaded and the element is in scope of the view (visible without need to scroll), and when the becomes visible (typically due to a scroll action).

When the following DIV element is or becomes visible to the user (i.e. by scrolling), a request to the server is issued to retrieve page 2 of the search results. The response will be injected in th DIV element, thereby replacing the "loading" message:

<div ifinview-load="/SearchResults?page=2">
    <p>Loading more results...</p>
</div>

Note that ifinview events are triggered only once: the first time the element appears in view.

Onscrolltop actions

Onscrolltop events are triggered by scrolling down the page or back up to the top of the page.

The following implements a button in the bottom-right corner of the view, visible only when not scrolled at top, that performs a scoll at top when clicked.
It uses Font Awesome icons.

<style>
    #back-top {
        display: block; position: fixed; bottom: 24px; right: 36px;
        font-size: 32px; color: #222; background-color: white;
        opacity: 0.4; z-index: 500;
    }
    #back-top:hover {
        opacity: 1;
    }
</style>
<div id="back-top" class="onclick-scrolltop onscrolltop-fade" hidden>
    <i class="fas fa-chevron-circle-up"></i>
</div>

Action-events

Check events

Check action-events check/uncheck the current element depending on the following events:

Check action-events can help implementing tree-like structures of checkboxes:

<ul>
  <li>
    <input type="checkbox" check-ifallchecked="<LI |> UL INPUT" ifchecked-check="<LI |> UL INPUT" /> America
    <ul>
      <li><input type="checkbox" /> Central and South-America</li>
      <li>
        <input type="checkbox" check-ifallchecked="<LI |> UL INPUT" ifchecked-check="<LI |> UL INPUT" /> North-America
        <ul>
          <li><input type="checkbox" /> Canada</li>
          <li><input type="checkbox" /> United States</li>
        </ul>
      </li>
    </ul>
  </li>
</ul>

This example uses relative CSS selectors to identify INPUT elements that are children of the current element.

Enable events

Enable action-events enable/disable the current element depending on the following events:

Enable action-events 

<input type="checkbox" class="line" /> Line 1 <br />
<input type="checkbox" class="line" /> Line 2 <br />
<input type="checkbox" class="line" /> Line 3 <br />
<button type="submit" enable-ifanychecked=".line" show-ifexists=".line">Delete selected lines</button>

Show events

Show action-events show/hide the current element depending on the following events:

In the above sample, the delete button is only visible if at least one line exists.

Chaining event-actions

Sircl provides a large set of event actions for common situations. Sircl is an extendible library that allows you to create your own additional event-actions.

Another way to deal with a missing event-action, is to chain existing event-actions.

Suppose you would want to move the focus to a (search) textbox when the / key is pressed. Therefore you would need an onkeydown-focus event-action. You can replace this event-action by chaining an onkeydown-click event-action to an onclick-focus event-action. When the / key is pressed (outside a form control), a click event is generated on the element having the onkeydown-click attribute. The click event is then captured by the onclick-focus event action, which sets the focus on the search box. For instance:

<input type="text" id="searchBox" />
<span onkeydown-click="/" onclick-focus="#searchBox"></span>

Chaining event-actions is generally done through the click action/event as most events can trigger a click action, and most actions can be triggered by a click event.

Order of evaluation

For some actions, the order of evaluation can be important. Take for instance the following enable and disable actions on the button:

<button type="button" onclick-enable="#opt1" onclick-disable=".opt">Only option 1</button>
<label><input type="checkbox" id="opt1" class="opt">Option 1</label>
<label><input type="checkbox" id="opt2" class="opt">Option 2</label>
<label><input type="checkbox" id="opt3" class="opt">Option 3</label>

The order in which the onclick-enable and onclick-disable attributes are written on the BUTTON element is not relevant for the evaluation order.

The order of evaluation of paired actions is fixed and is:

• ~-disable is always evaluated before ~-enable event-actions
• ~-readonly is always evaluated before ~-readwrite event-actions
• ~-uncheck is always evaluated before ~-check event-actions
• ~-hide is always evaluated before ~-show event-actions; ~-toggleshow is evaluated as last
• ~-removeclass is always evaluated before ~-addclass event-actions; ~-toggleclass is evaluated as last

In the above example, all three options will therefore first be disabled. Then the "opt1" option will be enabled, resulting in only this option to be enabled.

Add/remove/toggle class values

For different events, an addclass, removeclass or toggleclass action can be coupled by means of an event-action attribute where the value is the class or classes to add/remove/toggle.

In the following example, clicking the button changes its class from "inactive" to "active".

<button type="button" class="inactive" onclick-toggleclass="active inactive"> Toggle </button>

The action attribute value can also refer to another element where to apply the class action on, by using an "on" clause followed by a (relative) CSS selector. For instance:

<button type="button" onhover-addclass="emphasized on #actionhlp"> Action </button>
<span id="actionhlp">Pressing this button will...</span>

In this example, hovering over the button will add the class "emphasized" on the SPAN element. (Hovering out, will again remove the class.)

To apply a class action on several selectors, separate the selectors by commas. In the following example, the c1 class is applied on both elements e1 and e2:

<button type="button" onclick-addclass="c1 on #e1, #e2">...</button>

Finally, to apply separate classes on separate selectors, separate the "on" expressions by commas:

<button type="button" onclick-addclass="c0, c1 on #e1, #e2, c2 c3 on #e3">...</button>

In this example:

• class c0 is applied on the current element (the button),
• class c1 is applied on both elements e1 and e2,
• classes c2 and c3 are applied on element e3.

In all cases, where CSS selectors are expected, relative CSS selectors are supported.

Selector values

Unless stated otherwise, all attributes taking a selector as value support relative CSS selectors.