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:
<script src="https://cdn.jsdelivr.net/npm/@cloud-canal/cloud-canal@2/dist/cloud-canal.min.js" defer></script><style>[data-cc-hidden-until-init]{visibility:hidden;}</style>
Miscellaneous
Various tags meant to act in conjunction with other attributes in the framework.
data-cc-id
value: {id}
Groups attributes together across elements.
data-cc-endpoint
value: {URL}
Enables the framework to take control of a form and send requests to the specified URL.
data-cc-method
value: GET | POST | PUT | DELETE | etc.
Specifies which HTTP method the endpoint should use. Defaults to POST.
data-cc-auth
value: true
Ensures that the auth token stored by the framework is sent along with the response in an Authorization: Bearer header.
data-cc-loader
value: true
Shorthand attribute for showing an element when an HTTP request begins and hiding it upon completion.
data-cc-disable-inputs
value: true | false
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
value: true
Hides the element until all of the data-cc-on-load events have fired.
data-cc-comment
value: {text}
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
value: {variable}
Bind the value of the element to a variable.
data-cc-bind-text
value: {variable}
Bind the text of the element to a variable.
data-cc-bind-src
value: {variable}
Bind the src of the element to a variable.
data-cc-bind-href
value: {variable}
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}
value: {action(s)}
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
value: {path}
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
value: {action(s)}
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
value: {action(s)}
Executes actions if the array is not empty. Useful for showing the container element.
data-cc-array-is-empty
value: {action(s)}
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
value: {action(s)}
Fires when the page loads.
data-cc-on-click
value: {action(s)}
Fires when the element is clicked.
data-cc-on-input
value: {action(s)}
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
value: {action(s)}
Fires when the value of an input changes.
data-cc-on-mouseenter
value: {action(s)}
Fires when the user hovers over the element.
data-cc-on-mouseleave
value: {action(s)}
Fires when the user stops hovering over an element.
data-cc-on-focus
value: {action(s)}
Fires when the element gains focus.
data-cc-on-blur
value: {action(s)}
Fires when the element loses focus.
data-cc-on-submit
value: {action(s)}
Fires when the form is submitted.
HTTP Events
Events initiated due to HTTP requests and their various stages/results.
data-cc-http-start
value: {action(s)}
Fires when the request begins.
data-cc-http-success
value: {action(s)}
Fires when the request completes and the response has a status code of 2XX.
data-cc-http-fail
value: {action(s)}
Fires when the request completes and the response has a status code of 4XX or 5XX.
data-cc-http-always
value: {action(s)}
Fires when the request completes.
data-cc-http-{status}
value: {action(s)}
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
value: {action(s)}
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
value: {action(s)}
Fires when the page loads and the user is logged in.
data-cc-is-logged-out
value: {action(s)}
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}
value: {action(s)}
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::{group}
Trigger the action group.
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.
{{auth::token}}
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).