Forem: Henrique Dias

Axum/Tera & Real Shortcodes in Rust: A WordPress-Like Implementation

Henrique Dias — Mon, 02 Sep 2024 18:16:02 +0000

Introduction

Websites, blogs, and e-commerce platforms need to be dynamic, offering tools and components that enable rapid content creation with minimal effort. WordPress excels in this area by providing various tools, including plugins and shortcodes, which allow users to create dynamic content using these components.

However, the Rust ecosystem and the web platforms built with Rust generally lack tools for dynamic content creation without recompiling the entire application. The goal of this article is to bring the functionality of WordPress shortcodes to Rust, enabling them to be inserted into templates to display content or functionality provided by the shortcode.

Shortcodes

A WordPress shortcode is a simple code enclosed in square brackets, like "[shortcode]", that allows users to easily insert dynamic content into posts, pages, or widgets. Shortcodes can perform various functions, such as displaying galleries, embedding videos, or pulling in data from plugins like WooCommerce. They help users add complex features without needing to write or understand code, making content management more flexible and user-friendly.

For example, the shortcode below, taken from the Wordpress API page, shows a shortcode with a name ("myshortcode") and two attributes ("foo" and "bar"):



[myshortcode foo="bar" bar="bing"]

While it's possible to spend time implementing something similar in Rust by creating a template engine from scratch, we can achieve similar functionality by using an existing tool like Tera and building a custom function. Here's an example:



{{ shortcode(display="myshortcode", foo="bar", bar="bing") | safe }}

Example

Let's create a small prototype in Rust to demonstrate the concept using Tera and Axum.



cargo new app --bin
cd app
cargo add tokio -F rt-multi-thread
cargo add axum
cargo add tera -F builtins
mkdir templates

The structure of our project:



├── app/
    ├── plugins/
    ├── src/
    └── templates/

Inside the templates folder, we'll now create a template to include our shortcode.

templates/test_shortcode.html



<!DOCTYPE html>
<html lang="en">
<head>
<title>Shortcode Test</title>
</head>
<body>
{{ shortcode(display="myshortcode", foo="bar", bar="bing") | safe }}
</body>
</html>

The following code demonstrates the implementation of our shortcode in an Axum web server. When run, it displays the shortcode's output.

src/main.rs



use axum::{
    extract::{Extension, Request},
    response::Html,
    routing::get,
    Router,
    ServiceExt,
};

use tera::{Tera, Context, Result, Function};
use std::collections::HashMap;

struct Shortcodes;

impl Function for Shortcodes {
    fn call(&self,
        args: &HashMap<String, tera::Value>,
    ) -> Result<tera::Value> {
        // Extract attributes
        let display = args.get("display").unwrap().as_str().unwrap();
        let fragment = match display {
            "myshortcode" => {
                let foo = match args.get("foo") {
                    Some(value) => value
                        .as_str()
                        .unwrap()
                        .trim_matches(|c| c == '"' || c == '\''),
                    None => "no foo",
                };
                let bar = match args.get("bar") {
                    Some(value) => value
                        .as_str()
                        .unwrap()
                        .trim_matches(|c| c == '"' || c == '\''),
                    None => "no bar",
                };
                format!("bar: {} foo: {}", foo, bar)
            },
            _ => panic!("Unknown shortcode display name: {:?}", display),
        };
        Ok(tera::Value::String(fragment))
    }
}

async fn test(
    Extension(tera): Extension<Tera>,
) -> Html<String> {

    let context = Context::new();
    // Render the template with the context
    let rendered = tera
        .render("test_shortcode.html", &context)
        .unwrap();

    Html(rendered)
}

#[tokio::main]
async fn main() {
    let mut tera = Tera::new("templates/**/*").unwrap();

    // Register the custom function
    tera.register_function("shortcode", Shortcodes);

    // Build our application with a route
    let app = Router::new()
        .route("/", get(|| async {
            "Hello world!"
        }))
        .route("/test", get(test))
        .layer(Extension(tera));

    // Run the server
    let listener = tokio::net::TcpListener::bind("0.0.0.0:8080")
        .await
        .unwrap();
    axum::serve(listener, ServiceExt::<Request>::into_make_service(app))
        .await
        .unwrap();
}

Now, let's run the axum web server from the terminal and view the result.



cargo run

In a separate terminal, we'll use the curl command to test the shortcode, as demonstrated below.



curl http://127.0.0.1:8080/test

The output:



<!DOCTYPE html>
<html lang="en">
<head>
<title>Shortcode Test</title>
</head>
<body>

bar: bar foo: bing

</body>
</html>

The example above demonstrates how to use a Tera function to simulate a shortcode in Axum. However, in most cases, shortcodes are used to display data from a database, similar to how WooCommerce shortcodes display products based on the shortcode's attributes.

A challenge arises when using the template engines available in Rust. Many of these engines, often based on Jinja, only support custom functions that work synchronously. This creates a conflict with Axum, which operates on an asynchronous, Tokio-based runtime.

Fortunately, there is a way to work around this issue. While it may not be a perfect solution, it's the best approach I've found so far, and I’ll explain it below.

The solution is to create a route in Axum that handles asynchronous communication with the database. We can pass the database pool to Axum as an extension within a layer, allowing it to process inputs asynchronously.

This route receives inputs from the Tera custom function, processes the request to retrieve the data, and then collects the results.

To handle asynchronous code in this context, we use the "tokio::task::block_in_place" function to run the asynchronous operation within a blocking context.

Note:
I tried using "reqwest::blocking::Client::new()" without async in "fetch_data" function and without "block_in_place" in the "call" function, but I received the following error message:

thread 'tokio-runtime-worker' panicked at /../../.cargo/registry/src/index.crates.io-6f17d22bba15001f/tokio-1.39.3/src/runtime/blocking/shutdown.rs:51:21:
Cannot drop a runtime in a context where blocking is not allowed. This happens when a runtime is dropped from within an asynchronous context.

src/main.rs



use axum::{
    extract::{Extension, Request, Json},
    response::Html,
    routing::{get, post},
    Router,
    ServiceExt,
};

use serde::{Serialize, Deserialize};
use tera::{Tera, Context, Result, Function};
use std::collections::HashMap;

#[derive(Serialize, Deserialize)]
struct DataTest {
    foo: String,
    bar: String,
}

const ADDRESS: &str = "127.0.0.1:8080";

struct Shortcodes;

impl Shortcodes {

    async fn fetch_data(&self, data: &DataTest) -> String {

        let url = format!("http://{}/data", ADDRESS);

        // Convert the struct to json compact string
        let json_body = serde_json::to_string(data).unwrap();

        let client = reqwest::Client::new();
        let response = client.post(url)
            .header("Content-Type", "application/json")
            .body(json_body)
            .send()
            .await
            .unwrap();

        // Check the response status
        if response.status().is_success() {
            response.text().await.unwrap()
        } else {
            format!("Request failed with status: {}", response.status())
        }
    }
}

impl Function for Shortcodes {

    fn call(&self,
        args: &HashMap<String, tera::Value>,
    ) -> Result<tera::Value> {
        // Extract attributes

        let display = args.get("display").unwrap().as_str().unwrap();
        let fragment = match display {
            "myshortcode" => {
                let foo = match args.get("foo") {
                    Some(value) => value
                        .as_str()
                        .unwrap()
                        .trim_matches(|c| c == '"' || c == '\''),
                    None => "no foo",
                };
                let bar = match args.get("bar") {
                    Some(value) => value
                        .as_str()
                        .unwrap()
                        .trim_matches(|c| c == '"' || c == '\''),
                    None => "no bar",
                };

                // Use `block_in_place` to run the async function
                // within the blocking context
                let result = tokio::task::block_in_place(|| {
                    // We need to access the current runtime to
                    // run the async function
                    tokio::runtime::Handle::current()
                        .block_on(self.fetch_data(&DataTest {
                            foo: foo.to_string(),
                            bar: bar.to_string(),
                        }))
                });
                result
            },
            _ => panic!("Unknown shortcode display name: {:?}", display),
        };
        Ok(tera::Value::String(fragment))
    }
}

// Handler function that returns JSON content
async fn data(
    Json(payload): Json<DataTest>,
) -> Json<DataTest> {

    let data = DataTest {
        foo: format!("ok {}", payload.foo),
        bar: format!("ok {}", payload.bar),
    };

    // Return the JSON response
    Json(data)
}

async fn test(
    Extension(tera): Extension<Tera>,
) -> Html<String> {

    let context = Context::new();
    // Render the template with the context
    let rendered = tera
        .render("test_shortcode.html", &context)
        .unwrap();

    Html(rendered)
}

#[tokio::main]
async fn main() {
    let mut tera = Tera::new("templates/**/*").unwrap();

    // Register the custom function
    tera.register_function("shortcode", Shortcodes);

    // Build our application with a route
    let app = Router::new()
        .route("/", get(|| async {
            "Hello world!"
        }))
        .route("/test", get(test))
        .route("/data", post(data))
        .layer(Extension(tera));

    // Run the server
    let listener = tokio::net::TcpListener::bind(ADDRESS)
        .await
        .unwrap();
    axum::serve(listener, ServiceExt::<Request>::into_make_service(app))
        .await
        .unwrap();
}

Cargo.toml



[package]
name = "app"
version = "0.1.0"
edition = "2021"

[dependencies]
axum = "0.7.5"
reqwest = { version = "0.12.7", features = ["json"] }
serde = { version = "1.0.209", features = ["derive"] }
serde_json = "1.0.127"
tera = { version = "1.20.0", features = ["builtins"] }
tokio = { version = "1.39.3", features = ["rt-multi-thread", "bytes"] }

To run the application and view the result:



cargo run

Open another terminal and use the curl command to view the result.



curl http://127.0.0.1:8080/test

The output:



<!DOCTYPE html>

<html lang="en">

<head>

<title>Shortcode Test</title>

</head>

<body>

{"foo":"ok bar","bar":"ok bing"}

</body>

</html>

Conclusion

