Lighweight reactive library with templating and data binding.
npm install vouivre
npm install vouivre
`
and import in your project using a bundler like webpack or vite
`javascript
import vouivre from "vouivre"
`
Or you can grab the release on github and use it in a script tag directly.
`html
`
Usage
$3
The templating syntax allows you to bind your HTML DOM elements to an object of data in javascript. The template uses different attributes prefixed with v- or text wrapped in brackets { ... } (aka text interpolation).
`html
{ author.firstName } { author.lastName }
`
`js
vouivre.bind(document.body, {
author: {
firstName: "John",
lastName: "Doe",
link: "/authors/john-doe/"
}
});
`
Vouivre binds HTML elements to the model's property and observes modifications using a Proxy. When a property is modified in the model, only the corresponding bindings are updated, ensuring minimal DOM manipulations and maximum performance.
You can use multiple models bound to different parts of your HTML, in this example we use a single model bound to document.body.
$3
The on directive is used to bind event to an element.
`html
{ count }
`
`js
const model = vouivre.bind(document.body, {
count: 0,
addOne() {
model.count++;
}
});
`
$3
The foreach directive is a special one, usable only on template elements. It creates a scope for each iterated item. The name of the scope variable is the parameter of the directive v-foreach-*. Children elements can access this bound variable as well as a special variable $index.
`html
-
{ $index }
{ person.name }
`
Foreach supports all array operations, from adding and removing items to reordering the whole array. Moving elements in the array will just move HTML elements to match the new order with moveBefore, keeping the state of the node.
`js
const model = vouivre.bind(document.body, {
persons: [
{
name: "Kira"
},
{
name: "Wellan"
}
],
remove(event, scope) {
persons.splice(scope.$index, 1);
}
});
`
Event listeners receive a scope object as a second argument, with all the scoped variables, the index $index and the parent scope $parent.
$3
The binding directive allows you to create a bidirectional bind between the model value and an input element. This means that the model is updated when the user interacts with the form inputs, and the inputs are updated when the model is modified.
`html
`
`js
vouivre.bind(document.body, {
author: {
firstName: "Alban"
age: 20,
},
options: ["France", "Italie", "Allemagne", "Suisse"],
selectedOptions: [] // {} and new Set() are also supported
})
`
Built-in Directives
The asterisk * denotes a directive that receives an argument.
v-foreach-* creates one instance of the template foreach item in the array. Each instance has access to the array item using the variable name you pass as argument.
v-text sets the element text the same way as text interpolation does.
v-show changes the display of the element using css.
v-if adds or removes the element from the DOM depending on the value.
v-enabled enables or disables the element (for example a button).
v-on-* binds a function of the model to the event you pass as argument.
v-class-* adds or removes a css class.
v-attr-* adds or removes an HTML attribute.
v-prop-* sets the value of a property on the element.
v-* sets the value of an HTML attribute.
Modifiers
Modifiers are used to alter the value of a binding. They can format the value as time or percentage, or add simple logic like inverting a value with not or comparing with is. Modifiers are applied after the property path delimited by :. First comes the modifier name, and then a list of parameters if needed. You can also chain modifiers.
`html
public
`js
vouivre.bind(document.body, { isPrivate: true, now: Date.now(), status: "connected" });
`
Parameters of the modifier can be model properties, scope variables or primitives (string, number etc.). Properties will automatically be resolved and put in the watch list as a dependency of the binding, so that it updates when the value changes.
`html
Built-in Modifiers
watch [property1] [property2] ... adds model properties to the list of dependencies to watch.
not inverts the value.
is [propertyOrValue] compares the value to the value of a model property or a primitive value.
args [arg1] [arg2] ... add arguments that will be passed to the event listeners bound with on-*.
call [arg1] [arg2] ... calls a function with the list of arguments.
get [prop] returns the property 'prop' of the object. Usually used when 'prop' is a variable name of a property of the object.
Computed properties
`html
`
`js
vouivre.bind(document.body, {
firstName: "John",
lastName: "Doe",
get fullname() {
return this.firstName + " " + this.lastName;
},
fullname_dependencies: ["firstName", "lastName"]
});
`
You can tell the binding what are the dependencies of this computed property with an array with the same name as the getter + _dependencies. Or if you prefer you can use the watch modifier directly in the attribute.
Custom directives
You can add your own custom directives to vouivre before binding the model to your view.
`js
vouivre.directives["color"] = {
bind(element, value) {
// called once before any update
// can be used to register event listeners
},
unbind(element, value) {
// unregister things
}
update(element, value) {
// called on every watched properties value change
element.style.color = value;
// can call your own functions
this.extra.myFunction();
},
// optional extra data and functions
extra: {
myFunction() {
}
},
};
`
All hooks are optional. Another example, this time with an argument passed to the directive.
`js
vouivre.directives["on-*"] = {
bind: function (el, value) {
el.addEventListener(this.args[0], (e) => value(e));
},
}
`
Custom modifiers
Modifiers work almost the same as directives, all hooks are optional, and the binding is accessible via this.binding.
This example uses another feature, the ability to watch changes on all properties of an object by adding * to the object path array.
`js
vouivre.modifiers["toString"] = {
bind(value) {
this.binding.watch([...this._path, "*"]);
},
unbind(value) {
},
read(value) {
if (value instanceof Object) {
return JSON.stringify(value);
}
return value.toString();
},
write(value) {
return value;
}
};
vouivre.bind(document.body, { author: { firstName: "John", lastName: "Doe" } });
`
`html
`
Advanced example
In this example we render a list of persons in a table with an input text to filter the entries and buttons on each column to sort the list in ascending or descending order by this column field. The table body is filled by two imbricated foreach, one iterating the list and the other iterating the columns we chose to render.
`html
Pos
{ column }
class="sort-btn"
v-attr-disabled="isCurrentSort :call sortColumn column sortOrder desc"
v-on-click="sort :args column desc"
>
â > class="sort-btn"
v-attr-disabled="isCurrentSort :call sortColumn column sortOrder asc"
v-on-click="sort :args column asc"
>
â
{ $index }
{ person :get field }
`
`js
vouivre.bind(document.body, {
persons: [
{
firstName: "Merwyn",
lastName: "Ril' Avalon",
},
{
firstName: "Edwin",
lastName: "Til' Illan",
},
{
firstName: "Ewilan",
lastName: "Gil' Sayan",
},
{
firstName: "Duom",
lastName: "Nil' Erg",
},
{
firstName: "Bjorn",
lastName: "Wil' Wayard",
},
],
columns: ["firstName", "lastName"],
sortColumn: undefined,
sortOrder: "desc",
sort(e, scope, key, order) {
model.persons.sort((a, b) => (order == "desc" ? 1 : -1) * a[key].localeCompare(b[key]));
model.sortColumn = key;
model.sortOrder = order;
},
isCurrentSort(currentKey, key, currentOrder, order) {
return currentKey == key && currentOrder == order;
},
filterName: "",
get filteredPersons() {
if (this.filterName == "") return this.persons;
return this.persons.filter((p) =>
p.firstName.startsWith(this.filterName) || p.lastName.startsWith(this.filterName));
},
filteredPersons_dependencies: ["filterName", "persons"]
});
``