https://github.com/mrolafsson/telemark
Super-lightweight templating and generation of HTML (and other markup) with plain JavaScript. Works in the browser and Node.js.
https://github.com/mrolafsson/telemark
html javascript js markup markup-builder templating
Last synced: 3 months ago
JSON representation
Super-lightweight templating and generation of HTML (and other markup) with plain JavaScript. Works in the browser and Node.js.
- Host: GitHub
- URL: https://github.com/mrolafsson/telemark
- Owner: mrolafsson
- License: apache-2.0
- Created: 2017-07-26T03:14:37.000Z (almost 9 years ago)
- Default Branch: master
- Last Pushed: 2018-07-09T19:08:24.000Z (almost 8 years ago)
- Last Synced: 2025-10-21T11:53:42.615Z (8 months ago)
- Topics: html, javascript, js, markup, markup-builder, templating
- Language: JavaScript
- Homepage: https://www.npmjs.com/package/telemark
- Size: 469 KB
- Stars: 1
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
[](https://travis-ci.org/mrolafsson/telemark)
[](https://npm.runkit.com/telemark)
# Telemark
##### Super-lightweight, minimalist templating and generation of HTML (and other markup) with plain JavaScript. Works in the browser and Node.js.
## Getting started
Download or install with: `npm install telemark`.
To keep things as compact as possible you can use the library with or without the built-in support for HTML.
```html
```
or get both in one call:
```html
```
Getting started is super simple, let's say you want to create HTML you start with the `Telemark.Html()` one:
```javascript
Html.init(window);
ol( $class("beautiful"),
li("Foo"),
li("Bar")
).make();
```
This initialiser will add all the helper methods like `ol()`, and `li()` in this case to the global namespace and when you call `make()` generate the following HTML:
```html
- Foo
- Bar
```
If you want to generate and insert the markup into a particular DOM element, use the `into()` method.
In this case the `ol` and its child elements would be placed in the body of the element with the id: `some_id`.
```
ol( $class("beautiful"),
li("Foo"),
li("Bar")
).into("#some_id");
```
Note, you can also use `require()` where the equivalent would be:
```javascript
var markup = require("telemark/dist/telemark-html.min.js");
markup.html.init(window);
```
> Check out this [code example](https://runkit.com/mrolafsson/telemark-with-express-js) generating [HTML](https://telemark-with-express-js-0f6jnafj3umz.runkit.sh) server-side with [Express.js](http://expressjs.com)!
#### `text()`
For strings you're adding to the body of any element you can either refer to it directly (e.g. `li("foo")`) or wrap it in `text()`. You might want to do that when adding multiple text elements or to make use of utility functions like `join(separator)`:
```javascript
li( text("The", "quick", "brown", "fox").join(" ") );
```
### Iteration
Did I hear you say loop? Well, golly gosh what a coincidence. This is how you'd generate markup using the built-in `iterate()` method:
```javascript
Html.init(window);
var marx_brothers = ['Groucho', 'Harpo', 'Chico', 'Gummo', 'Zeppo'];
ol( $class('marx'),
iterate(marx_brothers, function (bro) {
return li( $class(bro), bro );
})
).make()
```
In this example you specify the sub-elements you need per entry using an anonymous function. This means that you have full control over the handling of each element in the collection.
You can also do object iteration:
```javascript
var obj = { Perch: 'Embiotocidae', Pike: 'Ptychocheilus grandis', Yellowtail: 'Seriola dorsalis'};
ol(
iterate(obj, function (value, key) {
return li( text(key), text(': '), i(value) );
})
).make()
```
Note that the first argument passed to the function is the value, resulting in the following HTML in this case:
```html
- Perch: Embiotocidae
- Pike: Ptychocheilus grandis
- Yellowtail: Seriola dorsalis
```
>You can pass into each function any number of elements, and attributes and the library will construct the right markup. Note that if you pass in a simple string it will be used for the body of the element.
### Conditional logic
You can wrap any attributes or elements in a `when( some_expression, ... )`. Only when the first argument evaluates to `true` will the rest of the parameters be executed:
```javascript
ul(
li( when(false, draggable(false)),
'Ferris'
),
li( when(true, draggable(true)),
'Cameron'
),
when( false,
li('Rooney')
),
li( when(false, draggable(false)),
'Sloane'
)
)
```
This applies to both attributes and elements as this example shows:
```html
- Ferris
- Cameron
- Sloane
```
In this case, principal Rooney is not added to the list, and only Cameron is draggable.
## Reusable components
You can specify and register your own components that encapsulate logic and return a particular structure:
```javascript
Telemark.specify('telephone', function (name, number) {
return a( href('tel:' + number), $class('phone-number'), text(name) );
});
```
You can then use these like any other element except that you pass in the parameters you specified:
```javascript
ol(
li(
telephone( 'Ghostbusters', '+1-800-555-2368' )
)
)
```
This would add your component with the specified properties, resulting in this case in the following HTML:
```html
```
### Component nesting
If you need components to be able to nest other components you can use the following pattern to define them:
```javascript
Telemark.specify('brothers', function (collection_of_brothers, nested) {
return section(
ol( $class('brothers'),
iterate(collection_of_brothers, function (a_name) {
return nested(a_name);
})
)
);
});
Telemark.specify('brother', function (a_name) {
return li( $class('brother'),
text(a_name)
);
});
```
You can then use them like this:
```javascript
var marx_brothers = ['Groucho', 'Harpo', 'Chico', 'Gummo', 'Zeppo'];
brothers(marx_brothers, function (name) {
return brother(name);
}).make()
```
### Building in stages
You don't have to create the markup using one fluent sequence. You can do this in stages and work with the elements at each stage, `append`/`prepend` elements, `set` attributes etc.
```javascript
var brothers = ol( $class('marx') );
var harpo = li('Harpo');
harpo.set( draggable(true) );
brothers.append(harpo);
brothers.prepend( li('Groucho') );
brothers.append( li('Chico') );
brothers.make();
```
...will somewhat predictably generate:
```html
- Groucho
- Harpo
- Chico
```
### Markup methods
#### `make()`
Generates and returns the markup as a string.
#### `into("query_selector", [element, default: document])`
Generates and inserts the markup into either the `document` or an element specified for the given [query selector](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector).
The example below would place the `
- ` and its child elements in the body of the first element with the class `i_have_class`.
```
ol( $class("beautiful"),
li("Foo"),
li("Bar")
).into(".i_have_class");
```
#### Other functions for manipulating markup
##### `append( some_telemark_expression )`
Append some markup based on a Telemark expression to the element. You do not need to invoke `make()` for the expression you're appending.
##### `prepend( some_telemark_expression )`
Prepend some markup based on a Telemark expression to the element. You do not need to invoke `make()` for the expression you're prepending.
##### `set( some_telemark_attribute )`
Set a particular attribute on the element in question. This returns a reference to the element so you can chain this and other expressions.
## Generating markup using your own element specification
In this case you don't start with `Telemark.Html()` but the core object `Telemark()`. You can pass in your own array of element names which will be turned into helper methods. You can either have these added to the global namespace like this:
```javascript
Telemark.init(['foo', 'bar'], window);
// var markup = require('telemark);
// markup.init(['foo', 'bar'], window);
var my_foo = foo(
bar('One'),
bar('Two')
).make();
```
...will return:
```xml
One
Two
```
Namespace prefixes are supported but the `:` needs to be replaced with an object dot notation to be a valid identifier:
```javascript
Telemark.init(['movie:science-fiction'], window);
movie.science_fiction().make();
```
...will return:
```xml
```
>We try and deal with special characters in element/attribute names e.g. replacing `-` with `_`:
You can use your own holder to keep the global namespace nice and tidy:
```javascript
var _ = Telemark.init(['foo', 'bar']);
_.foo(
_.bar('One'),
_.bar('Two')
).make();
```
For HTML plugin you would use the same methodology:
```javascript
var _ = Html.init();
```
If you also want to specify helpers for attributes you can do that:
```javascript
var namespace = {
elements: ['animals', 'cat', 'dog'],
attributes: ['sound', 'leash']
};
Telemark.init(namespace, window);
animals(
dog( sound('woof'), 'Benji' ),
cat( sound('meow'), leash('no'), 'Garfield' )
)
```
Output:
```xml
Benji
Garfield
```
You can add any element, regardless of what helper methods you specified using the `el()` function:
```javascript
Telemark.init([], window);
el('foo',
el('bar', attr('name', 'thirst'),
'First'
),
el('bar',
'Second'
),
el('bar',
el('zip',
'Third'
)
)
)
```
...which would conjure up this stirring bit of exemel poetry:
```xml
First
Second
Third
```
## Bonus Points: Generating JsDoc to suppress IDE warnings
You can use `Telemark.JsDoc` plugin to generate JsDoc snippets to suppress any warnings the IDE may give you for the helper methods:
```
var funcs = new JsDoc();
var namespace = {
elements: ['animals:domestic', 'cat', 'dog'],
attributes: ['sound', 'leash']
};
Telemark.init(namespace, funcs);
console.log(funcs.create_jsdoc());
```
Then copy/paste the snippets into your JS codebase:
```
/**@name iterate*/
/**@name when*/
/**@name attr*/
/**@name el*/
/**@name animals*/
/**@namespace animals*/
/**@name domestic*/
/**@name cat*/
/**@name dog*/
/**@name sound*/
/**@name leash*/
```