Skip to content

Commit

Permalink
Update documentation and example HTML file
Browse files Browse the repository at this point in the history
  • Loading branch information
@jgarber623
jgarber623 committed Mar 27, 2018
1 parent 13af84c commit b15daa5
Show file tree
Hide file tree
Showing 2 changed files with 206 additions and 33 deletions.
182 changes: 181 additions & 1 deletion README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -5,9 +5,189 @@
[![npm](https://img.shields.io/npm/v/@jgarber/templatetemplate.svg?style=for-the-badge)](https://www.npmjs.com/package/@jgarber/templatetemplate)
[![Downloads](https://img.shields.io/npm/dt/@jgarber/templatetemplate.svg?style=for-the-badge)](https://www.npmjs.com/package/@jgarber/templatetemplate)

### Key Features

- Uses established Web standards (e.g. `<template>`, `document.querySelector`)
- Dependency-free

TemplateTemplate is also really tiny:

<table>
<tbody>
<tr>
<th>Uncompressed</th>
<td>1,252 bytes</td>
</tr>
<tr>
<th>Minified</th>
<td>767 bytes</td>
</tr>
<tr>
<th>Minified and gzipped</th>
<td>446 bytes</td>
</tr>
</tbody>
</table>

## Getting TemplateTemplate

You've got a couple options for adding TemplateTemplate to your project:

- [Download a tagged version](https://github.com/jgarber623/TemplateTemplate/tags) from GitHub and do it yourself (old school).
- Install using [npm](https://www.npmjs.com/package/@jgarber/templatetemplate): `npm install @jgarber/templatetemplate`
- Install using [Yarn](https://yarnpkg.com/en/package/routerrouter): `yarn add @jgarber/templatetemplate`

## Usage

See [![Examples](https://github.com/jgarber623/TemplateTemplate/tree/master/example)]
TemplateTemplate takes two arguments: a reference to a `<template>` element and a hash of `insertions` defining the content to insert into the `<template>`.

### Basic

A basic example, inserting a row into a `<table>`:

```html
<table id="projects">
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Author</th>
<th scope="col">URL</th>
<th scope="col">Languages</th>
</tr>
</thead>
<tbody></tbody>
</table>

<template id="row-template">
<tr>
<th class="name" scope="row"></th>
<td class="author"></td>
<td class="url"></td>
<td class="languages"></td>
</tr>
</template>

<script>
var tbody = document.querySelector('#projects tbody');
var emptyTemplate = document.querySelector('#row-template');
var insertions = {
'.name': 'TemplateTemplate',
'.author': 'Jason Garber',
'.url': 'https://github.com/jgarber623/TemplateTemplate',
'.languages': 'JavaScript'
};
var renderedTemplate = TemplateTemplate(emptyTemplate, insertions);
tbody.appendChild(renderedTemplate);
</script>
```

In the example above, a reference to the `<template>` element is passed to TemplateTemplate using [`document.querySelector`](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector). The `insertions` hash is a map of key/value pairs where the key (e.g. `'.name'`) is a valid [CSS selector](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_Selectors) and the `value` (e.g. `'TemplateTemplate'`) is a string of text to insert into the selected node.

### Advanced

A more complex example, inserting a row into a `<table>` with different types of insertions.

```html
<table id="projects">
<thead>
<tr>
<th scope="col">Name</th>
<th scope="col">Author</th>
<th scope="col">URL</th>
<th scope="col">Languages</th>
</tr>
</thead>
<tbody></tbody>
</table>

<template id="row-template">
<tr>
<th class="name" scope="row"></th>
<td class="author"></td>
<td class="url"></td>
<td class="languages"></td>
</tr>
</template>

<template id="anchor-template">
<a></a>
</template>

<script>
var tbody = document.querySelector('#projects tbody');
var anchor = document.createElement('a');
anchor.setAttribute('href', 'https://sixtwothree.org');
anchor.textContent = 'Jason Garber';
tbody.appendChild(
TemplateTemplate('#row-template', {
'th': 'CashCash',
'th + td': anchor,
'.url': ['github.com/jgarber623/CashCash', {
'style': 'font-weight: bold;'
}],
'td:last-child': TemplateTemplate('#anchor-template', {
'a': ['JavaScript', {
'href': 'https://github.com/search?q=language%3AJavaScript',
'target': '_blank'
}]
})
})
);
</script>
```

The example above demonstrates a handful of additional features that you may find useful. Let's break it down with a commented version of the most interesting bits:

```js
// The first argument to TemplateTemplate may also be a valid CSS selector.
TemplateTemplate('#row-template', {
'th': 'CashCash',
// TemplateTemplate will use `appendChild` when given an instance of
// a `DocumentFragment` or an `HTMLElement`.
'th + td': anchor,
// When an array is passed as a value, TemplateTemplate will use the
// first index in the array as the `textContent` for the node. The
// second index is a hash of key/value pairs which are added to the
// node as HTML attributes.
'.url': ['github.com/jgarber623/CashCash', {
'style': 'font-weight: bold;'
}],
// TemplateTemplate may also be used to generate content from another
// `<template>` and reuse it on the fly!
'td:last-child': TemplateTemplate('#anchor-template', {
'a': ['JavaScript', {
'href': 'https://github.com/search?q=language%3AJavaScript',
'target': '_blank'
}]
})
})
```

## Browser Support

TemplateTemplate works in all modern browsers. The library makes use of several new(ish) JavaScript features, including:

- `document.querySelector` ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/querySelector))
- `document.importNode` ([MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/importNode))
- `Object.entries` ([MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/entries))
- `Array.prototype.forEach()` ([MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Array/forEach))

Support for `document.querySelector` first appeared in Internet Explorer in version 8. To avoid throwing JavaScript errors in browsers that don't support this method, you can [cut the mustard](http://responsivenews.co.uk/post/18948466399/cutting-the-mustard):

```js
if (document.querySelector) {
// Your scripts here…
}
```

TemplateTemplate, in an effort to remain as lightweight and dependency-free as possible, leaves it up to you to choose whether or not to polyfill features for older browsers.

## Acknowledgments

Expand Down
57 changes: 25 additions & 32 deletions example/index.html
View file
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@
</head>
<body>

<table id="projects-table">
<table id="projects">
<caption>A table of open source projects.</caption>
<thead>
<tr>
Expand All @@ -20,55 +20,48 @@
<tbody></tbody>
</table>

<template id="anchor-template">
<a></a>
</template>

<template id="project-template">
<template id="row-template">
<tr>
<th class="project-name" scope="row"></th>
<td class="project-author"></td>
<td class="project-url"></td>
<td class="project-languages"></td>
<th class="name" scope="row"></th>
<td class="author"></td>
<td class="url"></td>
<td class="languages"></td>
</tr>
</template>

<template id="anchor-template">
<a></a>
</template>

<script src="../src/templatetemplate.js"></script>
<script>
var tbody = document.querySelector('#projects-table tbody'),
anchor = document.createElement('a');

anchor.setAttribute('href', 'https://sixtwothree.org');
anchor.textContent = 'Jason Garber'
var tbody = document.querySelector('#projects tbody');

tbody.appendChild(
TemplateTemplate(document.querySelector('#project-template'), {
'.project-name': 'TemplateTemplate',
'.project-author': 'Jason Garber',
'.project-url': 'https://github.com/jgarber623/TemplateTemplate',
'.project-languages': 'JavaScript'
TemplateTemplate(document.querySelector('#row-template'), {
'.name': 'TemplateTemplate',
'.author': 'Jason Garber',
'.url': 'https://github.com/jgarber623/TemplateTemplate',
'.languages': 'JavaScript'
})
);

tbody.appendChild(
TemplateTemplate('#project-template', {
'th': 'RadioRadio',
'.project-author': anchor,
'td:nth-child(3)': 'https://github.com/jgarber623/RadioRadio',
'td:last-child': 'JavaScript'
})
);
var anchor = document.createElement('a');

anchor.setAttribute('href', 'https://sixtwothree.org');
anchor.textContent = 'Jason Garber';

tbody.appendChild(
TemplateTemplate('#project-template', {
TemplateTemplate('#row-template', {
'th': 'CashCash',
'.project-author': 'Jason Garber',
'.project-url': ['github.com/jgarber623/CashCash', {
'th + td': anchor,
'.url': ['github.com/jgarber623/CashCash', {
'style': 'font-weight: bold;'
}],
'td:last-child': TemplateTemplate('#anchor-template', {
'a': ['JavaScript', {
'href': 'https://github.com/search?q=language%3AJavaScript'
'href': 'https://github.com/search?q=language%3AJavaScript',
'target': '_blank'
}]
})
})
Expand Down

0 comments on commit b15daa5

Please sign in to comment.