Secutio Documentation
Table of Contents:
Example Usage
If using Node.js or another CommonJS environment
const Secutio = require('./secutio');
const app = new Secutio();
app.init();
If in a browser environment
<script
type="text/javascript"
src="https://cdn.jsdelivr.net/gh/mrhdias/secutio@master/dist/js/secutio.min.js">
</script>
<script>
const app = new Secutio();
app.init();
</script>
Project Directory Structure
The following directory structure is just a suggestion and can be adjusted to the needs of each project.
├── app/
│ ├── public/
│ │ ├── css/
│ │ │ ├── styles.css
│ │ ├── js/
│ │ │ ├── script.js
│ │ ├── templates/
│ │ │ ├── tpl-example.html
│ │ ├── tasks.json
└── server.bin
Tasks
Tasks are a set of properties that can be applied to each HTML element by adding the “data-tasks” attribute. Properties are specified in a JSON file with a “.json” extension. The JSON file is loaded from the path specified in “src” of “script” HTML element with the “data-tasktable” attribute and the “type” attribute must be set to “application/json”. More than one task can be defined per element as long as they correspond to different events (click, mouseover, submit, etc).
Example of a tasks file.
{
"get-contacts-list": {
"action": "/listcontacts",
"method": "get",
"trigger": "click"
},
"switch-contact-status": {
"action": "/statuscontact",
"method": "put",
"callback": "prepare-data",
"trigger": "click"
}
}
Properties
The following properties can be used in the “data-tasks” attribute:
- action: The action that is executed on the server when the event is triggered;
- method: Set a request method (GET, POST, PUT, PATCH or DELETE) to indicate the desired action to be performed for a given resource;
- trigger: Specifies the event that triggers the request;
- callback: Callback function;
- then: List of subtasks with the CSS “selector” property to be executed after the trigger has been performed (useful for displaying loaders);
- next: Performs a new task within the context of the original event where the property was declared;
- src-data: Used to load JSON data directly from a file to apply to templates. If the name starts with the character “#”, it indicates that the source of data is embedded in an HTML page within a script element with an id attribute matching the given name and a content type of “application/json”. It only works if the action and method are not specified. This approach is ideal for creating dynamic content on static websites;
- disabled: This property disable the task execution if set to “true”;
- error: Sets a new task that replaces the original if an error occurs during the request;
- wait: The time, in milliseconds that the timer should wait before the specified task is executed (currently available only for the “next” property).
The following properties can be used both client-side and server-side via custom HTTP header:
- target: Uses the first document element that matches the specified CSS selector as the final destination for data association with the template. The string “this” indicates that the target of the replacement is the element that triggered the action;
- template: This property enables you to choose the template for use to associate the data. If the value starts with the character “#”, it indicates that the template is embedded in the destination page and corresponds to the “id” of the element to be utilized. Otherwise, the specified value will be utilized as the path to load the template from the server side;
- before: List of subtasks with the CSS “selector” property to be executed before swapping the new content at the target;
- after: List of subtasks with the CSS “selector” property to be executed after swapping the new content in the target;
- swap: This property controls how content is swapped into the target element. The following “swaps” are available:
- inner: Replaces the target with a specified new set of children (default);
- outer: Replaces the target in the children list of its parent with a set of node or string objects;
- before: Inserts a set of node or string objects in the children list of target’s parent, just before the target;
- after: Inserts a set of node or string objects in the children list of the target’s parent, just after the target;
- prepend: Inserts a set of node objects or string objects before the first child of the target element;
- append: Inserts a set of node objects or string objects after the target element;
- delete: Removes the target element from the DOM;
- clean: Remove all child nodes from target element;
- none: It exists only for convenience, but does not make any transformations.
Custom Attributes
Custom attributes can be added to the elements where “tasks” are specified, allowing one to override the default value of one property with another. The property in the “tasks” file that defines the attribute must always begin with the substring ‘attribute-‘ followed by the attribute with property to replace. This transformation is available for the following properties: action, src-data, method, remove, target, swap, before, after, and trigger.
Example:
tasks.json
{
"load-paradises": {
"action": "/listparadises",
"attribute-action": "data-action",
"method": "get",
"trigger": "click",
"target": "#paradises",
"swap": "inner"
}
}
The attribute-action replaces the “action” property with the specified attribute, which should be present on the element with the “data-tasks” attribute.
This property overrides the default and allows actions to be unique.
Example
<div id="paradises"></div>
<button data-tasks="load-paradises">List All</button>
<button data-tasks="load-paradises" data-action="/listparadises/earth">Go To Earth</button>
Custom HTTP header (Secutio-Transformation) containing information about the transformation to be applied and overrides the same default properties if indicated in the tasks file.
An example is provided below.
HTTP/1.1 200 OK
Secutio-Transformation: target:#contacts-list;template:#contacts-list-tpl;swap:innerHTML
Content-Type: application/json
Subtasks
These special tasks are executed before or after the task with the event that triggered the action and must have the “selector” property.
Example of a subtask:
tasks.json
{
"active-paradise": {
"selector": ".paradises > .earth",
"add": {
"class": "active",
"style": "color: #0d6efd;"
}
}
}
Properties
Description of each of the properties allowed in the subtasks:
- traverse: The traversal starts at the specified element and moves up through its parents (toward the document root) until it locates a node that matches the specified CSS selector if “closest” is selected; otherwise, if “target” is used, it is limited to the owner element. If the “traverse” property is not used, the traversal begins from the document.
- selector: Returns a list of elements that match the specified group of selectors. The “remove” and “add” properties are applied to this list of elements;
- remove: Uses the list of document elements that match the specified CSS “selector” to remove attributes or properties of them before/after inserting the content into the target. If the property is empty “{}”, remove the element itself. If the “remove” and “add” property is present in the subtask, the first one to be executed is “remove”.
- attributes: List (array) of attributes to remove on each selected element;
- class: String with class names separated by space;
- style: String with property names separated by space
- add: Uses the list of document elements that match the specified CSS “selector” to add attributes or modify them before/after inserting the content into the target.
- attributes: Object with attributes in the form (attribute/value);
- class: String with class names separated by space;
- style: String in the form “property; value; property n; value;…”
- toggle: Toggle between adding and removing an attribute value or a class name from an element’s attribute.
- attribute: Object with attributes in the form (attribute/value);;
- class: String with class names separated by space.
- scroll-into: Property utilized in conjunction with the ‘selector’ and/or ‘transverse’ properties to smoothly scroll the page to the element identified by the specified identifier. It allows for the configuration of an object with properties akin to those found in the JavaScript scrollIntoView method.
In the “class” and “style” properties, which are already attributes, the value is a string and in the attributes it is a list in “remove” and an “object” in “add”.
Templates
These templates can be used to generate HTML content on the client side and can be embedded into the HTML page or loaded. This has nothing to do with the templating engines used on the server side to render pages before sending them to the client.
There is a special variable that can be used in templates:
- data: The data variable contains information obtained from an HTTP response or a JSON file when the “src-data” task property is provided.
Embedded
Embedded templates should have a unique id property, and their content must be enclosed within the HTML tag “script” with type=”text/template”.
<script id="contacts-list-tpl" type="text/template">
<!-- HTML Content -->
</script>
Loaded
These templates function just like normal HTML files and reside within the public directory. To load a template, tasks utilize the “template” property. The value assigned to this property should be the path to the HTML file containing the template.
templates/example.html
Template Literals
Template literals, formerly known as template strings. Template literals are enclosed with backtick ( `) characters, enabling multi-line strings, string interpolation with embedded expressions, and special constructs known as tagged templates.
let name = 'John Doe';
console.log(`Hello ${name}!`);
// returns Hello John Doe!
Template literals provide a concise and expressive way to create reusable components with HTML templates, simplifying variable insertion, supporting multiline strings, enabling expression evaluation, and enhancing overall code readability.
Todo List