Reactive Web Components
npm install reacton-jsGitHub | GitFlic | GitVerse | NpmJS | Download⤵️
Reacton (short Rtn) is a JavaScript framework for quickly creating reactive Web Components. It supports all the methods and properties that are provided by standard Web components. In addition, the framework contains a number of additional methods and implements server-side rendering of Web components.
Below is an example of creating a simple component:
``js
class WHello {
// initializing the properties of a state object
message = 'Reacton'
color = 'orangered'
static mode = 'open' // add Shadow DOM
// return the HTML markup of the component
static template =
}
1. Quick start
2. Component state
3. Cycles
4. Mixins
5. Views
6. Reactive properties
7. Static properties
8. Special methods
9. Event Emitter
10. Router
11. Server-side rendering
Quick start
Classes are used to create components. Classes can be either built into the main script or imported from an external module. Create a new working directory, for example named app, and download the rtn.global.js file into this directory.
Add an index.html file to the directory with the following content:
html
Document
`To ensure there are no naming conflicts between standard and custom HTML elements, the component name must contain a dash «-», for example, "my-element" and "super-button" are valid names, but "myelement" is not.
In most of the examples in this guide, the prefix will consist of a single letter «w-». that is, the Hello component will be called "w-hello".
When defining a component class, its prefix and name must begin with a capital letter. WHello is the correct class name, but wHello is not.
When you open the index.html file in the browser, the screen will display the message created in the Hello component:
Hello, Reacton!
The components can be placed in separate modules. In this case, the Hello component file would look like the following:
js
export default class WHello {
// initializing the properties of a state object
message = 'Reacton'
color = 'orangered' static mode = 'open' // add Shadow DOM
// return the HTML markup of the component
static template =
}
To work with external components, you will need any development server, such as lite-server.
You can install this server using the command in the terminal:
npm install --global lite-server
The server is started from the directory where the application is located using a command in the terminal:
lite-server
In addition, the framework supports single-file components that can be used along with modular ones when creating a project in the webpack build system.
An example of a simple single-file component is shown below:
html
Hello, {{ message }}!
`A single-file component must assign its class to the exports variable. This variable will be automatically declared during the creation of the component structure in the project's build system.
In single-file components, you can use the import instruction, for example:
html
`
Single-file components allow you to separate HTML markup from component logic. However, such components cannot work directly in the browser. They require a special handler that connects to the webpack.
To be able to work in the browser with components in which logic is separated from HTML content, there are built-in components.
An example of a simple embedded component is shown below:
html
Document
Hello, {{ message }}!
`The embedded component should return its class, and the contents of its <script> tag can be considered as a function. However, embedded components are not suitable for server-side rendering and, in addition, they cannot use the import instruction, but it is allowed to use the expression import(), for example:
html
`
For quick access to the component, it is enough to add an identifier to the element that connects the component to the document, as shown below:
html
`Now open the browser console and enter the commands sequentially:
hello.$state.message = 'Web Components'
hello.$state.color = 'blue'
The color and content of the header will change:
Hello, Web Components!
Component state
Each component can contain changing data, which is called a state. The state can be defined in the constructor of the component class:
js
class WHello {
constructor() {
// initializing the properties of a state object
this.message = 'Reacton'
this.color = 'orangered'
}
...
}
`Alternatively, using the new syntax, you can define the state directly in the class itself:
js
class WHello {
// initializing the properties of a state object
message = 'Reacton'
color = 'orangered'
...
}
`
The methods of a component are not a state. They are designed to perform actions with the state of the component and are stored in the prototype of the state object:
js
class WHello {
// initializing the property of a state object
message = 'Reacton' // define the method of the state object
printStr(str) {
return this.message
}
// return the HTML markup of the component
static template =
}
The special property $state is used to access the state object. Using this property, you can get or assign a new value to the state, as shown below:
hello.$state.message = 'Web Components'
The component content is updated automatically based on the new state.
When the content of a component is updated, its old DOM is not deleted. This means that the handlers assigned to the elements inside the component are preserved, since the old element is not replaced by a new element.
In the example below, the handler for the <h1> element will still work after the component state is updated. Because the update will only change the old value of its attribute and text content:
js
class WHello {
// initializing the property of a state object
message = 'Reacton' /* this method is performed after connecting the component to the document
when the DOM has already been created for the component from which you can select elements */
static connected() {
this.$('h1').addEventListener('click', e => console.log(e.target))
}
// return the HTML markup of the component
static template =
}
Cycles
Reacton supports three kinds of «for» loops that are implemented in JavaScript. They are all defined with a special $for attribute and output the contents of their HTML elements as many times as required by the loop condition.
This attribute will not be displayed in the compiled component.
In the example below, the «for» loop outputs 10 paragraphs with numbers from 0 to 9:
js
class WHello {
// return the HTML markup of the component
static template = Number: {{ i }}
}
In the special attribute $for you cannot use variable definition operators: var, let and const respectively. This will result in an error:
js
static template = Number: {{ i }}
The «for-in» loop is used to output the contents of objects, as shown below:
js
class WHello {
// initializing the property of a state object
user = {
name: 'John',
age: 32
} // return the HTML markup of the component
static template =
}
The «for-of» loop is designed to work with arrays:
js
class WHello {
// initializing the property of a state object
colors = ['red', 'green', 'blue'] // return the HTML markup of the component
static template =
}
When using events in loops using the special @event attribute, they will use the current value of the loop variable for their iteration phase:
js
static template =
More details about these events and other special attributes will be discussed later in the guide.
You can use loops with any nesting depth:
js
class WHello {
// initializing the property of a state object
users = [
{
name: 'John',
age: 32,
skills: {
frontend: ['HTML', 'CSS'],
backend: ['Ruby', 'PHP', 'MySQL']
}
},
{
name: 'Clementine',
age: 25,
skills: {
frontend: ['HTML', 'JavaScript'],
backend: ['PHP']
}
},
{
name: 'Chelsey',
age: 30,
skills: {
frontend: ['HTML', 'CSS', 'JavaScript', 'jQuery'],
backend: ['Ruby', 'MySQL']
}
}
] // return the HTML markup of the component
static template =
Name: {{ user.name }}
Age: {{ user.age }}
}
Mixins
Mixin is a general term in object-oriented programming: a class that contains methods for other classes. These methods can use different components, which eliminates the need to create methods with the same functionality for each component separately.
In the example below, the mixin's printName() method is used by the Hello and Goodbye components:
html
Document
`
Views
To display various components, a special attribute $view is used. This attribute can be assigned to any element, but usually the DIV element is used. The element containing the attribute is replaced by the component whose name is contained in the value of this attribute, for example:
html
Document
`The $view attribute cannot be used with loops. The example below will result in an error:
js
static template = Number: {{ i }}
Reactive properties
All state object properties used in a component are reactive, meaning that when their value changes, the values in all places in the component's HTML markup where these properties are used also change.
To insert reactive properties into text nodes, use double curly braces:
js
static template =
To insert a reactive property into an attribute, you must precede its name with a colon:
js
static template =
In the example below, a reactive property is added to a boolean attribute:
js
class WHello {
// initializing the property of a state object
hide = true // return the HTML markup of the component
static template =
}
The colon before the attribute name is used only in the component template HTML markup to indicate that the attribute accepts a reactive property. After compilation, the resulting component markup will display the attribute names without the colons.
For event attributes, the attribute name is preceded by the @ symbol, followed by the event name without the on prefix, as shown below:
js
class WHello {
// initializing the property of a state object
hide = true // return the HTML markup of the component
static template =
}
Instead of directly changing the reactive property in the event attribute, you can pass the name of a method that changes the reactive property, for example:
js
class WHello {
// initializing the property of a state object
hide = true // define the method of the state object
changeHide() {
this.hide = !this.hide
}
// return the HTML markup of the component
static template =
}
The event attributes contain an event object, using the target property of which you can get a reference to the element on which the event occurred:
js
static template =
Event attributes can have the same parameters that are passed in the third argument to the addEventListener method. These parameters are specified separated by a dot after the event name:
js
@click.once.capture.passive
`In the example below, the element that triggers the event will only be shown in the console once:
js
static template =
Static properties
alias – this static property allows you to add an alias for the this keyword, i.e. for the context of the state object:
js
class WHello {
// initializing the property of a state object
message = 'Reacton' static alias = 'o' // add alias for "this"
// return the HTML markup of the component
static template =
}
By default, there is no need to add the this keyword before the state object property names. However, if an alias is added, then either the alias or this keyword must be used before the property and method names.
time – this static property allows you to add a component refresh timer if you set it to "true" as shown below:
js
class WHello {
// initializing the property of a state object
message = 'Reacton' static time = true // add refresh timer
// return the HTML markup of the component
static template =
}
The component update time in milliseconds is displayed in the console after each change to any property of the state object.
name – this static property used, for example, when an anonymous class is passed to the Rtn function, as shown below:
js
// pass the anonymous class of the Hello component to the Rtn function
Rtn(class {
// initializing the property of a state object
message = 'Reacton' static name = 'w-hello' // name of the component
// return the HTML markup of the component
static template =
})
mode – this static property responsible for adding a Shadow DOM to the component. It can contain two values: "open" or "closed". In the latter case, when the component is closed, it is impossible to access the properties of its state object, methods for selecting elements and updating the content from the console.
Access to the properties of the state object, methods for selecting and updating the content of the component, in closed components is possible only from static methods, for example:
js
class WHello {
static mode = 'closed' // add a closed Shadow DOM // it is performed at the end of connecting the component to the document
static connected() {
// get an element using the sampling method
const elem = this.$('h1')
// add an event handler to the element
elem.addEventListener('click', e => console.log(e.target))
}
// initializing the property of a state object
message = 'Reacton'
// return the HTML markup of the component
static template =
}
Only components with a Shadow DOM can contain local styles.
extends – this static property responsible for creating customized components, i.e. those that are embedded in standard HTML elements, for example:
html
`The property must contain the name of the embedded element, and the embedded element itself must contain the is attribute with a value equal to the name of the component embedded in it.
serializable – this static property responsible for serializing the Shadow DOM of the component using the getHTML() method. By default, it has the value "false".
template() – this static property returns the future HTML content of the component as a string:
js
// return the HTML markup of the component
static template =
startConnect() – this static method is executed at the very beginning of connecting the component to the document, before generating the HTML content of the component and calling the static connected() method, but after creating the component state object.
In it, you can initialize the properties of the state object with the existing values:
js
class WHello {
// it is performed at the beginning of connecting the component to the document
static startConnect() {
// initializing the property of a state object
this.message = 'Reacton'
} // return the HTML markup of the component
static template =
}
or get data from the server to initialize their. But in this case, the method must be asynchronous:
js
class WHello {
// it is performed at the beginning of connecting the component to the document
static async startConnect() {
// initializing the state object property with data from a conditional server
this.message = await new Promise(ok => setTimeout(() => ok('Reacton'), 1000))
} // return the HTML markup of the component
static template =
}
This is the only static method that can be asynchronous.
connected() – this static method is executed at the very end of connecting the component to the document, after generating the HTML content of the component and calling the static startConnect() method.
In it, you can add event handlers to the internal elements of the component:
js
class WHello {
// initializing the property of a state object
message = 'Reacton' // it is performed at the end of connecting the component to the document
static connected() {
// get an element using the sampling method
const elem = this.$('h1')
// add an event handler to the element
elem.addEventListener('click', e => console.log(e.target))
}
// return the HTML markup of the component
static template =
}
This and all subsequent static methods are abbreviations of the standard static methods of the component.
disconnected() – this static method is executed when a component is removed from a document.
adopted() – this static method is executed when the component is moved to a new document.
changed() – this static method is executed when one of the monitored attributes is changed.
attributes – this static array contains the names of the monitored attributes, for example:
html
`
All static methods are called in the context of the proxy of the component state object. This means that if the required property is not found in the state object, then the search takes place in the component itself.
In the example below, the id property does not exist in the component state object. Therefore, it is requested from the component itself:
html
`
Special methods
All special methods and properties start with the dollar symbol «$» followed by the name of the method or property.
\$() – this special method selects an element from the component content by the specified selector, for example, to add an event handler to the element:
js
// it is performed at the end of connecting the component to the document
static connected() {
// get an element using the sampling method
const elem = this.$('h1') // add an event handler to the element
elem.addEventListener('click', e => console.log(e.target))
}
`This method fetches the contents of private components only if it is called from static methods of the component class.
\$$() – this special method selects all elements from the component content by the specified selector, for example, to add event handlers to the elements when iterating through them in a loop:
js
// it is performed at the end of connecting the component to the document
static connected() {
// get all elements using the sampling method
const elems = this.$$('h1') // iterate through a collection of elements in a loop
for (const elem of elems) {
// add an event handler to the element
elem.addEventListener('click', e => console.log(e.target))
}
}
`This method fetches the contents of private components only if it is called from static methods of the component class.
\$entities() – this special method neutralizes a string containing HTML content obtained from unreliable sources. By default, the ampersand character «&» is escaped, characters less than «<» and more than «>», double «"» and single quotes «'», for example:
js
class WHello {
// it is performed at the beginning of connecting the component to the document
static async startConnect() {
// getting HTML content from a conditional server
const html = await new Promise(ok => setTimeout(() => ok('
The special methods: \$event(), \$router() and \$render() will be discussed in the following sections. As with the \$entities() method, they also have their own named imports:
js
import Rtn, { Tag, Event, Router, Render } from "./rtn.esm.js"
`The Rtn function is always imported by default.
\$state – this special property refers to the proxy of the component's state object. This means that if the required property is not found in the state object, the search occurs in the component itself.
In the example below, the id property does not exist in the component state object. Therefore, it is requested from the component itself:
html
`
\$host – this special property refers to the element that connects the component to the document, i.e. the component element. This can be useful if properties with the same name are present in both the state object and the component..
The proxy of the state object initially looks for a property in the state object itself, which means that to get the property of the same name from the component element, you must use the special property $host, as shown below:
html
`
\$shadow – this special property refers to the Shadow DOM of the component:
hello.$shadow
For closed components and components without a Shadow DOM, this property returns "null".
\$data – this special property refers to the component's dataset object, which is used to access custom attributes, for example:
html
`
\$props – this special property refers to the state object of the parent component when the special attribute \$props without a value is passed to the child component:
html
`The special attribute \$props is specified here without any value:
js
// return the HTML markup of the component
static template =
To access the properties of the parent component's state object in the child component's HTML markup, a special property \$props is used, as shown below:
js
// return the HTML markup of the component
static template =
If it is necessary to transfer only some properties from the parent component, and not the entire state object, then the special attribute \$props must contain a value in which the names of the properties to be transferred are specified, separated by commas:
js
// return the HTML markup of the component
static template =
You can change the state of external components via the special property \$props of internal ones, but not vice versa. Because here we use one-way communication between components:
js
// parent component Hello
class WHello {
// initializing the property of a state object
message = 'Reacton' // return the HTML markup of the component
static template =
}// child component Inner
class WInner {
// return the HTML markup of the component
static template =
}
In order for any components to be able to change data in any other components, custom events are used, which will be discussed further.
Event Emitter
To enable components to interact with each other and exchange data, custom events are used. To create custom events, a special $event() method is used, which is available as a property of the Rtn function.
If the method is called as a constructor, it returns a new emitter object that will generate and track user events, for example:
js
const emit = new Rtn.event()
`An ordinary fragment of a document acts as an emitter. You can create as many new emitters as you want, and each emitter can generate and track as many new user events as you want.
When the $event() method is called as a regular function, it receives an emitter in the first argument, the name of the user event is passed in the second, and any data can be passed in the third argument:
js
this.$event(emit, 'new-array', ['Orange', 'Violet'])
`This data will then be available in the custom event handler as the detail property of the Event object, as shown below:
js
emit.addEventListener('new-array', event => {
this.rgb = event.detail
})
`In the webpack build system, the emitter can be exported from a separate module, for example, from a file Events.js:
js
import { Event } from 'reacton-js'
export const Emit = new Event()
`for the subsequent import of the emitter in the files of the components that will use it:
js
import { Emit } from './Events'
`
In the example below, a "click" event handler is added to each button from the Hello component, inside which the corresponding user event of the emitter object is triggered.
To track user events, the emitter is assigned the appropriate handlers in the Colors component. In the last handler, through the detail property of the Event object, a new array is assigned to the state property:
html
`
Router
The router is based on user events. To create route events, a special method $router() is used, which is available as a property of the Rtn function.
If the method is called as a constructor, it returns a new emitter object with the redefined addEventListener() method, which will generate and track route events, for example:
js
const emitRouter = new Rtn.router()
`When the $router() method is called as a regular function, it receives an emitter in the first argument, the name of the route event is passed in the second, and any data can be passed in the third argument:
js
this.$router(emitRouter, '/about', ['Orange', 'Violet'])
`In a real application, the name of the route event is not specified directly, as in the example above, but is taken from the value of the href attribute of the link that was clicked, for example:
js
this.$router(emitRouter, event.target.href, ['Orange', 'Violet'])
`
The user data passed in the last argument of the $router() method will be available in the route event handler as the detail property of the Event object, as shown below:
js
emitRouter.addEventListener('/about', event => {
const arr = event.detail
...
})
`The initial slash «/» in the name of the route event is optional:
js
emitRouter.addEventListener('about', event => {
const arr = event.detail
...
})
`The rest of the name of the route event, except for the initial slash, must completely match the value of the href attribute of the link, after clicking on which the handler corresponding to this value will be triggered:
html
About
`
The difference between user-defined and route events is that the string specified in the route event handler is converted to a regular expression and can contain special regular expression characters, as shown below:
js
emitRouter.addEventListener('/abou\\w', event => {
...
})
`In order not to have to use the backslash character twice in a regular string to escape special characters of regular expressions, you can use the tagged function raw() of the built-in String object by enclosing the name of the route event in a template string, for example:
js
emitRouter.addEventListener(String.raw/abou\w, event => {
...
})
`or so:
js
const raw = String.raw
emitRouter.addEventListener(raw/abou\w, event => {
...
})
`
In addition to the detail property, the Event object has an additional params property to get route parameters, as shown below:
js
emitRouter.addEventListener('/categories/:catId/products/:prodId', event => {
const catId = event.params["catId"]
const prodId = event.params["prodId"]
...
})
`This handler will be executed for all links of the form:
html
Product
`then catId will have the value 5 and prodId will have the value 7.
To support query parameters, the Event object has an additional search property, which is a short reference to the searchParams property of the built-in URL class, for example:
js
const raw = String.raw
emitRouter.addEventListener(raw/categories\?catId=\d&prodId=\d, event => {
const catId = event.search.get("catId")
const prodId = event.search.get("prodId")
...
})
`This handler will be executed for all links of the form:
html
Product
`then catId will have the value 5 and prodId will have the value 7.
The last addition property of the Event object is called url, which is an object of the built-in URL class and helps parse the request into parts:
js
emitRouter.addEventListener('/about', event => {
const hostname = event.url.hostname
const origin = event.url.origin
...
})
`
Below is an example of creating a simple router with three components for pages:
html
`To handle the routes of these pages, the router emitter is assigned a handler with an optional route parameter in the Content component:
js
// add an event handler to the emitter with an optional route parameter
emitRouter.addEventListener((:page)?, event => {
// assign a page component name to the property
this.page = w-${event.params.page || 'home'}
})
`In order for this handler to fire immediately when opening the application and connect the page component corresponding to the route, at the end of the connected() static method, an event is triggered for the address of the current route from the href property of the location object:
js
// initiate an event for the "href" value of the current page
this.$router(emitRouter, location.href)
`The rest of the pages components are loaded when you click on the corresponding link in the Menu component:
js
// add a "click" event handler for the NAV element
this.$('nav').addEventListener('click', event => {
event.preventDefault() // undo the default action
// initiate an event for the "href" value of the current link
this.$router(emitRouter, event.target.href)
})
`
Server-side rendering
SSR (Server Side Rendering) is a development technique in which the content of a web page is rendered on the server and not in the client's browser. To render the contents of web pages, the render() method is used, which is available as a property of the Rtn function. This method works both on the server side and in the client's browser.
In the example below, this method outputs the contents of the entire page to the browser console:
html
Document
Reactive Web Components