Riu-component NPM

A component-based JavaScript framework for building user interfaces. It is highly flexible and compatible with other frameworks and libraries. You can easily integrate it in existing projects or use it to create a web app from scratch. The framework provides a number of ways to manage resources in terms of reusability, loading and more. It provides built in support for plugins, allowing you to extend its functionality easily. RIU Component provides both declarative and procedural ways of building user interfaces.

Quick Start

Introduction

The easiest way to get started with RIU Component is using a CDN. Another way is by using NPM.

Installation

NPM

$ npm i riu-component --save

CDN

<script src="https://unpkg.com/riu-component"></script>

<script src="https://cdn.jsdelivr.net/npm/riu-component"></script>

Importing

import { riuComponent } from "riu-component";

Usage

A CDN will be used for this guide. To create a component, you can use either riuComponent or $riu. The method $riu is just an alias for riuComponent. We are going to use $riu because it is shorter and the sign $ provides an easy way of indicating that the function is used to create a component. The variables for components will be prefixed with $ in order to differenciate them from other variables.

The easiest way to create and use components is by using a schema. The schema contains attributes that are used to create a component. A schema will be used in this guide.

HTML:

<div id="hello-world"></div>

JS:

(async () => {
  const markup = `
    <main>
      <button>Say Hello</button>
    </main>
  `;

  const styles = `
    :scope {
      margin: 0;
      padding: 0;
      display: flex;
      justify-content: center;
      align-items: center;
      height: 100vh;
    }
    #say-hello {
      padding: 1rem;
      font-size: 2rem;
      font-weight: bold;
      color: #0cffff;
      background-color: #7f3fff;
      cursor: pointer;
    }
  `;

  const events = {
    "button": [
      {
        type: "click",
        listener: function (event) {
          alert("Hello World!");
        }
      }
    ]
  };

  const schema = { markup, styles, events };
  const $home = await $riu(schema);
  $home.replace("#hello-world");
})();

The HTML contains a <div> element with id hello-world. This is the element that will be replaced by our component. In the JavaScript, we crated the component and added to the DOM. A couple of steps were taken to achieve this. Let us look at each one of the steps.

1. Create Markup

The variable markup was declared and a template string containing the markup was assigned to it. This is the markup that will be used to create the component. To make things easy, HTML was used. XML can be used too, but it involves a little more work.

2. Create Styles

We put the styling for the component in a template string (styles) containing CSS. Notice the use of :scope to select the root element <main>. In standard CSS, the selector :scope selects the root element of the DOM no matter where the selector is used. In RIU Component, however, the selector always selects the root element of the component (in this case <main>). This is the only unusual behaviour of CSS selectors, the rest is normal CSS. The selector #say-hello selects the button.

3. Create Events

To make the component reactive, we added a click event to the button. In events, a CSS selector (#say-hello) was used to select the button. A click event was put in an array. The array can contain any number of events. The property type specified that the event is a click event. The property listener specified an event listener for the event.

4. Create Schema

A schema was created with the properties markup, styles and events.

5. Create Component

The component was created using $riu. The schema was passed as an argument in to $riu. Notice the use of await when creating the component ($home). This is because $riu is asynchronous.

6. Add Component Element to DOM

Finally, we inserted the component into the DOM using $HelloWorld.replace. The function inserts the component into the DOM by replacing the element (div#hello-world) specified by the CSS selector passed as the parameter.

Insertions

Components, elements, markup, text and data can be inserted into a component. Items can be inserted using either attribute names or attribute values. Attribute values are used to insert data, while attribute names are used to insert other items.

Data

Data is inserted using attribute values that start with @ and followed by the path to the value using object dot notation. Let us use schema.utils.data to insert data into an element's attribute.

const markup = `
  <main>
    <button title="@data.title">Say Hello</button>
  </main>
`;

const data = { title: "Say Hello" };
const utils = { data };
const schema = { ..., utils };

// ...

The attribute title of <span> will be updated to Say Hello. When you hover over span, the tootip will desplay "Say Hello". Note that data was added as a property of utils, which was the put in the schema.

Text

Let us change the text displayed on the button by programatically inserting text into the markup. This is done using the attribute riu-txt. The span element will be replaced with the text specified in the value of the attribute.

const markup = `
  <main>
    <button title="@data.title">
      <span riu-txt="action"></span>
    </button>
  </main>
`;

const data = { title: "Hello" };
const texts = { action: "Say Hello" };
const utils = { data, texts };
const schema = { ..., utils };

// ...

The button will contain the same text as before. The value action of riu-text points to schema.utils.texts.action.

Conditionals

Conditionals can be used to load, show and hide elements based on a particular condition. Conditionals are set on elements using attributes.

Loading

The loading conditional lets us load content when a particular condition has been met. Let us load content using lazy loading, which is one of the loading conditionals.

Markup:

<div class="images">
  <img src="/image-1.png" />
  <img src="/image-2.png" />
  <img src="/image-3.png" riu-loading="lazy" />
</div>

Images image-1.png and image-2.png will be loaded instantly. However, image-3.png will be loaded only if the user scrolls down the the area the image is supposed to occupy. The attribute riu-loading has a normal string or a JSON string as its value. In this case, we have used a normal string with the value lazy, in which case the default values for lazy loading will be used. Check out Loading for more information.

Display

You can display elements only if a particular condition is met using the display conditional. Let us see how we can make a button not to be displayed on large screens.

<button class="menu-toggle" riu-display='{"dislay": "none", "conditions": [{"query": "(min-width: 992px)"}]'>
  <img src="./menu.svg" />
</button>

The value of attribute riu-display is JSON object. The object has two attributes, type and conditions. The type of display of the element is indicated by type. The conditions that must be met for the element to have a display value specified in type are put in conditions, an array. The array can have any number of conditions. We have used a media query to make the button not to be displayed on screens with width atleast 992px. Check out Display for more information.

Collections

Collections are a way to turn a single element into a collection of elements containing variants of the element.

const markup = `
  <ul>
    <li riu-multiple='{"data": "@data.users"}'>
      <span riu-text="@datum"></span>
    </li>
  </ul>
`;

const users = ["user-1@email.com", "user-2@email.com", "user-3@email.com"];
const data = { users };
const utils = { data };
const schema = { utils };

// ...

In this case @datum refers to each item in the array schema.utils.data.users. The list will contain three items, each one of them containing a user email.