VERSION 2

Documentation

Intro

This is the documentation for Cloud Canal v2. The framework generally follows the attribute format of {event} = {action(s)}, with actions also able to contain parameters.

To begin, place this snippet in the head of your site:

‍

Miscellaneous

Various tags meant to act in conjunction with other attributes in the framework.

data-cc-id

Groups attributes together across elements.

data-cc-endpoint

Enables the framework to take control of a form and send requests to the specified URL.

data-cc-method

Specifies which HTTP method the endpoint should use. Defaults to POST.

data-cc-auth

Ensures that the auth token stored by the framework is sent along with the response in an Authorization: Bearer header.

data-cc-loader

Shorthand attribute for showing an element when an HTTP request begins and hiding it upon completion.

data-cc-disable-inputs

Disables all inputs on a form when that form is submitted, so that the user cannot change the fields until the request completes. Defaults to true.

data-cc-hidden-until-init

Hides the element until all of the data-cc-on-load events have fired.

data-cc-comment

No functionality. Used for leaving comments on an element, potentially explaining the attributes.

‍

Data Binding

Bind attributes of elements on the page to a central data store.

Page Binding

Bind data that does not persist beyond refreshing or navigating away from the page.

data-cc-bind-value

Bind the value of the element to a variable.

data-cc-bind-text

Bind the text of the element to a variable.

data-cc-bind-src

Bind the src of the element to a variable.

data-cc-bind-href

Bind the href of the element to a variable.

‍

Action Groups

Group lists of actions together. Often used with "If" actions.

data-cc-action-group-{name}

A list of actions on an element for code organization purposes. Can be triggered with the group::{name} action.

‍

Arrays

Used in conjunction with an array of data in order to create a repeating pattern of elements.

data-cc-array

Identifies the root of the array via dot notation. For example, {{widget.items}} would search the response body for a key of "widget", and then use the "items" key within it as the source array.

data-cc-array-element

Executes actions, except that the root of the response ({{res::...}}) is the array element itself. For example, to set a text field to the name of the array item, you would simply use text::{{res::name}}.

data-cc-array-has-results

Executes actions if the array is not empty. Useful for showing the container element.

data-cc-array-is-empty

Executes actions if the array is empty. Useful for showing a "no results" message.

‍

Events

Attributes that are triggered when something happens.

User Events

Events initiated due to user action.

data-cc-on-load

Fires when the page loads.

data-cc-on-click

Fires when the element is clicked.

data-cc-on-input

Fires when the input is updated. For example, this will fire on each keystroke when the user types in an input.

data-cc-on-change

Fires when the value of an input changes.

data-cc-on-mouseenter

Fires when the user hovers over the element.

data-cc-on-mouseleave

Fires when the user stops hovering over an element.

data-cc-on-focus

Fires when the element gains focus.

data-cc-on-blur

Fires when the element loses focus.

data-cc-on-submit

Fires when the form is submitted.

HTTP Events

Events initiated due to HTTP requests and their various stages/results.

data-cc-http-start

Fires when the request begins.

data-cc-http-success

Fires when the request completes and the response has a status code of 2XX.

data-cc-http-fail

Fires when the request completes and the response has a status code of 4XX or 5XX.

data-cc-http-always

Fires when the request completes.

data-cc-http-{status}

Fires when the request completes and the response has a status code of exactly {status}. For example, data-cc-http-401.

data-cc-http-default

Fires when the no other HTTP event was fired for the response on this element. For example, if an element has data-cc-http-success and data-cc-http-default attributes and the response comes back with a 401, then data-cc-http-default will fire since there are no data-cc-http-401 or data-cc-http-fail attributes on the element.

Auth Events

Events that fire on page load, based on the authentication status of the user.

data-cc-is-logged-in

Fires when the page loads and the user is logged in.

data-cc-is-logged-out

Fires when the page loads and the user is not authenticated.

Variable Events

Events that fire with respect to variables in the data store.

data-cc-on-update-{name}

Fires when the the value of the variable called {name} is changed.

‍

Actions

Snippets of functionality that are executed as a result of an event. These go inside the value of those attributes. Any question marks (?) denote an optional component of the action and are not to be used literally.

if({condition})::{group}?::{group}

If the condition is true, execute the first action group. Otherwise, execute the second (optional) action group. The condition takes the form of {argument}?::{operator}?::{argument}, where operator is one of:

[none] - the first argument is on its own, and evaluated as true/false
! - the second argument is omitted and the first is evaluated as its inverse.
=
!=
>
>=
<
<=

loop::{group}

Infinitely loop the actions in the action group. Useful for looping animations.

script::{URL}?::{Group}

Load a script on the page. Optionally execute an action group after it has loaded.

alert::{message}

Trigger an alert with the given message.

log::{message}

Log the given message to the console.

wait::{ms}

Wait {ms} milliseconds before proceeding.

timeout::{name}::{ms}::{group}

Set a timeout to call an action group. Only one timeout can exist with a given name, so calling this action again with the same name will cancel the previous timeout. One use case is adding a buffer towards search fields so they only send a single request when the user pauses typing instead of for every letter.

group?({selector})::{group}

Trigger the action group(s). If the selector is omitted, only the group on the current element will be triggered.

scroll?({selector})

Scroll the viewport to the current element, or the element with the given selector.

show?({selector})

Show the current element, or the element(s) with the given selector.

hide?({selector})

Hide the current element, or the element(s) with the given selector.

remove?({selector})

Remove the current element, or the element(s) with the given selector.

