Installation

Download the latest build and link the minified files in your HTML file's head section.

<link rel="stylesheet" href="platz-VERSION.min.css">
<script src="platz-VERSION.min.js"></script>

Usage

All elements that should receive platz.js functionality have to be registered. This can either be done with Platz.init() which automatically finds all elements in the DOM that use platz.js attributes or with Platz.register(element) which will register a single element and can provide hooks for custom behaviour as explained in the hooks section.

IMPORTANT: Registering targets more than once is undefined behaviour.

Simple Placeholder

This is the basic placeholder. It visually replaces the target with the text specified in the data-platz attribute. Below you can see a list and a table that demonstrate this functionality. You can remove and add elements with the buttons.

List

<div class="collection" data-platz="The list is empty">
    ...
</div>

When dealing with tables there is more to consider. A table is either split into thead and tbody or the rows (tr) can be direct sub-elements of the table. When the later is the case any row containing no data columns (td) will be considered empty. If the header should not be hidden when the placeholder is shown then the table has to be split into thead and tbody.

<table data-platz="The table is empty">
    <tr>
        <th>Foo</th>
        <th>Bar</th>
        <th>Baz</th>
        <th>Action</th>
    </tr>
    
    ...
</table>

<table data-platz="The table is empty">
    <thead>
        <tr>
            <th>Foo</th>
            <th>Bar</th>
            <th>Baz</th>
            <th>Action</th>
        </tr>
    </thead>
    <tbody>
        ...
    </tbody>
</table>

Styling

The automatically generated placeholder is a span element and sometimes this placeholder should be addressable by CSS. To make this possible the target element needs an id attribute. The generated placeholder will then receive a data-platz-for attribute containg the target id. Below you can see an example of how this could be used.

<div id="list" class="collection" data-platz="The list is empty">
    ...
</div>

[data-platz-for="list"] {
    font-size: 2em;
    color: #2196F3;
}

Advanced Placeholder

While simple placeholders can only specify text advanced placeholders can be used to use entire elements. The data-platz-id attribute contains the id of the element to use as a placeholder.

add

<div class="collection" data-platz-id="placeholder">
    ...
</div>

<img id="placeholder" src="https://github.com/Fylipp.png" alt="Placeholder image">

Hooks

Hooks can notify you when certain things hapen. The supported hooks are onChildless and onParent and the target is always passed as the only argument.

Platz.register(element, {
    onChildless: function (element) { ... },
    onParent: function (element) { ... },
});

Below you can see an example that uses hooks to create console messages. Note that data-platz-no-implicit attribute is required in order to exclude the list from the Platz.init function's scope so that it can be registered explicitly with Platz.register.

<div class="collection" data-platz="The list is empty" data-platz-no-implicit>
    ...
</div>

Platz.register(document.getElementById('example-hooks-list'), {
    onChildless: function() { console.log('The list has no children'); },
    onParent: function() { console.log('The list is a parent'); }
});