simpel v0.6.1

✨ SimpEl ✨

A simple way to create and render HTML Elements.

Minimalistic, zero dependency, only 4KB, JavaScript UI library!

No but seriously, SimpEl provides a simple interface to create HTML Elements by defining Components. These can be created by either using JSX or vanilla JavaScript.

Only 2 methods are provided. One to create elements and one to render them.

Table of contents

• Why?
• When to use
• Requirements
• Install
• Syntax
• Interface Create Element Render
• SimpEl ❤️ JSX How to transform Caveats
• Examples + Vanilla JavaScript Create and render a list + JSX Render Components stored in a variable Render Functional Components Render dynamically created Components Bind an event listener to a Component Use refs to reference other Components

Why?

Because why reinvent the wheel right? Well, I needed a very, very simple wheel and I really like React and JSX..

When to use

This library should only be used if you need to create almost static HTML pages with non complex UX.

If you need something more powerful, then I recommend you have a look at the amazing React library. The SimpEl API is heavily inspired by it, because React is awesome.

Requirements

You need Node version 4 or greater.

Install

npm i -S simpel

Syntax

import Simpel from 'simpel';

const div = Simpel.createElement('div', null, 'Hello World!');

Simpel.render(
	div,
	document.getElementById('root')
);

Interface

The following methods are provided:

createElement(type, props, children)

Creates an HTML Element.

Arguments

Returns

HTML Element.

render(element, container)

Renders an HTML Element into the DOM in the supplied container.

Arguments

Returns

Void.

SimpEl ❤️ JSX

You can use JSX to create SimpEl components. But to do so you need to transform it to SimpEl function calls.

This means the following:

import Simpel from 'simpel';

const profile = <div>
	<img src="avatar.png" class="profile" />

	<h3>
		{
			[ user.firstName, user.lastName ].join(' ')
		}
	</h3>
</div>;

Needs to be transformed into:

import Simpel from 'simpel';

const profile = Simpel.createElement(
	'div',
	null,
	Simpel.createElement(
		'img',
		{ src: 'avatar.png', className: 'profile' }
	),
	Simpel.createElement(
		'h3',
		null,
		[ user.firstName, user.lastName ].join(' ')
	)
);

This can be done with the Babel React JSX Transform Plugin.

How to transform

First install the transform plugin:

npm i -D babel-plugin-transform-react-jsx

Then configure the plugin in your .babelrc file:

{
	"plugins": [
		[
			"transform-react-jsx",
			{
				"pragma": "Simpel.createElement"
			}
		]
	]
}

Note that you need to change the pragma to Simpel.createElement.

Caveats

Always make sure to have the SimpEl library in scope when defining JSX Components. If omitted, the transformed JSX will not be able to execute:

import Simpel from 'simpel';

export default Label = <span>Hi</span>;

Examples

• Vanilla JavaScript * Create and render a list
• JSX Render Components stored in a variable Render Functional Components Render dynamically created Components Bind an event listener to a Component * Use refs to reference other Components

Create and render a list

/**
 * We will render the following HTML:
 *
 * <div id="root">
 *     <ul class="list">
 *         <li class="list-item">milk</li>
 *         <li class="list-item">eggs</li>
 *         <li class="list-item">bread</li>
 *         <li class="list-item">cheese</li>
 *     </ul>
 * </div>
 */

'use strict';

const Simpel = require('simpel');

const List = Simpel.createElement(
	'ul',
	{ 'class': 'list' },
	Simpel.createElement(
		'li',
		{ 'class': 'list-item' },
		'milk'
	),
	Simpel.createElement(
		'li',
		{ 'class': 'list-item' },
		'eggs'
	),
	Simpel.createElement(
		'li',
		{ 'class': 'list-item' },
		'bread'
	),
	Simpel.createElement(
		'li',
		{ 'class': 'list-item' },
		'cheese'
	)
);

Simpel.render(
	List,
	document.getElementById('root')
);

Render Components stored in a variable

import Simpel from 'simpel';

const Story = (
	<div id="story">
		<p class="story-text">Once upon a time..</p>
	</div>
);

Simpel.render(
	<Story />, // You can also reference `Story`, i.e. non JSX.
	document.getElementById('root')
);

Render Functional Components

import Simpel from 'simpel';

const User = props => <span>My name is { props.name }</span>;

Simpel.render(
	<User name="Daniel Illouz" />,
	document.getElementById('root')
);

Render dynamically created Components

import Simpel from 'simpel';

const Groceries = ({ groceries }) => (
	<ul class="list">
		{
			groceries.map(
				item => <li class="list-item">{ item }</li>
			)
		}
	</ul>
);

Simpel.render(
	<Groceries
		groceries={ [ 'milk', 'eggs', 'bread', 'cheese' ] }
	/>,
	document.getElementById('root')
);

Bind an event listener to a Component

import Simpel from 'simpel';

function _showAlert() {
	alert('Hello!');
}

const Alert = <button onClick={ _showAlert }>alert</button>;

Simpel.render(
	<Alert />, // You can also use JSX, i.e. `<Alert />`.
	document.getElementById('root')
);

The following events are supported:

Use refs to reference other Components

import Simpel from 'simpel';

let n = 0;

function _addItem(e) {
	e.preventDefault();

	// `SimpEl` returns HTML Elements so you can use
	// all API methods like `appendChild`.
	this.refs.list.appendChild(
		<li>item { n++ }</li>
	);
}

const Widget = () => (
	<div>
		<ul ref="list" />

		<button onClick={ _addItem }>
			add
		</button>
	</div>
);

Simpel.render(
	<Widget />,
	document.getElementById('root')
);

License

Apache 2.0 © Daniël Illouz