Docs
Everything You Need to Know
DOM
API
ChocolateChip-UI's DOM library has the following methods exposed on the DOM Stack object. Most of these are identical to those of the same name in jQuery.
$(selector)
This works the same as jQuery. You can provide any valid DOM/CSS selector. If there is a match for the selector, it returns the element. Otherwise it returns and empty DOM stack. Running DOM methods on an empty DOM stack will do nothing, erring silently.
const listItems = $('li')
const class = $('.items')
const id = $('#item')
const attr = $([type'])
const attr2 = $([type='text'])
$(function)
Like jQuery, this lets you run a function when the browser's DOM has loaded.
$(function() {
// Do stuff when the DOM is ready.
})
// or ES6 style:
$(() => {
// Do stuff when the DOM is ready.
})
You can have multiple functions in your document. They will be execute one after the other in order. If the DOM is already loaded, this function will execute immediately.
html`template literal`
This function converts the markup into a string. You can use new line endings to create normal looking markup. You can also pass this function some data to use as a template. This is in effect an ES6 tagged template literal.
const nodes = html`<p>This is a paragraph</p>` const list = html` <ul> <li>One</li> <li>Two</li> </ul>`
You can interpolate a varial in the template using ${}
const numbers = ['One', 'Two', 'Three']
const list = html`${numbers.map(number => html`<li>${number}</li>`)}`
// result: "<li>One</li><li>Two</li><li>Three</li>"
After creating a string of markup, you can use any of the regular DOM methods to insert it in the document, such as append, prepend, etc.
$.h(markup)
This method converts a string of markup into a document fragment, which you can then inject into the document using element.append() or any other DOM methods.
element.find(selector) - find descendant
This method let you find a select that is a descendent of the element it is anchored to.
// Get the current screen:
const screen = $('screen.current')
// Find all lists in the current screen:
screen.find('.list')
element.is(selector)
This method lets you test the element against the provided selector. It returns a boolean true/false.
const list = $('.list')
if (list.is('ul')) {
console.log('We got a list.')
}
element.index(element?)
Get the position of an element in a collection. This is a zero-based number. If no argument is provided, it gets the position of the element this is executed on in relation to its siblings. If an element is passed as an argument, it checks to see what its position is in relation to the collection this is executed against.
// Get the index of a p tag:
const paragraphPos = $('p').index()
// Get the index of a select list item:
const selectedListItem = $('.selected')
const pos = $('li').index(selectedListItem)
element.siblings(selector?)
Get the siblings of an element. If a selector is provided, the sibings must match it.
// Get all siblings of `.selected`:
const siblings = $('.selected').siblings()
// Get siblings that are list items:
const siblings = $('.selected').siblings('li')
element.closest(selector)
Get an element's ancestor that matches the provided selector.
const section = $('.list').closest('section')
element.css(property)
This method lets you get the value of a provided CSS property on the element.
// Get the following CSS properties:
const width = $('ul').css('width')
const color = $('h3').css('color')
element.css(property, value)
By passing this method two arguments, You can set the CSS properties of an element. CSS can be set in two ways: as two arguments - a property and a value - separated by a comma, or as a object of key value pairs.
// Set some CSS properties:
$('ul').css('color', 'red')
$('li').css('padding', '2px')
// Use an object to set the values:
$('ul').css({padding: '2px', color: 'red'})
element.before(content)
This method allows you to insert content before an element. The argument should be valid markup.
$('ul').before('<h2>The Title</h2>')
element.after(content)
This method lets you insert content after an element. This argument should be valid markup.
$('ul').after('<summary>This is the list summary.</summary>')
element.prepend(content)
This method allows you to prepend content to an element. That means the content is inserted at the beging of the elements children.
$('ul').prepend('<li><h3>A new item</h3></li>')
element.append(content)
This method allows you to append content to an element. That means the content is inserted as the last children of the element.
$('ul').append('<li><h3>A new, last item</h3></li>')
element.empty()
This method deletes all the child elements of the element it is executed on.
// Delete a list's content:
$('ul').empty()
element.html(content)
This method allows you to set the content of an element. The content should be valid markup.
$('.list').html('<li><h3>A new item</h3></li>')
Note about element.html(content)
ChocolateChip-UI's implementation differs from jQuery in that to create HTML elements, the markup must be valid HTML5. jQuery allows using its own shorthand markup, such as <div/> or <ul/>. Since this is not valid HTML5 markup, it will fail in ChocolateChip-UI. You need to use <div></div> or <ul></ul>.
element.html()
This method lets you get the content of an element.
const listContent = $('ul').html()
element.text(content)
This method lets you set the text content of an element.
$('h2').text('This is the title')
element.text()
This method lets you get the text of an element.
const title = $('h2').text()
element.remove()
This method removes the element it is executed on. Before removing the element, all events are unbound.
$('li.selected').remove()
element.replaceWith(content)
This method replaces the element it is executed on with the provided content, which may be markup for new elements or a node of a currently existing element in the document. Before removing the element, all events are unbound from it and, if the element that will replace it is already in the DOM, from the replacement element as well.
// Replace element with new content:
$('li.selected').replaceWith('<li><h3>New content!</h3></li>')
// Replace one element with another:
$('li.selected').replaceWith($('li:first-of-type'))
element.val(value)
This method lets you set the value of a form element.
$('#nameInput').val('John Doe')
element.val()
This method lets you get the value of a form element.
const name = $('#nameInput').val()
element.hide()
This method lets you hide an element.
$('li').is('.selected').hide()
element.show()
This method lets you show a hidden element.
$('li').show()
element.on(event, callback, type)
This method lets you bind an event to an element.
$('button').on('tap', () => alert('You just tapped!'))
element.on(event, element, callback, type)
This method allows you to register a delegated event on a element. You use delegated event when you need to register events on multiple items, such as list items.
$('ul').on('tap', 'li', () => alert('You just tapped!'))
element.off(event, callback, type)
This method lets you remove an event from an element. If no arguments are provided, all events will be removed.
// Remove tap event:
$('button').off('tap')
// Remove all events from list:
$('ul').off()
element.off(event, element, callback, type)
This method lets you remove delegated events.
// Remove delegated events from list items:
$('ul').off('tap', 'li')
element.trigger(event, data?)
This method lets you trigger the provided event on the element.
$('button').trigger('tap')
Optionally, you can pass a data object with the tirggered event. This gets passed to the callback on the event as the data property. You can access this from the callback's event:
// Setup event listener:
$('#button').on('tap', function(e) {
if (e.data) {
alert(e.data.msg)
} else {
alert('Nothing to say for now.')
}
})
// Trigger event and pass data:
$('#button').trigger('tap', { msg: 'This is from the trigger. Hello!'})
element.serializeArray()
This method create an array of key-value objects from a form's elements.
const data = $(form).serializeArray()
element.serialize()
This method creates a text string in standard URL-encoded notation.
const data = $(form).serialize()
element.eq(index)
Get an element based on its position in a collection. This uses zero-based numbers.
$('li').eq(4).addClass('important')
element.push(element)
Push an element onto the collection.
const listItem = $('#firstList').find('li').eq(2)
$('#list').find('li').push(listItem)
element.pop()
This method lets you pop the last item off of a collection.
const listItems = $('li')
listItems.pop()
element.unshift(element)
This method lets you add an element to the start of a collection.
const listItem = $('#firstList').find('li').eq(2)
$('#list').find('li').unshift(listItem)
element.shift()
This method lets you remove an element from a collection.
$('li').shift()
element.forEach(callback)
This method lets you execute a callback on each item in the collection. Its arguments follow the normal JavaScript convention of context followed by index.
$('li').forEach(function(item, idx) {
$('item').append(' Sold!')
console.log('Just output item: ' + idx + 1)
})
element.slice()
This method works just like the array equivalent.
element.splice()
This method works just like the array equivalent.
element.filter(callback)
This method works just like the array equivalent.
element.map(callback)
This method works just like the array equivalent.
element.every(callback)
This method works just like the array equivalent.
element.some(callback)
This method works just like the array equivalent.
element.unique()
This method removes any duplicate elements in the collection.
const listItems = $('li').unique()
element.array
ChocolateChip-UI stores element's in a Stack's array. You can examine this array at any time to get directly at the raw DOM nodes.
element.array.length
This is not a method, but a property on a Stack. It indicates the number of nodes a Stack contains. It does not you use methods to add or remove items from the Stack, this value will be updated. However, because a Stack is an object, you cannot change it to change the number of items in the Stack. Do not attempt to change this value!. Use push, pop, and other Stack methods to change the number of items.
// Find out how many list items:
const li = $('li')
console.log(li.array.length)
element.array[0]
Sometimes you need to get at the plain DOM node. This might be because you want to drop down to plain JavaScript while accessing the properties of a DOM element. To get at the node itself, you can access it direclty using array[0] on the node. the DOM stack stores its element in an array, so you can access them in the stack using element.array[0]. If you want to get at the node at a later position in a collection, use the element.eq() with this:
// Get the first list item:
if ($('li').array[0].nodeName === 'LI') {
alert('Got a list item!')
}
// Get the third list item/
// Remember that `eq` is zero-based:
const li3 = $('li').eq(2).array[0]
console.log(li3.nodeName)
element[0]
You can also access the element in a DOM Stack using [0] notation directly on the Stack. Please note that in the case of a Stack holding multiple nodes, this will only give you access to the first node. If you want to access a node other than the first in the Stack, use the element.array[3] notation described above.
// Get the first list item:
const firstLi = $('li')[0]