superdom

Superdom.js

You have dom. It has all the DOM virtually within it. Use that power:

// Fetch all of the links from the page
var links = dom.a.href;
 
// Make the links open in a new tab
dom.a.target = '_blank';

Only for modern browsers

Getting started

Simply use the CDN via unpkg.com:

<script src="https://unpkg.com/superdom@1"></script>

Or use npm or bower: npm|bower install superdom.

Select

It always returns an array with the matched elements, just get a property of dom with that selector:

// Simple element selector
var allLinks = dom.a;
 
// Combined selector
var importantLinks = dom['a.important'];

There are also some predetermined elements, such as id, class and attr that can be used for selection:

// Select HTML Elements by id:
var main = dom.id.main;
 
// by class:
var buttons = dom.class.button;
 
// or by attribute:
var targeted = dom.attr.target;
var targeted = dom.attr['target="_blank"'];

Generate

Use it as a function or a tagged template literal to generate a DOM fragments:

// Not a typo; tagged template literals
var list = dom`<a href="https://google.com/">Google</a>`;
 
// It is the same as
var link = dom('<a href="https://google.com/">Google</a>');

Delete elements

Delete a piece of the DOM

// Delete all of the elements with the class .google
delete dom.class.google;   // Is this an ad-block rule?

Attributes

You can easily manipulate attributes right from the dom node. There are some aliases that share the syntax of the attributes such as html and text (aliases for innerHTML and textContent). There are others that travel through the dom such as parent (alias for parentNode) and children. Finally, class behaves differently as explained below.

Get attributes

The fetching will always return an array with the element for each of the matched nodes (or undefined if not there):

// Retrieve all the urls from the page
var urls = dom.a.href;     // #attr-list
  // ['https://google.com', 'https://facebook.com/', ...]
 
// Get an array of the h2 contents (alias of innerHTML)
var h2s = dom.h2.html;     // #attr-alias
  // ['Level 2 header', 'Another level 2 header', ...]
 
// Get whether any of the attributes has the value "_blank"
var hasBlank = dom.class.cta.target._blank;    // #attr-value
  // true/false

You also use these:

• html (alias of innerHTML): retrieve a list of the htmls
• text (alias of textContent): retrieve a list of the htmls
• parent (alias of parentNode): travel up one level
• children: travel down one level

Set attributes

// Set target="_blank" to all links
dom.a.target = '_blank';     // #attr-set

dom.class.tableofcontents.html = `
  <ul class="tableofcontents">
    ${dom.h2.map(h2 => `
      <li>
        <a href="#${h2.id}">
          ${h2.innerHTML}
        </a>
      </li>
    `).join('')}
  </ul>
`;

Remove an attribute

To delete an attribute use the delete keyword:

// Remove all urls from the page
delete dom.a.href;
 
// Remove all ids
delete dom.a.id;

Classes

It provides an easy way to manipulate the classes.

Get classes

To retrieve whether a particular class is present or not:

// Get an array with true/false for a single class
var isTest = dom.a.class.test;     // #class-one

For a general method to retrieve all classes you can do:

// Get a list of the classes of each matched element
var arrays = dom.a.class;     // #class-arrays
  // [['important'], ['button', 'cta'], ...]
 
// If you want a plain list with all of the classes:
var flatten = dom.a.class._flat;     // #class-flat
  // ['important', 'button', 'cta', ...]
 
// And if you just want an string with space-separated classes:
var text = dom.a.class._text;     // #class-text
  // 'important button cta ...'

Add a class

// Add the class 'test' (different ways)
dom.a.class.test = true;    // #class-make-true
dom.a.class = 'test';       // #class-push

Remove a class

// Remove the class 'test'
dom.a.class.test = false;    // #class-make-false

Manipulate

Did we say it returns a simple array?

dom.a.forEach(link => link.innerHTML = 'I am a link');

But what an interesting array it is; indeed we are also proxy'ing it so you can manipulate its sub-elements straight from the selector:

// Replace all of the link's html with 'I am a link'
dom.a.html = 'I am a link';

Of course we might want to manipulate them dynamically depending on the current value. Just pass it a function:

// Append ' ^_^' to all of the links in the page
dom.a.html = html => html + ' ^_^';
 
// Same as this:
dom.a.forEach(link => link.innerHTML = link.innerHTML + ' ^_^');

Note: this won't work dom.a.html += ' ^_^'; for more than 1 match (for reasons)

Or get into genetics to manipulate the attributes:

dom.a.attr.target = '_blank';
 
// Only to external sites:
var isOwnPage = el => /^https?\:\/\/mypage\.com/.test(el.getAttribute('href'));
dom.a.attr.target = (prev, i, element) => isOwnPage(element) ? '' : '_blank';

Events

You can also handle and trigger events:

// Handle click events for all <a>
dom.a.on.click = e => ...;
 
// Trigger click event for all <a>
dom.a.trigger.click;

Testing

We are using Jest as a Grunt task for testing. Install Jest and run in the terminal:

grunt watch