populate

Populate DOM elements with data

Simple Example

The idea is that you take a pair of data and DOM elements and apply a mapping from the data onto the DOM.

var populate = require("populate")
    , property = require("populate/property")
    , textContent = require("populate/textContent")

var elements = {
    root: document.createElement("div")
    , text: document.createElement("span")
    , link: document.createElement("a")
}

populate({
    text: "some text goes in span!"
    , link: "http://google.com"
}, elements, {
    text: textContent
    , link: property("href")
})

elements.root.appendChild(elements.text)
elements.root.appendChild(elements.link)
document.body.appendChild(elements.root)

The above mapping placed the link into the <a>'s href property and placed the text into the <span>'s textContent.

Complex Example

The format of an object of elements allows you to populate multiple elements from a single object of data.

It also works cleanly with the result of unpack-html. However using unpack-html is completely optional. Feel free to get references to your DOM elements however you want!

<!-- ./template.html -->
<div>
    <div id="someText"></div>
    <div>
        <a id="someLink">I am a link</a>
    </div>
    <div>
        <textarea id="different"></textarea>
    </div>
    <ul id="name">
        <li>Im a nested template or something</li>
    </ul>
</div>

var html = require("unpack-html")
    , populate = require("populate")
    , property = require("populate/property")
    , textContent = require("populate/textContent")

    , template = require("./template.html")

// Generate an object of DOM element references to populate
// You can use something other then unpack-html!
var elements = html(template)
var data = {
    someText: "this is some text"
    , someLink: "http://google.com"
    , value: "you can map to other elements"
    , name: [
        "one"
        , "two"
        , "three"
    ]
}

populate(data, elements, {
    someText: textContent
    , someLink: property("href")
    , value: property("value", "different")
    // Custom logic. Mappings are just functions, do anything
    // you want!
    , name: function (value, elem, elements) {
        var tmpl = elem.firstElementChild
        elem.removeChild(tmpl)

        value.forEach(function (text) {
            var clone = tmpl.cloneNode(true)
            clone.textContent = text
            elem.appendChild(clone)
        })
    }
})

document.body.appendChild(elements.root)

Stream example

<!-- ./template.html -->
<div>
    <div>Name: <span id="name"></span></div>
    <div>Value: <span id="value"></span></div>
</div>

/*global document*/
var html = require("unpack-html")

    , PopulateStream = require("../../stream")
    , textContent = require("../../textContent")
    , template = require("./template.html")

var elements = html(template)
var stream = PopulateStream(elements, {
    value: textContent
    , name: textContent
})

var name = "Streaming population!"
var value = 0

setInterval(function () {
    value++
    stream.write({
        name: name
        , value: value
    })
}, 500)

document.body.appendChild(elements.root)

Docs

var elements = populate(data, elements, mapping)

populate the elements with the supplied data and mapping.

populate returns the elements you pass in for convenience.

mapping is expected to be an object with string keys and function values.

For each key it will find data[key] and elements[key], then it calls mapping(data[key], elements[key], elements)

This means your mapping might look like:

var populate = require("populate")

populate({ text: "hello" }, elements, {
    text: function (value, element) {
        element.textContent = value
    }
})

The above example function is actually the same as populate/textContent and this is the simplest way to use populate.

The value in the mapping object doesn't actually have to be a function. It can also be an array.

Let's say you have a link to a users page and you want to populate both the users profile image and his name with that link so he can click either and it redirects him.

var populate = require("populate")

populate({ userLink: someUri }, elements, {
    userLink: [function (value, _, elements) {
        elements.profileImageWrapper.href = value
    }, function (value, _, elements) {
        elements.userNameLink.href = value
    }]
})

Finally you can also supply an object as the value and populate will just recurs

var populate = require("populate")
    , textContent = require("populate/textContent")

populate({
    user: {
        name: "Steve"
    }
}, elements, {
    user: {
        name: textContent
    }
})

textContent

textContent is the simplest function you can use in a mapping. It basically says map the value to the elements textContent

var populate = require("populate")
    , textContent = require("populate/textContent")
    , assert = require("assert")

var elements = populate({
    text: "foo"
}, {
    text: document.createElement("span")
}, {
    text: textContent
})

assert.equal(elements.text.textContent, "foo")

property(prop[, name])

property is a slightly more flexible function that can be used in mapping. It maps the value to an elements property.

It takes an optional name property so that your elements keys can have different names from your data structure

var populate = require("populate")
    , textContent = require("populate/textContent")
    , assert = require("assert")

var elements = populate({
    link: "http://google.com"
}, {
    link: document.createElement("a")
}, {
    text: property("src")
})

assert.equal(elements.text.textContent, "http://google.com")

Installation

npm install populate

Contributors

• Raynos

MIT Licenced