The advantage of shortcodes is that they can be placed anywhere in templates where their content needs to be displayed, without requiring the application to be recompiled. Additionally, they can be customized through attributes.

For instance, on a platform built with Axum and Tera, we could create a shortcode library with various functionalities and an API, enabling others to extend it with additional features.

Thank you for reading!

Building a Dynamic Client-Side Blog with Secutio & Bootstrap

Henrique Dias — Wed, 10 Apr 2024 21:57:40 +0000

Traditionally, creating a blog involved server-side scripting languages like PHP. But what if you could achieve the same functionality with JavaScript and the power of client-side rendering?

This is where the Secutio framework steps in. Secutio empowers you to build dynamic content on the client-side, allowing you to create a full-fledged blog experience using JavaScript literal templates.

Imagine this: you can develop a web application that feels and functions like a traditional website, complete with individual post URLs that are SEO-friendly. This means search engines can easily discover and index your blog content, boosting your online visibility.

Get a Sneak Peek! Want to see the final project before diving into the details?

$ git clone https://github.com/mrhdias/secutio
$ cd secutio/examples/blog
$ python3 -m http.server -d public
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

The Secutio project is relatively new, which presents a challenge in capturing developers' attention and gaining traction, given the multitude of frameworks that share the same goal of providing developers with tools to create websites quickly and easily. Despite this competitive scenario, I believe in the alignment of our project with these objectives, which is what propels us forward.

Leveraging Bootstrap for Enhanced User Experience

To effectively demonstrate Secutio's capabilities for rapid web development, we've chosen the popular Bootstrap framework as a foundation. Bootstrap provides a robust and user-friendly interface, making it an ideal choice for building the project's base.

We'll be building upon the concept of the Bootstrap Blog, but with a key innovation: each blog post will be displayed within a modal window when accessed from the main page. Additionally, each post will have a dedicated URL, ensuring optimal search engine visibility for improved discoverability.

Streamlining Website Development with Templates

Developing a dynamic website often involves the repetition of content, a challenge that can be effectively addressed by converting it into reusable templates or web components, enhancing modularity and efficiency.

The process begins with a thorough analysis of the website's structure to identify recurring sections, such as navigation menus, recent posts, or archive listings. Each identified section is then extracted and transformed into a template or component. These templates operate akin to WordPress widgets, facilitating seamless content management and modification.

In this particular case, the process resulted in the creation of twelve distinct templates, each tailored to specific functionalities. These templates were seamlessly integrated into the website's directory, enhancing its overall flexibility and ease of management.

blog

├── blog/
│   ├── public/
│   │   ├── templates/
│   │   │   ├── top-bar.html
│   │   │   ├── nav-bar.html
│   │   │   ├── featured-post.html
│   │   │   ├── featured-posts.html
│   │   │   ├── panel-posts.html
│   │   │   ├── list-posts.html
│   │   │   ├── panel-archives.html
│   │   │   ├── panel-elsewhere.html
│   │   │   ├── footer.html
│   │   │   ├── btn-scroll-to-top.html
│   │   │   ├── modal-post.html
│   │   │   ├── nav-modal.html
│   │   ├── assets/
│   │   │   ├── css/
│   │   │   │   ├── styles.css
│   │   ├── index.html
│   │   ├── post.html
│   │   ├── tasks.json
│   │   ├── tasks-post.json
└── server.py

In the case of a SPA (Single Page Application), it would only be necessary to use an HTML page as the base of the project. However, it's important to consider that many SPA-based projects require alternative means of accessibility for robots to index the content for SEO purposes. Therefore, we will include an additional page called "post.html", which is designed to display the content of the post when accessed via URL.

Associate the Events of HTML Elements with Tasks

The working principle of the Secutio framework involves associating tasks with elements to generate dynamic content.

Define the Tasks

After cutting each piece from the 'index.html' page and placing them into templates, the next step is to assign tasks to each HTML element where content will be displayed. These tasks are then linked or associated with the corresponding template.

The HTML code provided below corresponds to the Blog home page of the Bootstrap example. In this project, a link to the JSON file containing tasks (<script data-tasktable type="application/json" src="tasks.json"></script>) has been added. Additionally, the address of the Secutio library has been included at the end of the HTML body element.

public/index.html

<!doctype html>
<html lang="en" data-bs-theme="auto">
<head>
    <!-- missing content -->
    <link rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/@docsearch/css@3">
    <link rel="stylesheet"
        href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/css/bootstrap.min.css"
        crossorigin="anonymous">
    <!-- Custom styles for this example -->
    <link rel="stylesheet"
        href="https://fonts.googleapis.com/css?family=Playfair&#43;Display:700,900&amp;display=swap">
    <link rel="stylesheet"
        href="assets/css/styles.css" rel="stylesheet">
    <script data-tasktable type="application/json" src="tasks.json"></script>
</head>
<body>
    <!-- missing content -->
    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.3/dist/js/bootstrap.bundle.min.js"
        crossorigin="anonymous"></script>
    <script type="text/javascript"
        src="https://cdn.jsdelivr.net/gh/mrhdias/secutio@master/dist/js/secutio.min.js"></script>
</body>
</html>

After the "body" HTML element, we will include the page header, which consists of a top bar and a menu featuring various categories.

public/index.html

<!-- missing content -->
<!-- header with topbar and menu with categories -->
<div class="container">
    <header id="top-bar"
        data-tasks="add-topbar"
        class="border-bottom lh-1 py-3"></header>

    <div class="py-1 mb-3 border-bottom">
        <nav class="navbar navbar-expand-lg">
            <div class="container-fluid">
                <button class="navbar-toggler"
                    type="button"
                    data-bs-toggle="collapse"
                    data-bs-target="#large-nav-bar"
                    aria-controls="large-nav-bar"
                    aria-expanded="false"
                    aria-label="Toggle navigation">
                    <span class="navbar-toggler-icon"></span>
                </button>
                <div id="large-nav-bar"
                    data-tasks="add-navbar"
                    class="collapse navbar-collapse justify-content-center">
                </div>
            </div>
        </nav>
    </div>
</div>
<!-- missing content -->

The HTML header element and the element with the identifier "#large-nav-bar" both have an attribute called "data-tasks". This attribute contains the name of the task to be executed when a specified event occurs, as defined within the "tasks.json" file. In this particular case, the event responsible for triggering the task execution is named "init". It is automatically initiated upon loading of the HTML page and does not require any user interaction.

public/tasks.json

{
    "add-topbar": {
        "trigger": "init",
        "template": "templates/top-bar.html",
        "target": "#top-bar",
        "swap": "inner"
    },
    "add-navbar": {
        "trigger": "init",
        "src-data": "data/navbar.json",
        "template": "templates/nav-bar.html",
        "target": "#large-nav-bar",
        "swap": "inner"
    }
}

All properties are documented in the Secutio documentation. As mentioned above, only tasks with the "init" event load automatically on page load. However, the "next" property allows loading additional content within the same event, as exemplified by the following code snippet where the scroll-to-top button is loaded.

public/tasks.json

{
    "add-footer": {
        "trigger": "init",
        "template": "templates/footer.html",
        "target": "footer",
        "swap": "inner",
        "before": "add-footer-classes",
        "next": "add-btn-scroll-to-top"
    },
    "add-footer-classes": {
        "selector": "footer",
        "add": {
            "class": "py-5 text-center text-body-secondary bg-body-tertiary"
        }
    },
    "add-btn-scroll-to-top": {
        "template": "templates/btn-scroll-to-top.html",
        "target": "footer",
        "swap": "after"
    }
}

The "next" property within tasks allows chaining multiple tasks to execute in a specified order. Similarly, the "data-tasks" attribute can hold a space-separated list of tasks, enabling the execution of multiple tasks for an element, as long as these tasks are not intended for the same event as the element itself.

Three additional properties, "then", "before", and "after", allow you to add or remove classes and styles during event handling. The "then" property executes immediately after the event fires, making it perfect for initiating a spinner to indicate progress. The "before" property executes before updating ("swap") the content in the target element, while the "after" property executes after the update is complete.

The provided tasks snippet demonstrates the use of the "src-data" property. This property specifies the static data source, which can be a JSON or text file. When declared within a task, the data from this source is inherited by subsequent tasks triggered by some events. This inheritance continues unless a new "src-data" property is explicitly defined for a specific task or override by the attribute "attribute-src-data".

Data Sources

This blog project leverages static data, meaning the content needs to be prepared and stored in JSON files beforehand. While manual creation is an option, it's not recommended. A more efficient approach is to utilize a script that fetches the relevant data for each post directly from a database or backend.

In this project, we've opted for the scripted approach. The data for each post is stored in separate JSON files located within the "data/raw" directory, as shown in the following illustration:

public/data/raw

├── blog/
│   ├── bin/
│   │   │── metamorph.py
│   ├── public/
│   │   ├── data/
│   │   │   ├── raw/
│   │   │   │   ├── 1.json
│   │   │   │   ├── 2.json
│   │   │   │   ├── 3.json
│   │   ├── templates/
│   │   ├── assets/
│   │   ├── index.html
│   │   ├── post.html
│   │   ├── tasks.json
│   │   ├── tasks-post.json
└── server.py

For example, we can create the following file with relevant information to populate the blog, either from a backend via REST API or even from the WordPress REST API. This approach can also be used to generate static multilingual content by adding additional directories with languages to the "data/raw" directory.

public/data/raw/1.json

{
    "id": 1,
    "category": "Naturale",
    "date_created": "2023-09-30T18:01:14",
    "title": "Curabitur volutpat",
    "excerpt": "Gravida ligula accumsan cursus. Donec consequat nibh id diam accumsan, eu suscipit ipsum condimentum.",
    "text": "Maecenas lacinia est hendrerit lobortis suscipit. Curabitur purus neque, dignissim vel lacinia eleifend, pellentesque imperdiet augue. Suspendisse vestibulum rutrum nibh, in facilisis urna pharetra at. Integer posuere nunc eu justo ultrices semper. Aliquam ut ullamcorper purus, et malesuada dui. Fusce nec lorem ultrices, malesuada ipsum a, feugiat dui. Donec tortor nulla, sagittis et erat a, finibus dapibus libero.",
    "image": {
        "src": "uploads/woman-tearing-mint-leaves.jpg",
        "name": "",
        "alt": ""
    },
    "permalink": "post.html?id=1",
    "author": "Aliquam Tincidunt",
    "views": 5,
    "featured": true
}

