README

dom-component-parser

Sometimes you want to be able to quickly set up a JavaScript component in your DOM with some settings. Libraries like Vue.js provide a powerful API to create custom components, but is quite heavy for cases like mounting third party libraries to your DOM.

Say we want to mount a hypothetical Uploader component on all .js-uploader nodes:

<div
    class="js-uploader"
    data-url="http://my-site.com/upload1"
    data-multiple
></div>
<div
    class="js-uploader"
    data-url="http://my-site.com/upload2"
></div>

Now let's retrieve the DOM element and read out the options in JavaScript:

for (let element of document.querySelectorAll('.js-uploader')) {
    const url = element.getAttribute('data-url');
    const multiple = element.getAttribute('data-multiple') === '' ? true : false;

    if (!url) throw new Error();

    new Uploader(element, { url, multiple });
}

The dom-component-parser cleans up the above process by declaring a component name and options object shape.

import component from 'dom-component-parser';

component('uploader', {
    url: 'required', // `required` is a special flag, will throw an error if missing
    multiple: false, // Defaults to false
}).forEach(({ element, options }) => new Uploader(element, options));

Install

You can install the package via npm:

$ npm install dom-component-parser

Usage

Retrieving Components

The component method always returns an array of results. Components are queried for a class with their names prefixed by js-, e.g. a component named my-uploader expects an element with a js-my-uploader class.

<div class="js-my-uploader" data-upload-url="http://example.com"></div>

import component from 'dom-component-parser';

const myUploaders = component('my-uploader');
// => [ { element: <Element>, options: {} } ]

Declaring Component options

Component options are declared as objects, and map to the component's data attributes. The attribute's corresponding value provided in the script will be used as the default value if it's omitted from the DOM element. Camel-cased object keys will look for a snake-cased data attributes.

<div class="js-my-uploader"></div>
<div class="js-my-uploader" data-upload-url="http://my-site.com/upload"></div>

const myUploaders = component('my-uploader', { uploadUrl: 'http://example.com' });
// [ { element: <Element>, options: { uploadUrl: 'http://example.com' } },
//   { element: <Element>, options: { uploadUrl: 'http://my-site.com/upload' } } ]

There's also a special required keyword, which will throw an error if the data attribute is missing.

<div class="js-my-uploader"></div>

const myUploaders = component('my-uploader', { uploadUrl: 'required' });
// Error: Option `required` is missing on component `my-uploader`

Attributes without values will be casted to true.

<div class="js-my-uploader"></div>
<div class="js-my-uploader" data-multiple></div>

const myUploaders = component('my-uploader', { multiple: false });
// [ { element: <Element>, options: { multiple: false } },
//   { element: <Element>, options: { multiple: true } } ]

Change log

Please see CHANGELOG for more information what has changed recently.

Testing

$ npm run test

Contributing

Please see CONTRIBUTING for details.

Security

If you discover any security related issues, please contact Sebastian De Deyne instead of using the issue tracker.

Credits

About Spatie

Spatie is a webdesign agency based in Antwerp, Belgium. You'll find an overview of all our open source projects on our website.

License

The MIT License (MIT). Please see License File for more information.

Usage no npm install needed!