Skip to content

Latest commit

 

History

History
286 lines (218 loc) · 10 KB

.verb.md

File metadata and controls

286 lines (218 loc) · 10 KB
Raw

{%= name %} {%= badge('npm') %} {%= badge('downloads') %} [![npm total downloads][downloads-img]][downloads-url]

Create HAST-compliant virtual dom trees of HTML using [hyperscript][] compatible syntax or JSX, just in ~570 bytes.

[![codeclimate][codeclimate-img]][codeclimate-url] codestyle [![linux build][travis-img]][travis-url] [![windows build][appveyor-img]][appveyor-url] [![codecov][coverage-img]][coverage-url] [![dependency status][david-img]][david-url]

You might also be interested in [hyperscript][] - a builder for real dom elements.

JSX CodePen Example

Highlights

  • Tiny: Very lightweight, ~600 bytes gzip + minify and the UMD wrapper.
  • Defaults: Sane defaults and tiny css selector parser.
  • Components: Can be used to create Stateless or Statefull Components.
  • Specificaition: Creates HAST-compliant AST trees.
  • Customization: Supports JSX, custom tags and attributes.
  • Minimalist: Really, just a builder of AST trees.
  • Compatibility: Same as [hyperscript][], but creates virtual DOM.
  • Friendly: Plays well with [browserify][] users.
  • Bundled: Available as ES6 Module, CommonJS, UMD.
  • SSR: Supports server-side rendering through [mich-to-html][].
  • Clean: Does not mess with DOM or anything.

Table of Contents

Install

Install with npm

$ npm install {%= name %} --save

or install using yarn

$ yarn add {%= name %}

Builds are also available on unpkg CDN, so iniclude

<script src="https://unpkg.com/mich-h/dist/mich-h.min.js"></script>

then access mich-h through the michH global property - notice the uppercased H letter.

<script>
  const h = michH
  const node = h('h1.hero#home.big', 'Hello World')

  console.log(node)
</script>

Try CodePen or JSBin Example

Usage

For more use-cases see the tests

const h = require('{%= name %}')

const ast = h('div#page.foo.bar.qux', { className: 'ok fool' },
  h('#header',
    h('h1.classy', 'hello', { style: 'background-color: #333; color: purple' })),
  h('nav#menu', { style: {'background': '#2f2', 'font-size': '12px' } },
    h('ul', [
      // notice `dataset` and `data-zaz`
      // both will be set to `properties.dataset`
      h('li', 'one', { dataset: { foo: 'bar', qux: 'ok' }, 'data-zaz': 'huh' }),
      h('li.sec', 'two', { className: ['huh'] }),
      h('li', { 'data-foo': 'hi' }, 'three')
    ])),
  h('h2#title', 'content title',  { style: {'background-color': 'red'} }),
  // notice `.first` and `className: 'foobie'`
  // both will be set in `properties.className` array 
  h('p.first',
    'so it is just like a templating engine,\n',
    { className: 'foobie' },
    'but easy to use inline with javascript',
    { onclick: () => {} }),
  h('p',
    { className: 'lastParagraph' },
    'the intention is for this to be used to create\n',
    h('strong', 'charlike', {
      className: ['bold'],
      style: 'background: white; color: green'
    }),
    ' reusable, interactive html widgets.'))

console.log(ast)

Or with modern JSX syntax, adding JSX Pragma somewhere at the top and using some transpiler - Rollup, Webpack or Babel with [babel-plugin-transform-react-jsx][].

/** @jsx h */
const h = require('{%= name %}')

const onclick = (e) => console.log('hooray it is clicked!')
const list = <ul>
  <li dataset={{ foo: 'bar', qux: 'ok' }} data-zaz="huh">one</li>
  <li className="sec huh">two</li>
  <li data-foo="hi">three</li>
</ul>

const ast = <div id="page" className="foo bar qux ok fool">
  <div id="header">
    <h1 className="classy" style="background-color: #333; color: purple">hello</h1>
  </div>
  <nav id="menu" style="background: #2f2;font-size: 12px;">
    {list}
  </nav>
  <h2 id="title" style="background-color: red;">content title</h2>
  <p className="first foobie" onclick={onclick}>so it is just like a templating engine,
    but easy to use inline with javascript
  </p>
  <p className="lastParagraph">the intention is for this to be used to create
    <strong className="bold" style="background: white; color: green">charlike </strong>
    reusable, interactive html widgets.
  </p>
</div>

console.log(ast)

Examples:

API

{%= apidocs('src/index.js') %}

Notes

The className and class