Using a Python script named "metamorph.py", located in the repository's "bin" directory, various types of JSON files can be generated for consumption by the templates. The script can be analyzed in detail here.

After executing the "metamorph.py" script, the resulting data and file directory structure are as follows:

├── blog/
│   ├── bin/
│   │   │── metamorph.py
│   ├── public/
│   │   ├── data/
│   │   │   ├── archives/
│   │   │   │   ├── 2023-09/
│   │   │   │   │   ├── 1.json
│   │   │   │   ├── 2024-02/
│   │   │   │   ├── 2024-04/
│   │   │   ├── categories/
│   │   │   │   ├── all/
│   │   │   │   │   ├── 1.json
│   │   │   │   ├── imaginatio/
│   │   │   │   ├── mundos/
│   │   │   ├── posts/
│   │   │   │   ├── 1.json
│   │   │   │   ├── 2.json
│   │   │   │   ├── 3.json
│   │   │   ├── raw/
│   │   │   │   ├── 1.json
│   │   │   │   ├── 2.json
│   │   │   │   ├── 3.json
│   │   │   ├── archives.json
│   │   │   ├── elsewhere.json
│   │   │   ├── featured-post.json
│   │   │   ├── featured-posts.json
│   │   │   ├── most-read.json
│   │   │   ├── navbar.json
│   │   │   ├── recent-posts.json
│   │   ├── templates/
│   │   ├── assets/
│   │   ├── index.html
│   │   ├── post.html
│   │   ├── tasks.json
│   │   ├── tasks-post.json
└── server.py

The contents of the directory structure can be viewed in detail within the repository where the example blog resides.

Below is the JSON file used to populate the menu bar template.

public/data/navbar.json

[
    {
        "category": "Most Recent",
        "category_slug": "all",
        "page": 1
    },
    {
        "category": "Imaginatio",
        "category_slug": "imaginatio",
        "page": 1
    },
    {
        "category": "Mundos",
        "category_slug": "mundos",
        "page": 1
    }
]

Populating Templates with Data

Now, let's examine templates and how data is associated with them. We'll examine the template used to generate the navigation menu, triggered by the "add-navbar" task:

public/templates/nav-bar.html

<ul class="navbar-nav nav-underline">${(() => {
    if (!task.ok) {
        return task.status === 404 ? `<strong>${data}</strong>` : 'an error happened!';
    }

    return data.map(record => `<li class="nav-item">
        <a href="/?page=1&category-slug=${record.category_slug}#posts-list"
            ${window.location.pathname !== '/post.html' ?
                `data-tasks="show-posts-list"
                data-trigger="click"
                data-after="remove-active-menu add-active-menu scroll-into-posts-list"
                data-src-data="data/categories/${record.category_slug}/1.json"` : ''}
                class="nav-item nav-link ${window.location.pathname !== '/post.html' &&
                    record.category_slug === 'all' ? 'active' : ''}">${record.category}</a>
        </li>`).join("");
})()}</ul>

The template combines HTML and JavaScript. To understand this approach, consider how PHP pages are generated. In PHP, code is embedded within the HTML. Similarly, this library leverages JavaScript template literals to achieve the same objective. From the definition: "Template literals are literals delimited with backtick (`) characters, allowing for multi-line strings, string interpolation with embedded expressions, and special constructs called tagged templates".

In this example, we see an object called "task" and a variable named "data". Essentially, the variable "data" serves as a shortcut for "task.result". The properties "ok" and "status" within the "task" object represent the outcome of the task and correspond to the result of the data fetch. Additionally, the "task" object contains the "event" object, which can be accessed through the "event" property: "task.event".

Additionally, templates can be incorporated into the HTML code either through the "script" HTML element with type type "text/template" or transmitted server-side via the "is-template" property, which is added to the task or specified in the "Secutio-Transformation: is-template:true" header. In this scenario, the template property is appended to the "task" object, providing access to the template via "task.template".

public/tasks.json

{
    "show-posts-list": {
        "trigger": "init",
        "attribute-trigger": "data-trigger",
        "src-data": "data/categories/all/1.json",
        "attribute-src-data": "data-src-data",
        "template": "templates/list-posts.html",
        "target": "#posts-list",
        "swap": "inner",
        "after": "scroll-into-posts-list",
        "attribute-after": "data-after"
    }
}

The "show-posts-list" task automatically starts upon blog load, as can be seen in the provided template. This task displays the latest posts. However, when a user clicks on the list to access posts through a click event, the triggering mechanism differs slightly.

Here's a breakdown of the process:

The HTML element where the task is declared possesses an attribute named "data-trigger";
When a click event loads the list, the value of the "data-trigger" attribute replaces the "trigger" property within the task declaration;
This replacement also applies to the "src-data" and "after" properties of the task.

If reusing an existing task is not desired, a new task can always be declared specifically for the click event.

How to Fix SEO Issues in Single-Page Web Applications (SPAs)

To improve search engine optimization (SEO) for a Single-Page Application (SPA), developers can leverage sitemaps and consider creating separate pages. This allows search engines to follow links and potentially improve indexing of the content within the SPA.

In SPAs, the History interface's "replaceState()" method is used to update the URL when users navigate to specific content. This method modifies the current history entry, replacing it with a state object and a URL that reflects the displayed content.

public/templates/single-post.html

${(() => {
    if (!task.ok) {
        return task.status === 404 ?
            `<strong>${data}</strong>` : 'an error happened!';
    }

    history.replaceState({}, "", data.permalink);

    return `<h3 class="pb-4 mb-4 fst-italic border-bottom">From the ${data.category}</h3>
        <article class="blog-post">
        <h2 class="display-6 link-body-emphasis mb-1">${(() => {
            document.title = 'Large - ' + data.title;
            return data.title;
        })()}</h2>
        <p class="blog-post-meta">${(() => {
            const dc = new Date(data.date_created + 'Z');
            return dc.toLocaleString('en-us',{year:'numeric', month:'long', day:'numeric'});
        })()} by <a href="#">${data.author}</a>
        </p>
        <p>
            <img src="${data.image.src}"
                class="figure-img img-thumbnail rounded"
                alt="${data.image.alt}"
                style="width: 50%;float: left;margin-right: 20px;">
            ${data.text}
        </p>
    </article>`;
})()}

As evident from the template above, whenever a user accesses a post, the client's URL changes to the URL specified in the data source for that post ("data.permalink"). The same behavior occurs when navigating to a category from the menu, whereupon the list of articles within that category is displayed (public/templates/list-posts.html).

Live Preview

This example does not use any database; it is based on static files and only needs an HTTP server to run. Any manual modification to the JSON files in the "data/raw" data directory requires running the "metamorph.py" script to update the remaining files.

To view the blog, simply use the Python HTTP server and execute the following command:

