npm install seviewA simple way of writing views with s-expressions,
and meant to be used with a virtual DOM library.
Because plain JavaScript is simpler to write and build than JSX or HTML string literals, and it's
great to write views in a way that is independent of the virtual DOM library being used. It's also
nice to use convenient features even if the underlying virtual DOM library does not support them.
Instead of writing this in JSX:
``jsx`
Enter your name:
{isMessage && {message}}
Or even this in hyperscript:
`js`
h('div', { id: 'home' }, [
h('span', { className: 'instruction' }, 'Enter your name:'),
h('input', { type: 'text', id: 'username', name: 'username', size: 10 }),
isMessage && h('div', { className: 'message' + (isError ? ' error' : '') }, message)
])
You can write this with seview:
`js`
['div#home',
['span.instruction', 'Enter your name:'],
['input:text#username[name=username][size=10]'],
isMessage && ['div.message', { class: { 'error': isError } }, message]
]
Besides the conveniences of the syntax, you also don't have to write h at every element. To
switch from one virtual DOM library to another, you only need to make changes in one place.
All your view code can remain the same.
If you are using the Meiosis pattern, seview is a great way to further
decouple your code from specific libraries. Your views become independent of the underlying
virtual DOM library API.
Using Node.js:
`
npm i seview
With a script tag:
`html`
Out of the box, seview supports 3 view libraries:
Using a different library is not difficult. See
Using a different view library.
When using seview with built-in support, we assume writing views with the following attributes:
- class for the HTML class attribute - converted to className for Reactfor
- for the HTML for attribute - converted to htmlFor for ReactinnerHTML
- for using unescaped HTML - converted appropriately for React, Preact, and MithrilonClick
- , onChange, etc. for DOM events - converted to lowercase for Mithril
> By writing views with the conventions above, you can switch between React, Preact, or Mithril
without changing any of your view code! You can see this in action in the
Meiosis Realworld Example,
where switching can be achieving just by editing
one file.
To use seview with React:
`js
import { h } from 'seview/react';
import { createRoot } from 'react-dom/client';
const rootView = (...) =>
['div.container',
[...]
];
const root = createRoot(document.getElementById('app'));
root.render(h(rootView(...)));
`
> Click here for a live example: seview + React
To use seview with Preact:
`js
import { h } from 'seview/preact';
import { render } from 'preact';
const rootView = (...) =>
['div.container',
[...]
];
const element = document.getElementById('app');
render(h(rootView(...)), element);
`
> Click here for a live example: seview + Preact
To use seview with Mithril:
`js
import { h } from 'seview/mithril';
import m from 'mithril';
const rootView = (...) =>
['div.container',
[...]
];
m.mount(document.getElementById('app'), {
view: () => h(rootView(...))
});
`
> Click here for a live example: seview + Mithril
seview supports CSS-style selectors in tag names, { class: boolean } for toggling classes, using
an array or varags for children, flattening of nested arrays, and removal of null/empty elements.
An element is an array:
`
[tag, attrs, children]
or a string (text node):
`
'this is a text node'
The tag can be a string, or something that your virtual DOM library understands; for example,Component
a in React. For the latter, seview just returns the selector as-is.
When the tag is a string, it is assumed to be a tag name, possibly with CSS-style selectors:
- 'div', 'span', 'h1', 'input', etc.'div.highlighted'
- , 'button.btn.btn-default' for classes'div#home'
- for id
- for . There can only be one type, so additional types are'input:password:text'
ignored. would result in .'input[name=username][required]'
- results in
- if you need spaces, just use them:
- default tag is , so you can write '', '.highlighted', '#home', etc.'input:password#duck.quack.yellow[name=pwd][required]'
- these features can all be used together, for example
results in
If the second item is an object, it is considered to be the attributes for the element.
Of course, for everything that you can do with a CSS-style selector in a tag as shown in the
previous section, you can also use attributes:
`js`
['input', { type: 'password', name: 'password', placeholder: 'Enter your password here' }]
You can also mix selectors and attributes. If you specify something in both places, the attribute
overwrites the selector.
`js`
['input:password[name=password]', { placeholder: 'Enter your password here' }]html`
`js`
['input:password[name=username]', { type: 'text', placeholder: 'Enter your username here' }]html`
Classes can be specified in the tag as a selector (as shown above), and/or in attributes using
class:
`js`
['button.btn.info', { class: 'btn-default special' }]html`
If you specify an object instead of a string for class, the keys are classes and the values
indicate whether or not to include the class. The class is only included if the value is truthy.
`js`
// isDefault is true
// isError is false
['button.btn', { class: { 'btn-default': isDefault, 'error': isError } }]html`
The last item(s), (starting with the second if there are no attributes, and starting with the
third if attributes are present), are the children. The children can be:
- an array, or
- varargs.
#### Using an array
You can specify children as an array:
`js`
['div', [
['span', ['Hello']],
['b', ['World']]
]html`
Hello
World
#### Using varargs
You can specify children as varargs:
`js`
['div',
['span', 'Hello'],
['b', 'World']
]html`
Hello
World
The problem with supporting varargs is, how do you differentiate a single element from two text nodes?
For example:
`js`
['div', ['b', 'hello']]
vs
`js`
['div', ['hello', 'there']]
For the second case, varargs must be used:
`js`
['div', 'hello', 'there']
Whether using an array of children or varargs, nested arrays are automatically flattened:
`js`
['div', [
['div', 'one'],
[
['div', 'two'],
[
['div', 'three']
]
]
]]
or
`js`
['div',
['div', 'one'],
[
['div', 'two'],
[
['div', 'three']
]
]
]
Both result in
`html`
one
two
three
The following elements are ignored and not included in the output:
- undefined
-
-
-
-
This makes it simple to conditionally include an element by writing:
`js`
condition && ['div', 'message']
If condition is falsy, the div will not be included in the output. Because it is completelyfalse
excluded, this will work even if the virtual DOM library that you are using does not handle, null, or undefined.
The following elements will be converted to a string:
- true
- numbers
-
-
seview exports a single function, seview, that you use to create an h function that works withh(view)
the view library of your choice. Calling , where view is the view expressed as arrays as
we have seen above, produces the final result suitable for your view library.
To set up your view library, call seview and pass it a function that gets called for every node in
the view. Each node has the following structure:
`js`
{
tag: 'button',
attrs: { id: 'save', class: 'btn btn-default', ... }
children: [ ... ]
}
The function that you write needs to convert the structure above to what is expected by the view
library that you are using. Note that your function will also be called for each element in
children.
`js
import { seview } from 'seview';
import { myViewLibrary } from 'my-view-library';
export const h = seview((node) => {
const tag = processTagAsNecessary(node.tag);
const attrs = processAttrsAsNecessary(node.tag);
return myViewLibrary(tag, attrs, node.children || []);
});
`
Then you can use h with your view library in a similar way as we saw in the Usage
section.
seview` is inspired by the following. Credit goes to the authors and their communities - thank you
for your excellent work!
- How to UI in 2018
- ijk
- JSnoX
- Mithril
- domvm
----
_seview is developed by foxdonut
(@foxdonut00) and is released under the MIT license._