Notice that we write className, but class is also supported. Just in old javascript versions it may throw you an error if you try to write it as object key. You will just always get an array as end result in the generated node - they are just concatenated.

const tag = h('.foo', {
  className: 'bar'
})

console.log(tag.properties.className)
// => [ 'foo', 'bar' ]

// or passing multiple classes in className
const div = h('.bar', {
  className: ['qux', 'xyz']
})
console.log(div.properties.className)
// => [ 'bar', 'qux', 'xyz]

The data-* and dataset

Another that you should be aware of is that we write dataset instead of data when want to define a data-* attributes for a tag while using props object. That name comes from DOM - it saves each data attribute to an object dataset in each DOM element. You can still define each data-* attribute as key in props object, like this

const div = h('.foo', {
  'data-abc': 'hello',
  'data-bar': 'world'
})

// another way is using `dataset`
const node = h('.foo', {
  dataset: {
    abc: 'hello',
    bar: 'world'
  }
})

While using JSX you still can define it in both styles

const node = <div data-abc="hello" dataset={{ bar: 'world' }}>Hi</div>

The styles

Note that you can define style in both ways 1) using a string as value or 2) object as value.

const node = h('p', {
  style: 'background: red; font-size: 15px;'
})

console.log(node.properties.style)
// => 'background: red; font-size: 15px;'

Using above approach you'll end up finally with a node that has a properties.style a string, because we don't parse the value. So what you pass, you'll get.

If you pass an object, you'll have an object. Here in that example we'll use JSX, but it is the same as using the h-calls.

const pTagStyle = {
  background: 'red',
  'font-size': '15px'
}
const node = <p style={pTagStyle}>Hello World</p>

console.log(node.properties.style.background) // => 'red'
console.log(node.properties.style)
// => { background: 'red', 'font-size': '15px' }

Notice that we also don't decamelize style keys, so you should use quotes.

{% if (verb.related && verb.related.list && verb.related.list.length) { %}

Related

{%= related(verb.related.list, {words: 20}) %} {% } %}

Contributing

Pull requests and stars are always welcome. For bugs and feature requests, [please create an issue](https://github.com/{%= repository %}/issues/new).
Please read the contributing guidelines for advice on opening issues, pull requests, and coding standards.
If you need some help and can spent some cash, feel free to contact me at CodeMentor.io too.

In short: If you want to contribute to that project, please follow these things

  1. Please DO NOT edit README.md, CHANGELOG.md and .verb.md files. See "Building docs" section.
  2. Ensure anything is okey by installing the dependencies and run the tests. See "Running tests" section.
  3. Always use npm run commit to commit changes instead of git commit, because it is interactive and user-friendly. It uses [commitizen][] behind the scenes, which follows Conventional Changelog idealogy.
  4. Do NOT bump the version in package.json. For that we use npm run release, which is [standard-version][] and follows Conventional Changelog idealogy.

Thanks a lot! :)

Building docs

Documentation and that readme is generated using [verb-generate-readme][], which is a [verb][] generator, so you need to install both of them and then run verb command like that

$ npm install verbose/verb#dev verb-generate-readme --global && verb

Please don't edit the README directly. Any changes to the readme must be made in .verb.md.

Running tests

Clone repository and run the following in that cloned directory

$ npm install && npm test

Author

{%= includeEither('authors', 'author') %}

License

{%= copyright({ start: 2016, linkify: true, prefix: 'Copyright', symbol: '©' }) %} {%= licenseStatement %}

{%= include('footer') %}
Project scaffolded using [charlike][] cli.

{%= reflinks(verb.reflinks) %}

[downloads-url]: https://www.npmjs.com/package/{%= name %} [downloads-img]: https://img.shields.io/npm/dt/{%= name %}.svg

[codeclimate-url]: https://codeclimate.com/github/{%= repository %} [codeclimate-img]: https://img.shields.io/codeclimate/github/{%= repository %}.svg

[travis-url]: https://travis-ci.org/{%= repository %} [travis-img]: https://img.shields.io/travis/{%= repository %}/master.svg?label=linux

[appveyor-url]: https://ci.appveyor.com/project/tunnckoCore/{%= name %} [appveyor-img]: https://img.shields.io/appveyor/ci/tunnckoCore/{%= name %}/master.svg?label=windows

[coverage-url]: https://codecov.io/gh/{%= repository %} [coverage-img]: https://img.shields.io/codecov/c/github/{%= repository %}/master.svg

[david-url]: https://david-dm.org/{%= repository %} [david-img]: https://img.shields.io/david/{%= repository %}.svg