$ cd blog
$ python3 -m http.server -d public
Serving HTTP on 0.0.0.0 port 8000 (http://0.0.0.0:8000/) ...

Conclusion

In this project, our objective was to demonstrate the effectiveness of integrating the Secutio framework with Bootstrap to streamline the development of dynamic web applications. Comparable to PHP's utilization of templates in website development, Secutio's task-oriented approach with JavaScript literal templates minimizes the need for extensive JavaScript when working with Bootstrap components. This methodology has the potential to substantially decrease development time and complexity, rendering it well-suited for constructing interactive and responsive web applications.

The source code for this project is available here.

Additional details and explanations are available in the framework documentation. You can also access the code here.

Thank you for reading!

Simple Real-Time Chat App with Secutio, WebSockets & Go!

Henrique Dias — Tue, 26 Mar 2024 23:36:12 +0000

Secutio is a relatively new framework designed to streamline the development process for web applications, particularly single-page applications (SPAs). Its goal is to make building SPAs less complex.

Here's a breakdown of some key points about Secutio:

Simplifies Development: Secutio aims to reduce the inherent complexities involved in SPA development.
Task-Based Approach: Similar to how forms trigger actions, Secutio allows you to associate actions (called tasks) with any HTML element within your application.
Inspired by htmx: If you're familiar with htmx, a framework for building web applications with HTML, CSS, and Javascript, you might find some similarities with Secutio's approach. However, Secutio offers a distinct way of handling tasks.

In this previous post some fully functional demos can be seen.

The Project

This small project is intended to showcase the functionalities of the Secutio framework.

Let's create a simple chat web app using the "Secutio" framework to build the chat client and an extension to handle communication via Websockets. Below, I'll demonstrate how to load and register the extension. The server will be implemented in Go, and we'll utilize the standard "net/websocket" library.

The project structure outlined below is provided as an example and can be tailored to suit the specific requirements of individual projects.

├── chat/
│   ├── public/
│   │   ├── css/
│   │   │   ├── styles.css
│   │   ├── index.html
│   │   ├── tasks.json
└── serve.go

Chat Client

Now, we'll create the index.html file. In the <head> element, we will add a link to the stylesheet. Additionally, we'll define the path to the JSON file containing the tasks using the <script> element. We'll include the attribute data-tasktable and the src attribute with the file name. Tasks can also be added inline, operating similarly to styles.

<head>
    <title>Test Websockets</title>
    <link rel="stylesheet" href="css/styles.css">
    <script data-tasktable type="application/json" src="tasks.json"></script>
</head>

We added the <main> element to contain the chat thread, a <textarea>, as well as the "send sentence" and "exit chat" <buttons>. Tasks are executed using the data-tasks attribute, which includes the name of the associated task in the "tasks.json" file.

<main id="main" data-tasks="show-login">
    <div class="chat">
        <input type="hidden" id="myself" name="myself" value="">
        <div id="chat-thread" data-tasks="get-chat-thread"></div>
        <div class="panel">
            <textarea id="sentence"></textarea>
            <div class="actions">
                <button id="send-sentence">
                    <span class="material-symbols-outlined">chat</span>
                </button>
                <button id="logout" data-tasks="logout">
                    <span class="material-symbols-outlined">logout</span>
                </button>
            </div>
        </div>
    </div>
</main>

The task file contains properties associated with each task. Examining the first task "show-login", we observe that the trigger corresponds to the "init" event. This indicates that the task executes without user interaction, meaning it runs as soon as the page is fully loaded. It retrieves the template with the id "login-dialog-tpl" and appends it to the element target with the id "main".

The other tasks adhere to a similar pattern and can be executed either on the client-side or server-side, depending on the existence of the action and method properties. In this example, the approach follows the REST architecture. For instance, in the "get-chat-thread" task, an extension is defined, initialized, and registered after including the "secutio.js" and extension libraries.

tasks.json

{
    "show-login": {
        "trigger": "init",
        "target": "#main",
        "template": "#login-dialog-tpl",
        "swap": "append"
    },
    "login": {
        "action": "login",
        "method": "post",
        "callback": "login",
        "trigger": "click",
        "target": "#login-dialog > div",
        "template": "#login-dialog-message-tpl",
        "swap": "prepend",
        "then": "rm-dialog-message"
    },
    "rm-dialog-message": {
        "selector": "div.warning",
        "remove": {}
    },
    "logout": {
        "action": "logout",
        "attribute-action": "data-action",
        "method": "delete",
        "trigger": "click",
        "target": "#main",
        "template": "#login-dialog-tpl",
        "swap": "append",
        "then": "rm-dialog"
    },
    "rm-dialog": {
        "selector": "#login-dialog",
        "remove": {}
    },
    "get-chat-thread": {
        "extension": {
            "name": "websocket",
            "connect": "ws://localhost:8080/echo",
            "callback": "send-sentence",
            "element": "#send-sentence",
            "trigger": "click"
        },
        "trigger": "init",
        "target": "#chat-thread",
        "template": "#chat-thread-tpl",
        "swap": "prepend"
    }
}

Templates

Secutio offers two ways to define template content within tasks:

Inline definition: Use the HTML <script> with type "text/template" element with the character "#" at the beginning of the template name in the task definition. This is ideal for smaller or simpler templates.
Loading from a file: Otherwise, the template name in the task definition is used to specify the template file path on server side. This approach is suitable for larger or more complex templates.

These templates operate similarly to server-side templating engines like PHP, but in this case, they leverage JavaScript's built-in "Template literals" for client-side rendering. This approach offers advantages like improved performance and a more dynamic user interface. Notably, the Secutio library can work with both server-side and client-side templating solutions depending on the project's requirements.

The first template is invoked by the "show-login" task, presenting a dialog for the user to input a name. Upon clicking the "login" <button>, the "login" task is executed. Subsequently, the second template is utilized to either close the dialog or display an error message if applicable.

The second template introduces the "task" object. This object holds properties like "ok" and "status" that provide information about the request's outcome.

<script id="login-dialog-tpl" type="text/template">
    <dialog id="login-dialog">
        <div>
            <label for="new-user">Choose your favorite name</label>
            <input type="text" id="new-user" name="new-user" value="">
            <button class="close-dialog" data-tasks="login">Login</button>
        </div>
    </dialog>
    <script>
        document.getElementById("login-dialog").showModal();
    </script>
</script>

<script id="login-dialog-message-tpl" type="text/template">
    ${(() => {
        if (task.ok) {
            if (task.status === 201) { // Created
                document.querySelector('#sentence').value = "Entered the room...";
                document.querySelector('#send-sentence').click();
                document.getElementById("login-dialog").close();
            }
            return "";
        }
        if (task.status === 302) { // Found
            const user = document.querySelector('#myself').value;
            document.querySelector('#myself').value = '';
            return `<div class="warning">The user ${user} already exist!</div>`;
        }
        return "";
    })()}
</script>

Additionally, we have the template responsible for displaying each line of the chat. This template utilizes the variable "data" ("task.result" shortcode), which holds the information returned from the server, including the name of the user associated with the chat text.

<script id="chat-thread-tpl" type="text/template">
    <div class="chat-line">${(() => {
        const record = JSON.parse(data);
        const mySelf = document.getElementById("myself").value;
        return `<span class="user${(mySelf === record['login']) ? ' self' : ' '}">${record['login']}</span>
            <span>${record['data']}</span>`;
    })()}</div>
</script>

Finally, we reach the section where the "secutio" library is added to the page and initialized. Since we intend to utilize an extension, it must be specified next.

<script type="text/javascript"
    src="https://cdn.jsdelivr.net/gh/mrhdias/secutio@master/dist/js/secutio.min.js"></script>
<script type="text/javascript"
    src="https://cdn.jsdelivr.net/gh/mrhdias/secutio@master/dist/js/ext/websocket.min.js"></script>

Following initialization, the next step involves registering the extension, along with any additional callbacks required for processing supplementary data. All callbacks are linked to specific tasks, which are detailed in the "tasks.json" file above.

<script type="text/javascript">
    const app = new Secutio();
    app.init();

    app.extension_register('websocket', wsExtension);

    app.callback_register('login', ((task) => {
        const newUserElem = document.getElementById("new-user");
        if (newUserElem.value.length > 2) {
            task.data = { 'user': newUserElem.value };
            document.getElementById("myself").value = newUserElem.value;
            document.getElementById("logout").setAttribute('data-action', `logout/${newUserElem.value}`);
        }
    }));

    app.callback_register('send-sentence', ((socket) => {
        const userElem = document.querySelector('#myself');
        const dataElem = document.querySelector('#sentence');
        if (dataElem !== null && dataElem.value !== '') {
            socket.send(JSON.stringify({
                'login': userElem.value,
                'data': dataElem.value
            }));
            dataElem.value = '';
        }
    }));
</script>

Chat Server

The server consists of two main parts:

User Management: This part manages incoming and outgoing users. Client/server communication for user management also occurs via JSON. Here, JavaScript objects are likely encoded into JSON for data exchange during user creation (POST requests) and removal (DELETE requests). Responses adhere to typical HTTP statuses associated with the REST architecture (404 Not Found, 302 Found, 201 Created, etc.).
Conversation Flow: This part orchestrates the flow of conversation between users. Similar to user management, communication here also utilizes JSON. The standard "net/websocket" library of the Go language is used for real-time communication. Messages can be encoded and exchanged in JSON format between clients and the server. JSON, being a lightweight and human-readable data format, is a popular choice for exchanging data over Websockets. However, it's important to note that Websockets themselves are a protocol for establishing a persistent connection, while JSON is a separate format for structuring data. You can use any data format with Websockets, not just JSON.

server.go

package main

import (
    "encoding/json"
    "fmt"
    "log"
    "math"
    "net/http"
    "os/exec"
    "runtime"
    "strings"
    "time"

    "golang.org/x/net/websocket"
)

type User struct {
    Login string `json:"login"`
    Data  string `json:"data"`
}

type UserCheck struct {
    Exist bool   `json:"exist"`
    User  string `json:"user"`
}

type Connection struct {
    Ws             *websocket.Conn
    TimeInactivity *time.Time
}

type App struct {
    Connections map[string]*Connection
    Timeout     int
    PublicDir   string
    ListenPort  int
}

func openUrlInBrowser(url string) error {
    var cmd string
    var args []string

    switch runtime.GOOS {
    case "windows":
        cmd = "cmd"
        args = []string{"/c", "start"}
    case "darwin":
        cmd = "open"
    default: // "linux", "freebsd", "openbsd", "netbsd"
        cmd = "xdg-open"
    }
    args = append(args, url)

    return exec.Command(cmd, args...).Start()
}

func (app *App) checkInactivity() {
    for {
        usersLogout := []string{}
        for user := range app.Connections {
            difference := time.Until(*app.Connections[user].TimeInactivity)
            if math.Abs(difference.Minutes()) > float64(app.Timeout) {
                log.Printf("User Time Inactivity: %s (%.f)\n",
                    user, math.Abs(difference.Minutes()))
                delete(app.Connections, user)
                usersLogout = append(usersLogout, user)
            }
        }

        for _, userLogout := range usersLogout {
            userData := User{
                Login: userLogout,
                Data:  "Left the room",
            }
            jsonResp, err := json.Marshal(userData)
            if err != nil {
                log.Fatalln(err)
            }

            for user, connection := range app.Connections {
                if err := websocket.Message.Send(connection.Ws, string(jsonResp)); err != nil {
                    log.Printf("Can't send data to %s\r\n", user)
                    delete(app.Connections, user)
                }
            }
        }

        time.Sleep(time.Second * 5)
    }
}

func (app *App) wsHandler(ws *websocket.Conn) {

    go app.checkInactivity()

    for {
        var reply []byte
        if err := websocket.Message.Receive(ws, &reply); err != nil {
            log.Println("Can't receive")
            return
        }

        log.Printf("Received: %s: %s\n", ws.RemoteAddr(), string(reply))

        var user User

        if err := json.Unmarshal(reply, &user); err != nil {
            log.Fatalln(err)
        }

        if _, ok := app.Connections[user.Login]; !ok {
            log.Printf("user %s don't exist\n", user.Login)
            continue
        }
        if app.Connections[user.Login].Ws == nil {
            app.Connections[user.Login].Ws = ws
        }

        now := time.Now()
        app.Connections[user.Login].TimeInactivity = &now

        for login, connection := range app.Connections {
            if err := websocket.Message.Send(connection.Ws, string(reply)); err != nil {
                log.Printf("Can't send data to %s, so it is removed\n", login)
                delete(app.Connections, login)
            }
        }
    }
}

func (app *App) logout(w http.ResponseWriter, r *http.Request) {

    if r.Method != http.MethodDelete {
        http.Error(w, "Method not allowed",
            http.StatusMethodNotAllowed)
        return
    }

    path := r.URL.Path
    parts := strings.Split(path[1:], "/")
    if len(parts) != 2 {
        http.Error(w, "Bad Request",
            http.StatusBadRequest)
        return
    }

    user := parts[1]

    if _, ok := app.Connections[user]; !ok {
        http.Error(w, "Not Found",
            http.StatusNotFound)
        return
    }

    now := time.Now().Add(time.Minute * time.Duration(app.Timeout) * -1)

    app.Connections[user].TimeInactivity = &now

    w.WriteHeader(http.StatusOK)
}

func (app *App) login(w http.ResponseWriter, r *http.Request) {
    if r.Method != http.MethodPost {
        http.Error(w, "Method not allowed",
            http.StatusMethodNotAllowed)
        return
    }

    var data map[string]string

    if err := json.NewDecoder(r.Body).Decode(&data); err != nil {
        http.Error(w, "Bat Request",
            http.StatusBadRequest)
        return
    }

    if func() bool {
        if _, ok := app.Connections[data["user"]]; ok {
            return true
        }

        connection := Connection{}
        app.Connections[data["user"]] = &connection

        now := time.Now()
        app.Connections[data["user"]].TimeInactivity = &now

        return false
    }() {
        http.Error(w, "Found",
            http.StatusFound)
        return
    }

    w.WriteHeader(http.StatusCreated)
}

func NewApp() App {
    app := new(App)

    app.Connections = map[string]*Connection{}
    app.PublicDir = "./public"
    app.ListenPort = 8080
    app.Timeout = 15

    return *app
}

func main() {

    app := NewApp()

    mux := http.NewServeMux()

    mux.Handle("/echo", websocket.Handler(app.wsHandler))
    mux.HandleFunc("/login", app.login)
    mux.HandleFunc("/logout/", app.logout)
    mux.Handle("/", http.FileServer(http.Dir(app.PublicDir)))

    go func() {
        <-time.After(100 * time.Millisecond)
        openUrlInBrowser(fmt.Sprintf("%s:%d", "http://localhost", app.ListenPort))
    }()

    server := http.Server{
        Addr:    fmt.Sprintf(":%d", app.ListenPort),
        Handler: mux,
    }

    fmt.Printf("Server listening on %s\r\n", server.Addr)
    if err := server.ListenAndServe(); err != nil {
        panic(err)
    }
}

Naturally, everything can be executed in the style adopted by htmx if you opt for that approach. The HTML content will then be dynamically generated on the server-side and placed directly into the designated target according to the task executed.

Now that all the server-side code is ready and saved in the root directory structure as described above, let's proceed to run the server using the following command:

$ go run .
Server listening on :8080

Due to the "openUrlInBrowser" function, the web page will automatically open in your default browser. If it doesn't work, you can manually enter the address http://localhost:8080 to access it. Once on the page, you should see a dialog with the message "Choose your favorite name"

Conclusion

In this project, an extension was utilized for the first time to showcase the potential of extending the framework's functionalities. As noted earlier, the project is still in its early stages and subject to structural changes until a stable and reliable interface is achieved that meets users' needs, while maintaining the primary objective of simplicity.

The source code for this project is available here.

Additional details and explanations are available in the framework documentation. You can also access the code here.

Thank you for reading!

Exploring Secutio Task by Task. Setting "Events" Like Stylesheets!

Henrique Dias — Fri, 02 Feb 2024 09:49:10 +0000

Introduction

This article aims to showcase some of the features of the Secutio Framework. While the framework is still under development, its progress indicates that it provides an alternative with a quick learning curve. This allows anyone to create and prototype web applications, abstracting them from the complexity of using JavaScript.

Feature Demonstration

The following demos showcase some of the functionality already present in the framework, allowing users to explore its capabilities. Similar to the htmx framework, template rendering can be done server-side. However, only examples that do not require a backend are presented here."

Inline Tasks with CSS

In this demo, we demonstrate the ability to request a joke from a remote site without using JavaScript. During the request, a "loader" is displayed. Additionally, the demo illustrates the capability to change styles using only subtasks. Please review the code and give it a try!

The list of tasks specified inline can be provided from a JSON file: <script data-tasktable type="application/json" src="tasks.json"></script>.
Both modes can coexist, and there can even be multiple inline task and task declaration files, similar to CSS stylesheets. In the future, the specification of tasks should be done using a custom HTML element, as shown in the following example: <task src="tasks.json"></task>.

Show Dialog on Error

The demo below not only displays a joke but also presents a dialog with an error message if an error occurs during the request. In this instance, an incorrect URL is used to simulate this functionality.

If we examine the HTML code, the subtask to close the dialog can be executed either by clicking the close button within the dialog or by clicking the button to request a joke.

Fetch JSON Example

This last demo, borrowed from the MDN website for comparison, demonstrates a food shopping list obtained from a remote JSON file using only tasks and CSS.

The example also showcases the use of inline templates, employing JavaScript Template Literals. The JSON data obtained from the GET request is accessible through the "data" variable.

<script id="food-list-tpl" type="text/template">
  <ul>
    ${data['products'].map(record => `<li><strong>${record["Name"]}</strong>
      can be found in ${record["Location"]}. Cost: <strong>${record["Price"]}€</strong>
    </li>`).join("")}
  </ul>
</script>

Map is syntactic sugar for the JavaScript Array.map() method, which creates a new array from an existing one and is a convenient method for listing products through a loop. In the end, all the elements in the list are concatenated. There are several ways to accomplish this. There are several ways to achieve this, and conditional statements can be used to filter the elements.

Additional information and explanations for each of the properties used in the demos can be found in the framework documentation.

Conclusion

As evident from the HTML code in the demos, employing the concept of "Cascading Task Sheets", similar to style sheets, offers a practical means of overwriting tasks later. This can be accomplished either on the server side via the HTTP header or on the client side. Creating an application with dynamic content becomes simple and productive in a short amount of time. There is still much to be done, including the writing of documentation, but these demos provide insight into how it works and the way forward.

The source code for this library is available here.

Thank you for reading!

Rapid Prototyping with Flask, Bootstrap and Secutio

Henrique Dias — Tue, 30 Jan 2024 22:07:18 +0000

Introduction

Secutio is a project in the early stages of development with the goal of simplifying the creation of dynamic content in a straightforward manner. The vision is that anyone should be able to build a web application using only HTML, stylesheets, and a JSON structure where "tasks" are specified.

It easy update parts of a page and create a Single-page Application (SPA):

Try opening the network tab in the browser's dev tools. When the button is clicked, a GET request is sent to the https://v2.jokeapi.dev/joke/Any?format=txt&safe-mode endpoint. The response is then appended to the HTML element with the "id" of "output".

Demo Description

The example outlined in this article mimics the "click to edit" functionality found in the htmx framework. Similar to htmx, this framework offers a method to enable inline editing of all or part of a record without the need for a page refresh.

Secutio enables each HTML element to have one or more unique actions associated with it, referred to here as tasks. Let's expand the idea of actions, similar to those found in HTML forms, to include any HTML element. When an event is triggered on an HTML element with an associated task, it executes the defined action, enabling the creation of localized dynamic content without the need to reload the entire page.

Key features include:

Tasks associated with any HTML element;
Multiple tasks can be defined per element, as long as they are associated with different events;
Tasks specified in a file, similar to how styles are specified in a CSS file;
Inline task definitions, similar to inline styles;
Templates (embedded or loaded) using JavaScript Template Literals;
Client-side rendering of data via JSON content or static JSON files;
Support for server-side templates, such as the Jinja template library;
Definition of transformations and targets on the frontend or backend through an HTTP custom header.

And there's much more to come...

Setup the Project

The "click to edit" example is a page that enables the editing of an online contact without requiring a page refresh, in contrast to the process when using only HTML and submitting a form.

To make the demo more interesting, we will use the Bootstrap framework and Flask as the backend.

A simple project structure:

├── click-to-edit/
│   ├── public/
│   │   ├── css/
│   │   │   ├── styles.css
│   │   ├── index.html
│   │   ├── tasks.json
└── server.py

The example consists of a single HTML page (index.html) with two embedded templates, "details-contact-tpl" and "edit-contact-tpl". The HTML content to render must be within the "script" tag with type "text/template". Within the "head" element, there is an HTML "script" element with the "data-tasktable" attribute and a "src" attribute specifying the file path for the "tasks" file. The JavaScript library, 'secutio.js,' responsible for processing tasks and replacing variables in templates, is then added at the end.

<!doctype html>
<html lang="en">

<head>
    <title>Click To Edit</title>
    <link rel="icon" type="image/svg+xml" href="img/favicon.svg">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta http-equiv="Cache-control" content="no-cache">
    <meta name="author" content="Henrique Dias">
    <link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/css/bootstrap.min.css"
        integrity="sha384-T3c6CoIi6uLrA9TneNEoa7RxnatzjcDSCmG1MXxSR1GAsXEV/Dwwykc2MPK8M2HN" crossorigin="anonymous">
    <link rel="stylesheet" href="css/styles.css?2024011401">
    <script data-tasktable type="application/json" src="tasks.json"></script>
</head>

<body>

    <div id="details-contact" data-tasks="show-contact"></div>

    <!-- embedded templates -->

    <script id="details-contact-tpl" type="text/template">
        <div id="details-contact">
            <div class="mb-3"><label>First Name</label>: ${data.firstname}</div>
            <div class="mb-3"><label>Last Name</label>: ${data.lastname}</div>
            <div class="mb-3"><label>Email</label>: ${data.email}</div>
            <button data-tasks="edit-contact" data-task-action="/contact/${data.id}/edit"
                class="btn btn-outline-primary btn-sm">
                Click To Edit
            </button>
        </div>
        <script type="text/javascript">
            console.log('Yes work!');
        </script>
    </script>

    <script id="edit-contact-tpl" type="text/template">
        <form id="details-contact" data-tasks="save-contact" data-task-action="/contact/${data.id}/save">
            <input type="hidden" name="id" value="${data.id}">
            <div class="mb-3">
                <label for="firstname" class="form-label">First Name</label>
                <input class="form-control" id="firstname" type="text" name="firstname" value="${data.firstname}"
                    placeholder="First Name" required>
            </div>
            <div class="mb-3">
                <label for="lastname" class="form-label">Last Name</label>
                <input class="form-control" id="lastname" type="text" name="lastname" value="${data.lastname}"
                    placeholder="Last Name" required>
            </div>
            <div class="mb-3">
                <label for="email" class="form-label">Email Address</label>
                <input class="form-control" id="email" type="email" name="email" value="${data.email}"
                    placeholder="name@example.com" required>
            </div>
            <div>
                <button class="btn btn-outline-primary btn-sm">Submit</button>
                <button class="btn btn-outline-primary btn-sm" data-tasks="show-contact"
                    data-task-trigger="click">Cancel</button>
            </div>
        </form>
    </script>

    <script src="https://cdn.jsdelivr.net/npm/bootstrap@5.3.2/dist/js/bootstrap.bundle.min.js"
        integrity="sha384-C6RzsynM9kWDrMNeT87bh95OGNyZPhcTNXj1NW7RuBCsyN/o0jlpcV8Qyq46cDfL"
        crossorigin="anonymous"></script>

    <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>

</body>

</html>

On the HTML page, we can observe several attributes defining tasks: data-tasks="show-contact", data-tasks="edit-contact", and data-tasks="save-contact". The properties of these tasks are specified in the JSON file named "tasks.json", which is shown below.

The "details-contact-tpl" template displays the details of a contact. The associated div contains a button that, when pressed, triggers the "edit-contact" task to retrieve the editing form ("edit-contact-tpl" template) UI for the contact. The form has a "save-contact" task that issues a PUT request to /contact/1, following the usual RESTful pattern.

{
    "show-contact": {
        "action": "/contact/1",
        "method": "get",
        "attribute-trigger": "data-task-trigger",
        "trigger": "init",
        "target": "#details-contact",
        "template": "#details-contact-tpl",
        "swap": "outer"
    },
    "edit-contact": {
        "attribute-action": "data-task-action",
        "method": "get",
        "trigger": "click",
        "target": "#details-contact",
        "template": "#edit-contact-tpl",
        "swap": "outer",
        "before": "remove-script"
    },
    "save-contact": {
        "attribute-action": "data-task-action",
        "method": "put",
        "trigger": "submit",
        "target": "#details-contact",
        "template": "#details-contact-tpl",
        "swap": "outer"
    },
    "remove-script": {
        "selector": "#details-contact + script",
        "remove": {}
    }
}

The explanations for each attribute and task property can be found in the project documentation (which is still incomplete).

The Flask framework (Python) was employed to create the HTTP server that serves JSON content, rendering the contact on the client side in accordance with the RESTful pattern.

#!/usr/bin/python
#
# https://flask.palletsprojects.com/en/3.0.x/installation/
#

from flask import Flask, jsonify, request

contacts = [
    {
        "id":        "1",
        "firstname": "Lorem",
        "lastname":  "Ipsum",
        "email":     "lorem.ipsum@example.com",
    },
    {
        "id":        "2",
        "firstname": "Mauris",
        "lastname":  "Quis",
        "email":     "mauris.quis@example.com",
    },
    {
        "id":        "3",
        "firstname": "Donec Purus",
        "lastname":  "Purus",
        "email":     "donec.purus@example.com",
    }
]

app = Flask(__name__,
            static_url_path='',
            static_folder='public',)

@app.route("/contact/<int:id>/save", methods=["PUT"])
def save_contact(id):
    data = request.json
    contacts[id - 1] = data

    return jsonify(contacts[id - 1])

@app.route("/contact/<int:id>", methods=["GET"])
@app.route("/contact/<int:id>/edit", methods=["GET"])
def get_contact(id):
    return jsonify(contacts[id - 1])

@app.route('/')
def root():
    return app.send_static_file('index.html')

if __name__ == '__main__':
    app.run(debug=True)

Conclusion

The concept of "styelization" of "tasks", akin to CSS styles, enables the dynamic creation of content without cluttering HTML elements with excessive attributes. It also facilitates the creation of a cascade of tasks that can be applied before and after content is swapped in the target HTML element, in a straightforward and practical manner.

The source code for this demo is available here: click to edit

Thank you for reading!

Creating HTML Templates for Binding JSON Data with JavaScript Template Literals

Henrique Dias — Fri, 12 Jan 2024 20:21:24 +0000

Introduction

The objective of this project/prototype is to simplify the development of web applications (single-page applications) by reducing the inherent complexity. The guiding principle is the KISS ('Keep it simple, stupid') motto.

The Prototype II

This article follows the previous one I wrote and stems from refining the idea described there.

Now, let's consider a scenario where we want to display a list of contacts in a table. The common approach involves making a request to the server to obtain the list. However, various scenarios may unfold: one involves receiving a complete HTML page with the table already inserted (resulting in a reload); another entails receiving an HTML fragment with linked data that can be placed in the destination target (as exemplified, for instance, by the htmx library); and lastly, we may receive a JSON data structure in response, enabling the dynamic creation of the table through JavaScript on the client side.

The last scenario is one that many developers have encountered, considering the widespread use of the REST architecture and the multitude of APIs. These APIs exist due to their simplicity, scalability, and easy integration, serving as the glue that unites numerous services and supports various companies across SAAS (web development, e-commerce, service integration, microservices, cloud computing, internet of things, etc.). Hence, the concept of having a simple tool that almost magically generates the contact table on the client side using HTML templates, JavaScript Template literals, and a few more layers of magic is something that accelerates and streamlines the developer's workflow, saving a significant amount of time and effort.

The concept is not new and is already in use, involving the use of 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.

To implement this idea I created a library that is still a prototype that uses many of the ideas from the first article I wrote and some based on htmx and the knockoutjs library. This library is still in the early stages of development, so it is a prototype that evolves over time and is subject to structural changes and the addition of new ideas.

The idea I had is that, rather than selecting the template on the client side and defining the location where the template is placed along with the "transformations" to be applied, these same parameters can also be specified on the server side (but never both). This approach is practical because, depending on the data to be sent and the constraints encountered during processing, we can choose one template or another and determine different transformations for use on the client side.

To associate the JSON data structure with the template, the web server sends a personalized header (Automata-Transformation) along with the body. This header includes information about the transformation to be applied to the template on the client side and specifies the final destination for the resulting transformation outcome. The header consists of its case-insensitive name followed by a colon (:), then by its value (key/value).

Response Header Example:



HTTP/1.1 200 OK
Automata-Transformation: target:#example;template:#example-tpl;swap:afterbegin;remove:#example-modal
Content-Type: application/json

{
    "employee": {
        "name": "John",
        "age": 30,
        "city": "New York"
    }
}

List of available properties to use in the HTTP header or tasks:

target: uses the first document element that matches the specified CSS selector as the final destination for data association with the template;
template: this property enables you to choose the template for use to associate the data. If the name 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. Conversely, if it starts with "@", it signifies that it is a template to be loaded from the templates directory;
swap: this property controls how content is swapped into the target element (default: innerHTML) (optional);
remove: uses a list of document elements matching the specified group of CSS selectors to be removed before inserting the template into the destination (optional).

While the transformation can be defined on the client side, the server-side HTTP header is optional. However, it proves practical on the server side, allowing you to decide which template to use based on the data.

When the response reaches the client, the matching is done with the selected template using template literals. Each literal expression is converted into a string corresponding to the content of the sent data structure. The variable with the JSON structure that contains the data is always called "data".

Experiment

To better visualize the process, let's create a table with a list of contacts retrieved from a JSON response. To achieve this, we'll first construct a JSON data structure that represents the contacts, as shown below.



[
    {
        "id": "1",
        "name": "Lorem Ipsum",
        "email": "lorem.ipsum@example.com",
        "status": "Active"
    },
    {
        "id": "2",
        "name": "Mauris Quis",
        "email": "mauris.quis@example.com",
        "status": "Active"
    },
    {
        "id": "3",
        "name": "Donec Purus",
        "email": "donec.purus@example.com",
        "status": "Active"
    }
]

Now that we have the list, let's create a HTML template and associate it with the contact data using the Template literals mentioned above. HTML templates can be embedded (identified by the HTML element "template" or loaded from a URL. This latter option is ideal for creating reusable components that can be inserted into the HTML structure.

Template example:



<template id="contacts-list-tpl">
    <textarea data-codeblock>
        <table>
            <thead>
                <tr>
                    ${(function () {
                        let headers = [];
                            for (const header of ["&nbsp;", "Name", "Email", "Status"]) {
                                headers.push(`<th>${header}</th>`);
                            }
                            return headers.join("");
                    }())}
                </tr>
            </thead>
            <tbody>
                ${data.map(record => `<tr>
                    <td>
                        <input type="checkbox"
                            name="id"
                            value="${record.id}">
                    </td>
                    <td>${record.name}</td>
                    <td>${record.email}</td>
                    <td>${record.status}</td>
                </tr>`).join("")}
            </tbody>
            <tfoot>
                <tr>
                    <td colspan="4">
                        <button name="switch-status" value="activate"
                            data-tasks="switch-contact-status" disabled>Activate</button>
                        <button name="switch-status" value="deactivate"
                            data-tasks="switch-contact-status" disabled>Deactivate</button>
                    </td>
                </tr>
            </tfoot>
        </table>
    </textarea>
</template>

We have a template with a table for the contact list. If we inspect the table, we notice that the template element is followed by a "textarea" element. This arrangement allows the HTML code inside the element to be preserved as is for interpolation. If the "textarea" element is omitted, all content within the template is converted to plain text, rendering the template unusable. This method works effectively as long as we ensure that all expressions within the backticks resolve to strings.

In the template, there are two buttons for activation/deactivation. Each button has a "data-tasks" attribute, which is utilized to execute an action based on the rules defined in a tasks file (refer to the previous article).

Expected result after data binding:



<table>
    <thead>
        <tr>
            <th>&nbsp;</th>
            <th>Name</th>
            <th>Email</th>
            <th>Status</th>
        </tr>
    </thead>
    <tbody>
        <tr>
            <td><input type="checkbox" name="id" value="1"></td>
            <td>Lorem Ipsum</td>
            <td>lorem.ipsum@example.com</td>
            <td>Active</td>
        </tr>
        <tr>
            <td><input type="checkbox" name="id" value="2"></td>
            <td>Mauris Quis</td>
            <td>mauris.quis@example.com</td>
            <td>Active</td>
        </tr>
        <tr>
            <td><input type="checkbox" name="id" value="3"></td>
            <td>Donec Purus</td>
            <td>donec.purus@example.com</td>
            <td>Active</td>
        </tr>
    </tbody>
    <tfoot>
        <tr>
            <td colspan="4">
                <button name="switch-status" value="activate"
                    data-tasks="switch-contact-status">Activate</button>
                <button name="switch-status" value="deactivate"
                    data-tasks="switch-contact-status">Deactivate</button>
            </td>
        </tr>
    </tfoot>
</table>

We have also created a "tasks.json" file with the list of tasks defined in buttons with the "data-tasks" attribute, as explained in the previous article.



{
    "get-contacts-list": {
        "action": "/listcontacts",
        "method": "get",
        "trigger": "click"
    },
    "switch-contact-status": {
        "action": "/statuscontact",
        "method": "put",
        "collect-data": "#contacts-list > table > tbody > tr > td > input[name]",
        "trigger": "click"
    }
}

Available properties for each task:

action: the action that is executed on the server when the event is triggered;
attribute-action: replaces the "action" property with the specified attribute, which should be present on the element with the 'data-tasks' attribute (optional);
method: set a request method (GET, POST, PUT, PATCH or DELETE) to indicate the desired action to be performed for a given resource;
collect-data: uses the data attributes given by the first element within the document that matches the specified selector as a source of data (optional);
trigger: specifies the event that triggers the request;

We can also utilize the properties available for the HTTP header (Automata-Transformation) here, but if the header already exists, the properties specified there take priority.

Finally, we will create an HTML page (index.html) containing the template and a field that serves as the target for the template after data association. Within this field, there is a button to trigger the association.

The JavaScript library ("Automata.js"), responsible for processing events and binding data to the attributes, was added at the end.



<!DOCTYPE html>
<html lang="en">

<head>
    <title>Test</title>
    <link rel="icon" type="image/svg+xml" href="/favicon.svg">
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta http-equiv="Cache-control" content="no-cache">
    <meta name="author" content="Henrique Dias">
    <link rel="stylesheet" href="styles.css?2024011101">
</head>

<body>

    <div id="contacts-list">
        <button data-tasks="get-contacts-list"
            class="contact-button">
            Get Contacts List
        </button>
    </div>

    <!-- embedded templates -->

    <template id="contacts-list-tpl">
        <textarea data-codeblock>
            <table>
                <thead>
                    <tr>
                        ${(function () {
                            let headers = [];
                                for (const header of [
                                    "&nbsp;", "Name",
                                    "Email", "Status"]) {
                                    headers.push(`<th>${header}</th>`);
                                }
                                return headers.join("");
                        }())}
                    </tr>
                </thead>
                <tbody>
                    ${data.map(record => `<tr>
                        <td>
                            <input type="checkbox"
                                name="id" value="${record.id}"> 
                        </td>
                        <td>${record.name}</td>
                        <td>${record.email}</td>
                        <td>${record.status}</td>
                    </tr>`).join("")}
                </tbody>
                <tfoot>
                    <tr>
                        <td colspan="4">
                            <button name="switch-status" 
                                value="activate"
                                data-tasks="switch-contact-status" 
                                disabled>Activate</button>
                            <button name="switch-status" 
                                value="deactivate"
                                data-tasks="switch-contact-status" 
                                disabled>Deactivate</button>
                        </td>
                    </tr>
                </tfoot>
            </table>
        </textarea>
    </template>

    <script>
        /* <![CDATA[ */
        import("./Automata.js?2024011001").then((module) => {
            const automata = new module.Automata();
            automata.init();
        });
        /* ]]> */
    </script>
</body>

</html>

Now that the frontend is planned, let's shift our focus to the backend. We'll create a web server in Go (can be in any language or framework) to handle incoming requests. When you click on the "Get contact list" button, a request is sent to the server to retrieve the contact list. Assuming the contacts are stored in a database, the server queries them and generates a JSON data structure containing the selected list of contacts, as shown above.

In the response to be sent to the client, some magic is included — a new custom HTTP header (Automata-Transformation) is added, containing information about the transformation to be applied. An example is provided below.



HTTP/1.1 200 OK
Automata-Transformation: target:#contacts-list;template:#contacts-list-tpl;swap:innerHTML
Content-Type: application/json

The web server code (server.go) is basic and intended solely for demonstration purposes. Static content is served from the "public" folder. Click here to see the python version.



package main

import (
    "encoding/json"
    "fmt"
    "log"
    "net/http"
    "os/exec"
    "runtime"
    "strings"
    "time"
)

type Contact struct {
    Id     string `json:"id"`
    Name   string `json:"name"`
    Email  string `json:"email"`
    Status string `json:"status"`
}

var contacts = []Contact{
    {
        Id:     "1",
        Name:   "Lorem Ipsum",
        Email:  "lorem.ipsum@example.com",
        Status: "Active",
    },
    {
        Id:     "2",
        Name:   "Mauris Quis",
        Email:  "mauris.quis@example.com",
        Status: "Active",
    },
    {
        Id:     "3",
        Name:   "Donec Purus",
        Email:  "donec.purus@example.com",
        Status: "Active",
    },
}

func openUrlInBrowser(url string) error {
    var cmd string
    var args []string

    switch runtime.GOOS {
    case "windows":
        cmd = "cmd"
        args = []string{"/c", "start"}
    case "darwin":
        cmd = "open"
    default: // "linux", "freebsd", "openbsd", "netbsd"
        cmd = "xdg-open"
    }
    args = append(args, url)

    return exec.Command(cmd, args...).Start()
}

func transformationHeader(transformations map[string]string) string {
    return strings.Join(func() []string {
        list := []string{}
        for k, v := range transformations {
            list = append(list, fmt.Sprintf("%s:%s", k, v))
        }
        return list
    }(), ";")
}

func switchContactStatus(w http.ResponseWriter, r *http.Request) {

    w.Header().Set("Content-Type", "application/json")

    if r.Method != http.MethodPut {
        http.Error(w, fmt.Sprintf(`{"message": "Method %s Not Allowed"}`, r.Method),
            http.StatusMethodNotAllowed)
        return
    }

    w.Header().Set("Automata-Transformation",
        transformationHeader(map[string]string{
            "target":   "#contacts-list",
            "template": "@contacts-list",
        }))

    content := struct {
        SwitchStatus string   `json:"switch-status"`
        Id           []string `json:"id"`
    }{}

    if err := json.NewDecoder(r.Body).Decode(&content); err != nil {
        http.Error(w, fmt.Sprintf(`{"message": "%s"}`, err.Error()),
            http.StatusBadRequest)
        return
    }

    for _, id := range content.Id {
        for i := range contacts {
            if contacts[i].Id == id {
                contacts[i].Status = func() string {
                    if strings.EqualFold(content.SwitchStatus, "deactivate") {
                        return "Inactive"
                    }
                    return "Active"
                }()
            }
        }
    }

    jsonResp, err := json.Marshal(contacts)
    if err != nil {
        http.Error(w, fmt.Sprintf(`{"message": "%s"}`, err.Error()),
            http.StatusInternalServerError)
        return
    }

    w.Write([]byte(jsonResp))
}

func listContact(w http.ResponseWriter, r *http.Request) {

    w.Header().Set("Content-Type", "application/json")

    if r.Method != http.MethodGet {
        http.Error(w, fmt.Sprintf(`{"message": "Method %s Not Allowed"}`, r.Method),
            http.StatusMethodNotAllowed)
        return
    }

    w.Header().Set("Automata-Transformation",
        transformationHeader(map[string]string{
            "target":            "#contacts-list",
            "template":          "#contacts-list-tpl",
            "swap":              "innerHTML",
        }))

    jsonResp, err := json.Marshal(contacts)
    if err != nil {
        log.Fatalf("Err: %v\r\n", err)
    }

    w.Write([]byte(jsonResp))
}

func main() {

    mux := http.NewServeMux()
    mux.HandleFunc("/statuscontact", switchContactStatus)
    mux.HandleFunc("/listcontacts", listContact)
    mux.Handle("/", http.FileServer(http.Dir("public/")))

    go func() {
        <-time.After(100 * time.Millisecond)
        openUrlInBrowser("http://localhost:8080")
    }()

    server := http.Server{
        Addr:    ":8080",
        Handler: mux,
    }

    fmt.Printf("Server listening on %s", server.Addr)
    if err := server.ListenAndServe(); err != nil {
        panic(err)
    }
}

If we examine the code, we can see in the "switchContactStatus" function that, in the custom HTTP header, the template is fetched from a URL (its name starting with the "@" character) instead of using a template embedded in the HTML page as in the "listContact" function. All templates are located in the "templates" directory.

The following directory structure is just a suggestion and can be adjusted to the needs of each project.

list-contacts/
- public/
  - Automata.js
  - index.html
  - styles.css
  - tasks.json
  - templates/
- server.go
- server.py (alternative)

Now that the code is ready and saved in the root of the directory structure indicated above, let's run the server with the following command:



$ go run .
Server listening on :8080

Conclusion

Associating JSON data structures with HTML templates using JavaScript Template literals is a practical way to abstract ourselves from the complexity of generating HTML on the client side with JavaScript alone. Template literals simplify the process of directly inserting variables into the template, making it easier to create and maintain HTML templates for reusable components. While not all use cases may currently be covered by this strategy, it contributes to accelerating the development speed.

The source code for this prototype is available here: list-contacts

Thank you for reading!

Like htmx, but with only one attribute per element - a prototype

Henrique Dias — Sat, 16 Dec 2023 11:43:54 +0000

Introduction

The htmx is a great tool that provides access to AJAX, CSS transitions, WebSockets, and server-sent events directly in HTML. It accomplishes this by using attributes such as hx-get, hx-post, hx-trigger, etc. within HTML tags. However, in certain scenarios, the use of many attributes in the same element can contribute to element pollution. Picture a train of attributes within the same element.

The Prototype

The concept behind this prototype is to apply the same principle as htmx but with a simplified approach, utilizing only one attribute (data-tasks) like the class attribute. The class attribute is often used to point to a class name in a style sheet. This prototype also uses an attribute but to perform tasks that are defined in a json file, to mimic the styles file used by classes.

We can imagine the "data-tasks" attribute like a class of css, but instead of styling the elements styles the actions?

Let's create a simple example to elucidate the concept. Essentially, it involves a button that, upon being clicked, triggers an action on the server, returning a html list. The list includes a button at the end to clear it and restore the initial state.

Example:

<div id="bag">
    <button data-tasks="get-fruits" class="fruits-button">
        Get Fresh Fruits
    </button>
</div>

The idea is that one or more tasks can be defined in an element, similar to classes, where one or more blocks can be defined within an element.
<element data-tasks="task-1 task-n" class="block-1 block-n"></element>

styles.css

.fruits-button {
    color: #37474F;
    font-weight: bold;
    background-color: #fff;
    border: 1px solid #000;
    cursor: pointer;
}
.fruits-button:hover {
    background-color: #c0c0c0;
}

To "stylize" the actions, we will use a JSON file because it is simple to define blocks with the values of the properties (key/value).

tasks.json

{
    "get-fruits": {
        "action": "/getfruits",
        "method": "get",
        "target": "#bag",
        "swap": "innerHTML",
        "trigger": "click"
    },
    "empty-bag": {
        "action": "/emptybag",
        "method": "get",
        "target": "#bag",
        "swap": "innerHTML",
        "trigger": "click"
    }
}

To implement the idea, I created a basic JavaScript library named "automata.js" with a class called "Automata". This library reads a json file containing tasks and executes them.

The crucial component is the MutationObserver interface, which enables the monitoring of changes to the DOM tree when HTML fragments are inserted or removed.

For testing purposes only a few events are used.

automata.js

/* <![CDATA[ */

class Automata {
    constructor(parameters = {
        "attribute": "data-tasks",
        "json_file": "tasks.json"
    }) {
        // https://developer.mozilla.org/en-US/docs/Web/API/Element#events
        // Some events to test
        this.triggers = new Set([
            'click',
            'mouseenter',
            'mouseover',
            'mouseup',
            'mouseleave'
        ]);
        this.dataAttribute = parameters["attribute"];
        this.jsonFile = parameters["json_file"];
        this.tasks = {};
    }

    async makeRequest(data = {}) {
        const response = await fetch(data.action, {
            method: data.method,
            cache: "no-cache"
        });

        const fragment = await response.text()
        return fragment;
    }

    async getDefinedTasks() {
        const response = await fetch(this.jsonFile, {
            cache: "no-cache"
        });

        this.tasks = await response.json();
    }

    setTask(element) {
        const elementTasks = element.dataset.tasks.split(/ +/);

        let _this = this;
        elementTasks.forEach(function (task) {
            if (_this.tasks.hasOwnProperty(task)) {
                // console.log("Task:", task);

                const parameters = _this.tasks[task];
                // the default trigger for Button is "click"
                if (!(parameters.hasOwnProperty('trigger') &&
                    _this.triggers.has(parameters.trigger)) &&
                    (element.nodeName === 'BUTTON' ||
                        (element.nodeName === 'INPUT' && element.type === 'button'))) {
                    parameters.trigger = 'click';
                }

                element.addEventListener(parameters.trigger, (event) => {
                    _this.makeRequest(parameters).then((data) => {
                        if (parameters.hasOwnProperty('target')) {
                            // console.log(data);
                            if (parameters.target === 'this') {
                                if (parameters.hasOwnProperty('swap') &&
                                    parameters.swap === 'outerHTML') {
                                    element.outerHTML = data;
                                } else {
                                    element.innerHTML = data;
                                }
                            } else {
                                if (parameters.hasOwnProperty('swap') &&
                                    parameters.swap === 'outerHTML') {
                                    document.querySelector(parameters.target).outerHTML = data;
                                } else {
                                    document.querySelector(parameters.target).innerHTML = data;
                                }
                            }
                        }
                    });
                }, false);
            }
        });
    }

    search4Tasks(parentNode) {

        const elemWithTasks = parentNode.querySelectorAll("[" + this.dataAttribute + "]");

        if (elemWithTasks.length > 0) {
            let _this = this;
            elemWithTasks.forEach(function (element, index) {
                // console.log(element.dataset.tasks);
                _this.setTask(element);
            });
        }
    }

    findTasksRecursively(addedNode) {

        if (addedNode.nodeType !== Node.TEXT_NODE &&
            addedNode.nodeType !== Node.COMMENT_NODE) {

            for (const node of addedNode.childNodes) {
                if (node.hasChildNodes) {
                    this.findTasksRecursively(node);
                }
            }

            if (addedNode.hasAttribute(this.dataAttribute) &&
                addedNode.getAttribute(this.dataAttribute) !== "") {
                this.setTask(addedNode);
            }
        }
    }

    init() {

        // https://developer.mozilla.org/en-US/docs/Web/API/MutationObserver

        const targetNode = document.getElementsByTagName('body');

        const config = {
            childList: true,
            subtree: true
        };

        const callback = (mutations, observer) => {
            mutations.forEach(mutation => {
                if (mutation.type === "childList") {

                    for (const addedNode of mutation.addedNodes) {
                        if (addedNode.nodeType === Node.TEXT_NODE ||
                            addedNode.nodeType === Node.COMMENT_NODE) {
                            continue;
                        }

                        if (addedNode.hasChildNodes) {
                            this.findTasksRecursively(addedNode);
                            continue;
                        }
                        if (addedNode.hasAttribute(this.dataAttribute) &&
                            addedNode.getAttribute(this.dataAttribute) !== "") {
                            this.setTask(addedNode);
                        }
                    }

                    for (const removedNode of mutation.removedNodes) {
                        if (removedNode.childNodes.length > 0 &&
                            removedNode.hasAttribute(this.dataAttribute)) {
                            console.log("Unimplemented removeEventListener...");
                        }
                    }

                    if (mutation.target.childNodes.length === 0) {
                        observer.disconnect();
                    }
                }
            });
        }

        const observer = new MutationObserver(callback);
        observer.observe(targetNode[0], config);

        this.getDefinedTasks().then(() => {
            this.search4Tasks(targetNode[0]);
        });
    }

}
// const automata = new Automata();
// automata.init();
/* ]]> */

Now, a basic HTML page.

index.html

<!DOCTYPE html>
<html lang="en">

<head>
    <title>Test</title>
    <meta charset="utf-8">
    <meta name="viewport" content="width=device-width, initial-scale=1">
    <meta http-equiv="Cache-control" content="no-cache">
    <meta name="author" content="Henrique Dias">
    <link rel=stylesheet href="styles.css">
</head>

<body>

    <div id="bag">
        <button data-tasks="get-fruits" class="fruits-button">
            Get Fresh Fruits
        </button>
    </div>

    <script src="automata.js"></script>
    <script>
        /* <![CDATA[ */
        const automata = new Automata();
        automata.init();
        /* ]]> */
    </script>
</body>

</html>

Finally, we need a web server to make this work, in this case I coded it in Golang, but it could be in another programming language.

server.go

package main

import (
    "fmt"
    "net/http"
    "os/exec"
    "runtime"
    "strings"
    "time"
)

func openUrlInBrowser(url string) error {
    var cmd string
    var args []string

    switch runtime.GOOS {
    case "windows":
        cmd = "cmd"
        args = []string{"/c", "start"}
    case "darwin":
        cmd = "open"
    default: // "linux", "freebsd", "openbsd", "netbsd"
        cmd = "xdg-open"
    }
    args = append(args, url)

    return exec.Command(cmd, args...).Start()
}

func getFruits(w http.ResponseWriter, r *http.Request) {

    w.Header().Set("Content-Type", "text/html")
    fmt.Fprintf(w, "<strong>%s</strong><ul>%s</ul><button data-tasks=\"empty-bag\" class=\"fruits-button\">Empty Bag</button>",
        "Bag contents:",
            strings.Join(func() []string {
            list := []string{}
            for _, fruit := range []string{
                "Orange",
                "Apples",
                "Pears",
                "Pineapple",
            } {
                list = append(list, fmt.Sprintf("<li>%s</li>", fruit))
            }
            return list
        }(), "\r\n"))
}

func emptyBag(w http.ResponseWriter, r *http.Request) {

        w.Header().Set("Content-Type", "text/html")
        fmt.Fprint(w, "<button data-tasks=\"get-fruits\" class=\"fruits-button\">Get Fresh Fruits</button>")
}

func main() {

    mux := http.NewServeMux()
    mux.HandleFunc("/getfruits", getFruits)
    mux.HandleFunc("/emptybag", emptyBag)
    mux.Handle("/", http.FileServer(http.Dir("public/")))

    // go openUrlInBrowser("http://localhost:8080")
    go func() {
        <-time.After(100 * time.Millisecond)
        openUrlInBrowser("http://localhost:8080")
    }()

    server := http.Server{
        Addr:    ":8080",
        Handler: mux,
    }

    fmt.Printf("Server listening on %s", server.Addr)
    if err := server.ListenAndServe(); err != nil {
        panic(err)
    }
}

In the end, the directory structure should be as follows:

fresh-fruits/
- public/
  - automata.js
  - index.html
  - styles.css
  - tasks.json
- server.go

To perform the test, follow these simple steps: navigate to the root of the prototype directory and execute the following command:

$ go run .
Server listening on :8080

The web page will open automatically in your default browser. Alternatively, you can manually enter the address http://localhost:8080 to access it. Once on the page, you should see a button with the text "Get Fresh Fruits".

Conclusion

This is merely a basic prototype with ample room for improvement. However, I believe it presents a straightforward alternative to appending a lot of attributes to HTML elements.

The source code for this prototype is available here: Automata

Thank you for reading!