Vizu
allows the user to create and aggregate Vizu Web Components
and then render and manipulate them. It offers a similar API as React
but Vizu
directly writes to the DOM and it is much more lighter. As Vizu
provides a set of methods to manipulate the component's childs in the DOM tree (incremental DOM), it doesn't need a virtual DOM.
Vizu
introduces only two concepts: Vizu Web Components
and view
. A Vizu Web Component
is a Javascript object that defines an HTML block and methods to manipulate it. A view
is the aggregation of Vizu Web Components
.
Vizu
gives a direct access to all the Vizu Web Components
of the view whatever their position in the view hierarchy with a very fine granularity. But, the access could be restricted. A module can only access to the Vizu Web Components
it owns.
Vizu
is just old plain Javascript, HTML and CSS3. There is neither intermediate format nor pre-processing.
You want to see how to use Vizu
in a real application, click here. Kiwii-Vizu
is an example of an hybrid mobile application built with Vizu
as the View library.
import { Component } from 'vizu';
class Aaa extends Component {
constructor() {
super();
this.title = 'Hi!';
}
render() {
return `
<div>
<h1>${this.title}</h1>
</div>
`;
}
}
A Vizu Web Component
is defined by a class with, at least, the method render
that returns a plain old HTML block. You can insert Javascript instructions in it. They are processed when the component is rendered.
import { Vizu } from 'vizu';
Vizu.render(
`<Aaa />`,
{ '<Aaa />': Aaa },
document.getElementById('app'),
);
The method Vizu.render()
renders the Vizu Web Components
directly in the DOM tree. This method requires one mandatory argument and two optional arguments:
-
The first argument is a Javascript string that defines an HTML block. Here it is limited to an HTML tag; the
Vizu Web Component
. -
The second argument is a Javascript object. It contains the
Vizu Web Component
tags and their reference (reference to the class). If omitted, theVizu Web Component
tags aren't processed. -
And finally, the third argument is the DOM element in which the view is inserted as a child element. If omitted, the view is directly inserted into the
body
as the first node.
- Vizu
npm install --save vizu
import { Vizu } from 'vizu';
Vizu.render(
`<div>
<p>Hi!</p>
</div>`
);
As nothing else as an HTML block is defined here, Vizu
renders the block in the body of the HTML page.
<body>
<div id="id9td66c">
<p>Hi!</p>
<div>
</body>
A Vizu
component must always be a set of HTML tags surrounded by a div
. Vizu
adds an unique ID
to this Vizu Web Component
.
import { Vizu } from 'vizu';
Vizu.render(
`<Aaa />
<Bbb />
`,
{ '<Aaa />': Aaa, `<Bbb />`: Bbb },
document.getElementById('app'),
);
Here we want to render the Vizu Web Components
<Aaa />
and <Bbb />
.
The first argument is a Javascript string that contains the custom HTML tags <Aaa />
and <Bbb />
. They represent Vizu Web Components
(we will see later on how to define them). The tag contains the name of the class that defines the component preceded by <
and completed by />
.
The second argument is a Javascript object. It links the tags <Aaa />
and <Bbb />
to the references of their respective Vizu Web Components
(the classes that define them).
And finally, the third argument is a Javascript object that references the DOM element surrounding the rendered view.
It gives this:
<div id="app" class="container">
<div id="ifwhoesn">
<p>Hi!</p>
</div>
<div id="iqn96zqo">
<p>Hello!</p>
</div>
</div>
As seen above, an unique method render()
is required with Vizu
to render a View. This method requires three arguments: the components that compose the view, their reference and where they are inserted into the DOM tree.
import { Component } from 'vizu';
class Aaa extends Component {
render() {
return '<div></div>';
}
}
A Vizu Web Component
is defined by a class that extends the class Component
. This class must provide, at least, the method render()
. This method must return an HTML block. I.e. HTML tags surrounded by a div
.
Rendering this Vizu Web Component
results in:
<div id="app" class="container">
<div id="iynx1ktk">
</div>
</div>
import { Component } from 'vizu';
class Aaa extends Component {
constructor() {
super();
this.title = 'Title';
}
render() {
return `
<div>
<h1>${this.title}</h1>
</div>
`;
}
}
This Vizu Web Component
includes a Javascript variable initialized by the constructor
.
This variable is declared in the string in between ${}
as defined by the ES6 standard. It's pure Javascript!
Rendering this Vizu Web Component
results in:
<div id="app" class="container">
<div id="i7mlzk3r">
<h1>Title</h1>
</div>
</div>
A Vizu Web Component
could include another Vizu Web Component
:
import { Component } from 'vizu';
class Aaa extends Component {
constructor() {
super();
this.subtitle = 'Subtitle';
}
render() {
return `
<div>
<h2>${this.subtitle}</h2>
</div>
`;
}
}
class Bbb extends Component {
constructor() {
super();
this.title = 'title';
}
render() {
// Reference Aaa:
this.cList = { '<Aaa />': Aaa };
return `
<div>
<h2>${this.title}</h2>
<Aaa />
</div>
`;
}
}
A Vizu Web Component
can include another Vizu Web Component
quite easily. It just needs to be declared by a tag (here <Aaa />
) and referenced in the variable cList
attached to this component (here this.cList = { '<Aaa />': Aaa };
).
Rendering the Vizu Web Component
<Bbb />
results in:
<div id="app" class="container">
<div id="isoue0z7">
<h2>title</h2>
<div id="ios7lybb">
<h2>Subtitle</h2>
</div>
</div>
</div>
In the above examples, we initialized the variables with the constructor
. Vizu Component
provides a method for defining the initial value of the Javascript variables:
import { Component } from 'vizu';
class Aaa extends Component {
getInitialState() {
this.props.options.title = 'Title';
}
render() {
return `
<div>
<h1>${this.props.options.title}</h1>
</div>
`;
}
}
This is the preferred method to initialize variables.
The user can add his own methods to interact with the Vizu Web Component
:
import { Component } from 'vizu';
class Aaa extends Component {
getInitialState() {
this.props.options.title = 'Title';
}
// Method particular to this Vizu Web Component
updateTitle(title) {
this.props.options.title = title;
this.$('h1')[0].innerText = title;
}
render() {
return `
<div>
<h1>${this.props.options.title}</h1>
</div>
`;
}
}
This Vizu Web Component <Aaa />
has a specific method called updateTitle
. It updates the title of the component (we will see later on how to access this method).
This method relies on this.$('h1')[0].innerText
to change the title. The method $(el)
is just a wrapper around the Javascript function querySelector
.
If the method $()[]
has no selector (argument), it returns the entire HTML block that defines this Vizu Web Component
in the DOM tree.
Nota:
Component
implements a few shortcuts (see the reference section). For instance $('h1')[0].innerText
can be replaced by $('h1').text()
.
Vizu
provides the method createClass
to create Vizu Web Components
without ES6:
Vizu.createClass({
getInitialState: function() {
this.props.options.title = 'Title';
},
render: function() {
return `
<div>
<h1>` + this.props.options.title + `</h1>
</div>
`;
}
});
A Vizu Web Component
is a Javascript class that extends the Vizu
class Component
.
A Vizu Web Component
could define a simple block of HTML tags surrounded by a div
or/and it can include other Vizu Web Component
.
A Vizu Web Component
offers, at least, the method render()
that returns a set of HTML tags surrounded by a div
.
A Vizu Web Component
can provides the method getInitialState
that defines some javascript variables included in the HTML block.
A Vizu Web Component
can be extended with specific methods.
Vizu Web Component
implements the method events()
that is executed when the component is rendered in the DOM tree to attach events.
Example for a counter:
import { Component } from 'vizu';
class Counter extends Component {
getInitialState() {
this.props.options.counter = 0;
}
events() {
const self = this;
let counter = this.props.options.counter;
// Increment:
this.$('.plus').on('click', () => {
counter += 1;
self.$('h1').text(counter);
});
// Decrement:
this.$('.minus').on('click', () => {
counter -= 1;
self.$('h1').text(counter);
});
}
render() {
return `
<div>
<h1>${this.props.options.counter}</h1>
<button class="minus">-</button>
<button class="plus">+</button>
</div>
`;
}
}
When the view is rendered, Vizu
returns an object on this view:
import { Component } from 'vizu';
const view = Vizu.render(
`<Aaa />`,
{ '<Aaa />': Aaa },
document.getElementById('app'),
);
The view
object can be used to interact with the Vizu Web Components
that compose the view.
The Vizu Web Component
Aaa
can be accessed by:
view.Aaa;
The Vizu Web Component
returns three variables:
view.Aaa.id;
view.Aaa.cList;
view.Aaa.components
id
is the id of the Vizu Web Component
(the id of the surrounding div
).
cList
is an object that lists the Vizu Web Components
included in this component(null
if none).
components
is an object that references the Vizu Web Components
included in this component (null
if none). For instance if Aaa
includes Bbb
, Bbb
could be accessed by:
view.Aaa.components.Bbb
The defined methods of a Vizu Web Component
can be accessed by:
view.Aaa.updateTitle('Hello!');
The method of a Vizu Web Component
that belongs to a parent
Vizu Web Component
can be accessed by:
view.Aaa.components.Bbb.updateTitle('Hello Again!');
Sometimes, you need to replace a complete Vizu Web Component
in the view
. For instance, if your application consists of a view
built with four Vizu Web Components
: Header, Footer, Menu, Contents. When the user moves from one page to another, you have to change all the contents section of the application:
// Render a view:
const view = Vizu.render(
`<Aaa />`,
{ '<Aaa />': Aaa },
document.getElementById('app'),
);
// Aaa contains a subcomponent Bbb that needs to be replaced by Ccc:
Vizu.replace(view, { '<Bbb />': Ccc });
You just need to call the method Vizu.replace
. The first argument is the view
object and the second argument is an object whose property is the tag of the web component to replace and the value is the reference to the new Vizu Web Component
.
class <new component> extends Component {
constructor() {
}
getInitialState() {
}
$() {
}
events() {
}
render() {
}
}
A Vizu Web Component
is a class object that extends the class Component
of Vizu
. It implements four methods:
-
getInitialState
: this method is executed before the component is rendered. It initializes Javascript variables at their initial value. -
$
: this method interacts with the DOM elements of the selectedVizu Web Component
.$
is a wrapper around the Javascript functionquerySelector
and it implements a few functions (see below). -
events
: this method attaches events to the component when it is rendered in the DOM tree. -
render
: this method returns the component defined in a string by HTML tags.
Methods | Description
$() | selects the Vizu Web Component and returns this,
$(sel) | selects the child element with the attribute 'sel' and returns this,
$().id | returns the id of selected element,
$()[0] | returns the selected DOM element,
$().selectChild(n) | selects the nth child,
$().parent() | selects the parent node,
$().firstParent() | selects the root parent node if defined,
$().html() | returns the child element(s) of the selected element.
$().html(xml) | replaces the child element by a new element defined by the passed-in XML string and returns this,
$().empty() | removes all the child nodes and returns this,
$().append(xml) | inserts the element (defined by the passed-in XML string) after the last child node and returns this,
$().prepend(xml) | inserts the element before the first child node and returns this,
$(el).after(xml)¹ | inserts the element after the selected element and returns this,
$(el).before(xml)¹ | inserts the element before the selected element and returns this,
$(el)replaceWith(xml)¹ | replaces the selected element by the passed-in element and returns this,
$().text() | returns the contents of the selected element,
$().text('string') | replaces the text contents and returns this,
$().clone(deep) | clones the selected node if deep is false, clones node and childs if deep is true,
$().insertChildBefore(n, c) | inserts the child 'n' before the child 'c' and returns this,
$().removeChild(child) | removes the child 'child' and returns this,
$().replaceChild(n, c) | replaces the child 'c' by the child 'n' and returns this,
$().children() | returns a DOM object with all the node children,
$().childIndex() | returns the child index (0 for the first child),
$().getRect() | returns the position and size of the node,
$().css(style) | returns the style value,
$().css(style, value) | sets the style value and returns this,
$().getClassList() | returns a DOMTokenList (getClassList() is a wrapper around classList),
$().addClass('className') | adds 'className' to the selected element and returns this,
$().addClasses([...]) | adds an array of classes and returns this,
$().removeClass('className') | removes 'className' from the selected element and returns this,
$().removeClasses([...]) | removes an array of classes and returns this,
$().toggleClass('className') | adds or removes 'className' to/from the selected element and returns this,
$().hasClass('class') | returns true if the node has the class 'class' or false if not,
$().attr(attribute) | returns the attribute value of the selected element,
$().attr(attribute, value) | sets the attribute of the selected element,
$().removeAttr(attribute) | removes the attribute from the selected element,
$().animate(props, d, e, cb) | changes dynamically the CSS attributes,
$(el).on(event, listener) | adds an event listener to the selected child and returns this.
$(el).off(event, listener) | removes the attached event listener from the selected child and returns this.
¹ after, before and replacewith could only apply to a child element and not to the Component itself,
Vizu
implements the method render
to insert a view in the DOM tree:
const view = Vizu.render(view, reference, el);
Vizu.render()
requires one mandatory argument and two optional arguments:
view
: the first argument is the view to render. It is a string that contains a set of HTML tags defining the object to visualize. It can contain custom tags definingVizu Web Components
.
A Vizu Web Component
tag is defined as <NameOfVizuWebComponent />
.
reference
: the second argument is a Javascript object that links theVizu Web Component
tag to the class defining it.
// Example:
{ '<NameOfVizuWebComponent />': NameOfVizuWebComponent }
If this argument is omitted, the Vizu Web Component
tag is not interpreted.
el
: the third argument is the element in the DOM tree where the view is inserted. If it is omitted, the view is directly inserted in thebody
as the first node.
Vizu.render()
returns the view object. This object allows the user to interact with the Vizu Web Components
defining the view
. The view object looks like:
{ 'NameOf1stVizuWebComponent': {...}, 'NameOf2ndVizuWebComponent': {...}, etc. }
The view
object gives the list of the first level Vizu Web Components
objects that compose the view.
The Vizu Web Component
object gives access to three variables:
id
{string}: the id of thediv
tag that surrounds theVizu Web Component
,
-
cList
{Object}: the list of theVizu Web Component
tags that are included in thisVizu Web Component
, -
components
{Object}: theVizu Web Component
objects that are included in thisVizu Web Component
object,
// Example for the `Aaa` Vizu Web Component child of view:
const id = view.Aaa.id;
// Example for the `Bbb` Vizu Web Component child of `Aaa` Vizu Web Component:
const id = view.Aaa.components.Bbb.id;
// Example for `Ccc` child of `Bbb`:
const id = view.Aaa.components.Bbb.components.Ccc.id;
The Vizu Web Component
object gives access to the user defined methods:
// Example for the `Aaa` Vizu Web Component child of view:
view.Aaa.updateTitle('New Title');
// Example for the `Bbb` Vizu Web Component child of `Aaa` Vizu Web Component:
view.Aaa.components.Bbb.updateTitle('New Title');
// Example for `Ccc` child of `Bbb`:
view.Aaa.components.Bbb.components.Ccc.updateTitle('New Title');
Vizu
implements the method replace
to replace a Vizu Web Component
in the DOM tree:
Vizu.replace(view, newwebcomponent);
view
is the object returned by Vizu.render
.
newwebcomponent
is an object whose property is the tag of the Vizu Web Component
to replace and the value is the reference to the new Vizu Web Component
(the class).
Example:
{ `<Aaa />`: Bbb }
It means: I want to replace the Vizu Web Component
linked to the tag <Aaa />
by the Vizu Web Component
referenced by Bbb
(the class Bbb).
Vizu
implements the method createClass
to create a Vizu Web Component
without ES6 classes.
Vizu.createClass({
getInitialState: function() {
},
render: function() {
}
});
MIT.