Arlement

Extendable DOM selector engine

Arlement takes a CSS Selector string and gives you an array of HTML elements. That's it.

Install

To install Arlement you will need Node.js:

npm install arlement --save

Usage

import Arlement from 'arlement'

const $ = new Arlement()

// adds a class to all li-elements
$('li').forEach(element => element.classList.add('list-item'))

You can also pass in a HTMLElement, a NodeList or a present Arlement:

const list = document.querySelector('ul#list')

// adds a class to the selected element
$(list).forEach(element => element.classList.add('list'))

// note: Arlement is always an array (even it contains just one element). The following doesn't work!
$(list).classList.add('list') // error!

const listItems = document.querySelectorAll('li')

// adds a class to all li-elements
$(listItems).forEach(element => element.classList.add('list-item'))

const $heading = $('.heading')
const $listItems = $('li')
const $headingAndListItems = $heading.concat($listItems)

// adds a class to all h1- and li-elements
$(headingAndListItems).forEach(element => element.classList.add('heading-or-list-item'))

Arlement is a real Array, so you can use all buildin Array methods to work with or manipulate the elements machted by the selector.

// all hidden li-elements
const $hiddenListItems = $('li').filter(element => element.hasAttribute('hidden'))

context

Of course you can definde a context where to search for elements:

<!-- index.html -->
…
<h1 class="heading">Outer Heading</h1>
<div class="inner">
  <h2 class="heading">Inner Headeing</h2>
</div>
…

const $inner = $('.inner')

// selects the h2 only
const innerHeading = $('.heading', $inner)

In your project

To not call const $ = new Arlement() in every file, you can instantiate Arlement once and import it in every file you need it:

// globals.js

import Arlement from 'arlement'
export default new Arlement()

// list.js

import $ from './globals.js'

$('li').forEach(element => element.classList.add('list-item'))

Extensions

If you're seeing youreself often to add classes to elements, you can add a helper function to Arlement

// globals.js

import Arlement from 'arlement'
export default new Arlement({
  addClass: className => {
    this.forEach(element => element.classList.add(className))
    return this // returning `this` makes your Arlement chainable!
  }
})

// list.js

import $ from './globals.js'

$('li').addClass('list-item')

// heading.js

import $ from './globals.js'

$('h1').addClass('heading')

Tests

Tests are written with QUnit. You can see the test results on Travis CI or in your target browser on https://lokkasio.github.io/arlement/.

Contribution

Any kind of feedback or contribution (bug reports, feature requests, ideas, questions, pr's, …) is wellcome!

lokkasio/arlement