Controlling your Snippet

Now that your Snippet is in your website's HTML and Plinthos is configured, we can start changing the content on display.

Technical Overview

If you're not a techy, skip to Controlling with HTML

By default, the Plinthos Snippet initializes an Intersection Observer and a Mutation Observer to detect instructions coming from the DOM, including in SPA contexts.

Both the Intersection and Mutation Observers can be disabled in the Snippet configuration.

Leveraging the HTML controls with the Intersection and Mutation observers is highly recommended because it also enables dynamic lazy-loading.

Should I use the HTML or the JavaScript API?

The HTML and JavaScript APIs are designed to work together to create the best possible, most dynamic experience for your users and which you use should depend on the task.

Use the HTML API for:

• Displaying or updating content in response to the user's scroll position.

Use the JS API for:

• Responding to user-driven events (e.g., button clicks).
• Displaying or updating content in web app contexts that use router navigation hooks or component on-load hooks.

Controlling with HTML

The easiest way to control the content on display is with data attributes. This method is the intended default way to use your Plinthos Snippet with JavaScript control used to respond to events like user input.

This is done by adding data attributes to the elements of your page that form significant portions of the layout. In semantically written HTML, <section> tags tend to be good targets for this. The data attributes contain instructions describing what Content should be shown on which Instances.

Your Snippet detects when these elements are scrolled into view and updates the Instances.

<section data-pd-show="plinth@background">
    <!-- Website content to accompany the "Plinth" shot -->
</section>

In the example above, when the <section> element is scrolled into view, the background Stage Instance will display the plinth Shot.

Anatomy of the data attribute

Here is a breakdown of each part of the data attribute working from left to right.

Attribute key

data

This is a prefix required of all data attributes to ensure that the contents is added to the DOM element's dataset parameter. Don't worry if this doesn't make sense.

pd

This is a Plinth Digital specific prefix that tells Plinthos that this data attribute is relevant to Plinthos.

Since data attributes are used for all sorts of things and likely strewn through your HTML, this prefix allows Plinthos to rapidly ignore information that is not intended to affect the content.

If this prefix happens to collide with other data attributes in your website, this prefix can be configured in the snippet configuration. This is a very unlikely edge-case, though, and for ease of use, we strongly recommend leaving it as the default unless absolutely necessary.

show

This tells Plinthos that the body of this data attribute contains Stage instructions.

Attribute body

plinth

This is the Key of the Shot that we wish to display when this element is in view.

@

A separator that connects the Shot key to the Stage Instance key.

background

The Stage Instance Key of the Stage on which we want to display the plinth Shot.

Multiple Instructions

In setups with multiple Plinthos instances on the same page, it is possible to send multiple instructions from the same element:

In the following example, the background Instance will show the plinth shot and the embed Instance will show the echo shot.

<section data-pd-show="plinth@background; echo@embed">
    <!-- Website content -->
</section>

Note

Plinthos is not fussy about whitespace in these instructions so format them in a way that looks right to you. The data attributes in the following example are all considered equivalent:

<section
    data-pd-show="plinth@background;echo@ embed"
    data-pd-show="plinth @ background ; echo@embed"
    data-pd-show="plinth@ background; echo @embed"
    >
    <!-- Website content -->
</section>

Parameters via Attributes

Parameters are extra pieces of data that change how Plinthos Content is displayed. You can send parameters alongside your instructions with additional data attributes. Each Stage will have a different set of parameters that it responds to but there are some that come standard with most Stages.

Basics

In the following example, the plinth Shot will be displayed on the background Instance and the Shot will be zoomed in by a factor of 2.

<section data-pd-show="plinth @ background" data-pd-zoom="2">
    <!-- Website content -->
</section>

Note that the data-pd-zoom attribute also requires the data prefix (so that it's included in the DOM object's dataset property) and the pd prefix (so that Plinthos knows that this attribute is intended for its use).

Multiple

In the following example, the plinth Shot will be displayed on the background Instance, zoomed out by a factor of 0.8 and horizontally offset so that the Shot is centered in the middle of the left hand side of the page (courtesy of data-pd-lhs).