reset?({selector})

Reset the current form, or the form(s) with the given selector.

focus?({selector})

Focus the current element, or the element with the given selector.

click?({selector})

Trigger a click on the current element, or the element(s) with the given selector. Because of the way jQuery works, this will not trigger native functionality on an <a> tag. To do that, use {{fcn::element.click()}}.

trigger?({selector})::{event}

Trigger a {event} event the current element, or the element(s) with the given selector.

disable?({selector})

Disable the current element, or the element(s) with the given selector.

enable?({selector})

Enable the current element, or the element(s) with the given selector.

value?({selector})::{value}

Set the value of the current element, or the element(s) with the given selector.

text?({selector})::{text}

Set the text of the current element, or the element(s) with the given selector.

src?({selector})::{URL}

Set the src of the current element, or the element(s) with the given selector.

href?({selector})::{URL}

Set the href of the current element, or the element(s) with the given selector.

style?({selector})::{name}::{value}

Set the {name} style on the current element, or the element(s) with the given selector.

attribute-set?({selector})::{name}?::{value}

Set the {name} attribute of the current element, or the element(s) with the given selector.

attribute-remove?({selector})::{name}

Remove the {name} attribute of the current element, or the element(s) with the given selector.

data-set?({selector})::{name}?::{value}

Set the {name} data of the current element, or the element(s) with the given selector.

data-remove?({selector})::{name}

Remove the {name} data of the current element, or the element(s) with the given selector.

class-add?({selector})::{name}

Add the {name} class to the current element, or the element(s) with the given selector.

class-remove?({selector})::{name}

Remove the {name} class from the current element, or the element(s) with the given selector.

field-invalid?({selector})::{message}

Mark the current element as invalid with the given {message}, or the element(s) with the given selector.

field-valid?({selector})

Mark the current element as valid, or the element(s) with the given selector.

clipboard-copy::{value}

Copy {value} to the user's clipboard.

endpoint::{URL}

Call the endpoint. Can work in conjunction with the corresponding miscellaneous attributes, just as a form would.

submit::{id}

Submit all forms with the given data-cc-id={id}.

navigate::{URL}

Navigate to {URL}.

redirect::{URL}

Redirect to {URL}, removing the current page from the user's state history.

reload

Refresh the current page.

page-title::{title}

Set the page title to {title}.

array-add::{id}?::{path}

Add an element to the array with data-cc-id={id}. If {path} is empty, a blank element is added.

array-remove::{id} | true

Remove the last element in the array with data-cc-id={id}, as in a "-" button. If set to true instead, removes the current array element. Useful for a nested delete button.

cookie-set::{key}::{value}

Sets a cookie with a session expiry.

cookie-clear::{key}

Deletes a cookie with {key}.

var-set::{key}::{value}

Sets a variable in the data store.

var-clear::{key}

Remove a variable from the data store.

storage-set::{key}::{value}

Sets an item in localStorage.

storage-clear::{key}

Removes an item from localStorage.

session-set::{key}::{value}

Sets an item in sessionStorage.

session-clear::{key}

Removes an item from sessionStorage.

auth-set::{value}

Sets a cookie called cc-auth-token, used in other attributes like when determining whether the user is logged in.

auth-clear

Removes the cc-auth-token cookie.

options::{path}::{text}::{value}

Creates the options for a <select> dropdown based on a response from an HTTP request. Cannot be used in conjunction with other actions.

‍

Parameters

These values can be used inside actions to insert data dynamically.

{{attr?({selector})::{name}}}

Get the value of the {name} attribute of the current element, or the element with the given selector.

{{cookie::{key}}}

Get the value of the {key} cookie.

{{var::{key}}}

Get the value of the {key} variable from the data store.

{{storage::{key}}}

Get the value of the {key} item from localStorage.

{{session::{key}}}

Get the value of the {key} item from sessionStorage.

{{query::{key}}}

Get the value of the {key} query parameter from the URL.

{{path::{index}}}

Get the value of the path parameter from the URL at {index}.

{{fcn::{code}}}

Execute the given JavaScript code. If the code returns anything, this parameter will be replaced with the value.

Get the value of the cc-auth-token cookie.

{{random::{min}::{max}::{round}}}

Generate a random number between {min} and {max}, rounded to {round} decimal places.

{{res::{path}}}

Get the response at the path (only applicable to HTTP events that fire after the request has completed).

‍

API

    window.cloudCanal = window.cloudCanal || {};
    window.cloudCanal.callbacks = window.cloudCanal.callbacks || [];
    window.cloudCanal.callbacks.push(['cc-init', function() {
      
      // Add custom function via Cloud Canal API
      window.cloudCanal.functions.setCustomFunction('NAME', function(...) {...});
      
      // Add custom variables via Cloud Canal API
      window.cloudCanal.functions.setVariable('NAME', VALUE);

      // Add custom attributes via Cloud Canal API
      // The passed function takes 'value' as a parameter, which is the value of the new attribute
      // The passed function must return an object of attribute name/value pairs { attr1: val1, attr2: val2, ... }
      window.cloudCanal.functions.addCustomAttribute('NAME', function(value) {...});
    
      // Add custom actions via Cloud Canal API
      // The passed function takes a 'slot' and list of arguments. Slot is mandatory, even if it isn't used in the function.
      window.cloudCanal.functions.addCustomAction('NAME', function(slot, ...args) {...});
    
    	// Trigger an action via API by passing a string
    	window.cloudCanal.functions.executeAction('ACTION(S)', ELEMENT);
    }]);