README

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

Usage

import $ from '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)

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'

class MyArlement extends Arlement {
  addClass (className) {
    this.forEach(element => element.classList.add(className))
    return this // returning `this` makes your Arlement chainable!
  }
}

export default (selector, context) => new MyArlement(selector, context)

// 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!

Usage no npm install needed!