<section
    data-pd-show="plinth @ background"
    data-pd-zoom="0.8"
    data-pd-lhs
    >
    <!-- Website content offset to render on the right hand side -->
</section>

Multiple Parameters can be sent at once using multiple data attributes. Note that the data-pd-lhs attribute does not have a body; in cases like this, Plinthos interprets this Parameter's value as the boolean value true.

Parameter Inheritance

Parameter values can be inherited from ancestor elements / overridden by descendant elements allowing for defaults to be set at various levels throughout the DOM.

Basic inheritance

In the following example Section 1 will display the plinth Shot on the background Instance horizontally offset so that the Shot is centered in the middle of the left hand side of the page. Section 2 will display the echo shot on the background instance with the same horizontal offset as Section 1 because both shots inherited the data-pd-lhs attribute from their parent tag.

<div data-pd-lhs>
    <section
        data-pd-show="plinth @ background"
        >
        <!-- Section 1 -->
    </section>
    <section
        data-pd-show="echo @ background"
        >
        <!-- Section 2 -->
    </section>
</div>

Advanced inheritance

Here is a more complex example. The instructions sent by each section are explained below.

<div
    data-pd-zoom="0.5"
    data-pd-plinth-color="#ffaa00"
    >
    <div data-pd-lhs>
        <section data-pd-show="plinth @ background">
            <!-- Section 1 -->
        </section>
        <section
            data-pd-show="echo @ background"
            data-pd-plinth-color="#00ccff"
            >
            <!-- Section 2 -->
        </section>
    </div>
    <div data-pd-rhs>
        <section data-pd-show="grid @ background">
            <div data-pd-zoom="2">
                <!-- Section 3 -->
            </div>
        </section>
    </div>
</div>

Section 1

• The plinth shot will be displayed on the background Instance.
• The Shot will be horizontally offset to be centered at the middle of the left hand side of the page due to the data-pd-lhs attribute on the section tag's parent div element.
• The Plinth motif will be colored #ffaa00 and the Shot will be zoomed out by a factor of 0.5 due to the data-pd-plinth-color and data-pd-zoom attributes present on the section tag's grandparent div element.

Section 2

• The echo shot will be displayed on the background Instance. The Plinth motif will be colored #00ccff due to the data-pd-plinth-color attribute present on the section tag.
• The Shot will be horizontally offset to be centered at the middle of the left hand side of the page due to the data-pd-lhs attribute on the section tag's parent div element.
• The Shot will be zoomed out by a factor of 0.5 due to the data-pd-zoom attributes present on the section tag's grandparent div element. The data-pd-plinth-color attribute on the grandparent div tag was overridden by the value on the section tag and so has no effect on Section 2.

Section 3

• The grid shot will be displayed on the background Instance.
• The Shot will be horizontally offset to be centered at the middle of the right hand side of the page due to the data-pd-rhs attribute on the section tag's parent div element.
• The Plinth motif will be colored #ffaa00 and the Shot will be zoomed out by a factor of 0.5 due to the data-pd-plinth-color and data-pd-zoom attributes present on the section tag's grandparent div element.
• The data-pd-zoom="2" attribute on the section tag's child div element will have no effect because the instruction sent by the section tag only looks upwards through the DOM ancestry for parameters.

Responsive Parameters

Parameters can be given multiple values bound to viewport width to allow for responsive Shot composition.

Parameters with viewport responsive values must begin with a ? followed by the default value. After that, add a minimum viewport width value enclosed in square brackets [] followed by the parameter's new value when the viewport is equal to or above the bracketed value.

<section
    data-pd-show="plinth @ background"
    data-pd-y-focal-point="?0.5[768]0"
    data-pd-x-focal-point="?0[768]0.6[1400]0.5"
    >
    <!-- Website content -->
</section>

In this example, data-pd-y-focal-point has the value 0.5 when the viewport is betwen 0 and 767 pixels wide. When the viewport is at or above 768 pixels, its value is 0.

Similarly, data-pd-x-focal-point has the value 0 when the viewport is between 0 and 767 pixels wide. When the viewport is between 768 and 1399 pixels wide, the value is 0.6 and then the viewport is 1400 pixel wide or more, the value is 0.5.

Responsive parameters are most useful when changeing camera angles or camera offsets to ensure that Content is frames appropriately on both desktop and mobile devices.

Special Data Attributes

There are a number of special data attributes that you can use to make Plinthos easier to use with certain types of websites or website builders.

Apply to Ancestor

Special data attribute data-pd-apply-to-ancestor treats its value as a css selector and applies all of its Plinthos data attributes (i.e., data attributes prefixed with "pd") to the nearest ancestor that matches the selector.

Some website builders allow you to edit content blocks but do not allow you to directly edit the HTML (e.g., Squarespace, some Wordpress themes, etc). Since applying data attributes to section tags is usually ideal, Plinthos provides this special data attributes to make this possible under these contraints.

input

<section>
    <div class="container">
        <!-- User editable code starts here -->
         <div class="content">
            <u data-pd-apply-to-ancestor="section"
                data-pd-show="pyramid @ background"
                data-pd-horizon="#a94"
                ></u>
            <!-- Section content -->
         </div>
        <!-- User editable code ends here -->
    </div>
</section>

result

<section data-pd-show="pyramid @ background"
    data-pd-horizon="#a94"
    >
    <div class="container">
        <!-- User editable code starts here -->
        <div class="content">
            <u data-pd-apply-to-ancestor="section"
                data-pd-show="pyramid @ background"
                data-pd-horizon="#a94"
                ></u>
            <!-- Section content -->
        </div>
        <!-- User editable code ends here -->
    </div>
</section>

In this example, a user can add a code block containting the highlighted u tag (any tag would work but an empty inline tag is best) into the user-editable section and Plinthos will automatically apply its relevant data attributes to the section tag (since it matches the css selector section in the data-pd-apply-to-ancestor attribute).

Apply to Descendant

Special data attribute data-pd-apply-to-descendant treats its value as a css selector and applies all of its Plinthos data attributes (i.e., data attributes prefixed with "pd") to the nearest descendant that matches the selector.

If you are able to add code snippets only at a high level but you want to add data attributes to nested elements, data-pd-apply-to-descendant can help.

Controlling with JavaScript

Your Stage Instances can also be controlled using JavaScript.

By default, your Snippet will create an object in the global scope called Plinthos. As Stage Instances are created by the Snippet, a reference to them will be stored under Plinthos.instances (a keyed object of Stage Instances).

Kits initialize asynchronously

The Kit initializes asynchronously so the Plinthos object is not guaranteed to be fully populated if you're accessing it as your site is loading.

You can compensate for this by putting your Kit-dependent code in an event listener that listens for the 'plinthoskitready' event which is fired from the document node as soon as the Kit has finished its initialization process.

// Global Scope

// ❌ The following line might result in an error.
// "background" may be undefined due to a race condition.
Plinthos.instances.background.setContent('plinth');

document.addEventListener('plinthoskitready', () => {
    // ✅ It is now safe to assume your Stage Instances are ready.
    Plinthos.instances.background.setContent('plinth');
});

The Plinthos object also has a ready variable which you can check at any time to see the ready status of the Kit.

Plinthos.ready; // true if all Instances are initialized, false otherwise.

Below is the most basic example of setting Stage Instance Content using JavaScript:

Plinthos.instances.background.setContent('plinth');

Parameters

The setContent function takes an options second parameter which should be a keyed object of Shot Parameters:

Plinthos.instances.background.setContent('plinth', {
    rhs: true,
    zoom: 0.8,
    plinthColor: '#00ccff',
});

The example above will result in the same Shot arrangement as the following data attribute control:

<section
    data-pd-show="plinth@background"
    data-pd-rhs
    data-pd-zoom="0.8"
    data-pd-plinth-color="#00ccff"
    >
</section>

Why don't the keys in the JavaScript object have the pd prefix?

You might have noticed that the pd prefix is missing from the object keys in the JavaScript example and you might have expected them to be present since the dataset property of the section element would still have them attached (i.e., pdRhs, pdZoom, pdPlinthColor).

The purpose of the pd prefix is to tell Plinthos which data attributes it should pay attention to and which it should ignore. The result of this filtration process creates a keyed object that looks like the object shown in the JavaScript example instead of an object populated directly from the dataset property of the element.