Droplet Documentation

Introduction#

Greetings! This is the official up-to-date documentation for the Droplet web plugin. We invite you to read through all of this documentation carefully to acquire a full in-depth knowledge for how Droplet works.

What Is The Purpose of Droplet?#

The purpose of Droplet is to present information to website visitors in small portions and also achieve that in a meaningful way. A key feature of Droplet is the menu bar at the top. It can either be laid out as a breadcrumb bar or as simple navigation with back and home buttons. Droplet's main content is loaded dynamically. Droplet thrives to be stylish and use animations in a way that would increase the readability and general understanding of the provided information. Last but not least, with Droplet we want to encourage better knowledge of various web technologies.

Anatomy of Droplet#

Droplet starts with a simple HTML element container. The initial content is put inside the container as HTML code. Also, data-title attribute should be added to the host element in order to give your content card a title name. It will be copied over to the dynamically created menu bar (enabled by default, see menu bar option).

By default Droplet will auto capture all hyperlinks inside the content area (see “d-prevent” class name option) and prevent your user agent from navigating to the new location. Instead, once a link inside the content area is clicked, Droplet will initiate a new HTTP request, receive HTML data from the new location, and create a new content card.

Content Fragments#

It's important to note that Droplet will not inject the entire HTML data into the new card, but rather cut out a portion of it. Specifically, Droplet will look for an element with ID attribute set to “content” (see “defaultFragment” option), grab its inner HTML content, and place it into the new card.

<div id="content">
    <p>Content for the next card.</p>
    <p><a href="more-card.html">Show even more</a></p>
</div>

The title for the new content card will be taken from the HTML's unique <title> tag. If it's absent, first 3 words will be used from the main content.

You can customize the target location's fragment to be cut out by adding your fragment component to hyperlink's URL, like so:

<a href="next-card.html#my-fragment">Show more</a>

When the above is used, Droplet will look for an element with ID attribute set to “my-fragment” in the target location's HTML data.

<div id="my-fragment">
    <p>Content for the next card.</p>
    <p><a href="more-card.html">Show even more</a></p>
</div>

Network Response in JSON Format#

Droplet will also accept response data in JSON format. The response message must contain a Content-Type header which would start with application/json in the response headers. Droplet expects the JSON object to contain at least title and content elements.

{
    "title": "Hello!",
    "content": "<p>This is my content.<\/p><p><a href=\"next-card.html\">Show more<\/a><\/p>"
}

Content should be provided in HTML format like shown above. If the fragment component was provided in the URL which initiated the request, Droplet will look for an element that would match the fragment name in the JSON object. For example, with fragment set to “my-fragment”, ideally the JSON response object should look like the below.

{
    "title": "Hello!",
    "my-fragment": "<p>This is my content.<\/p><p><a href=\"next-card.html\">Show more<\/a><\/p>"
}

Plain Text Responses#

Droplet will also try to work with plain text responses, eg. Content-Type: text/plain. When Droplet detects that the response is in plain text format, it will parse the text and use the first line of text for the Droplet title. The rest will be converted into HTML code where multi-line-breaks will mark the ending and beginning of paragraphs, eg. <p></p>, single line-breaks will be replaced with <br> tags, and markdown link syntax will be transformed into hyperlinks.

Downloading Droplet#

You can download Droplet package at droplet/#download-support-thanks. Keep in mind that Droplet can be installed as a regular web plugin or as a web component on your website. Please read more about web components, if you haven't come across this technology suite in the past.

Download Package Contents#

dist/

Directory containing code that should be used in production environment. It's also the directory where you'll find code in optimal condition ready to be served. If you want to grab things quickly, this is where you'll look. This directory contains HTML files representing each Droplet theme (eg. droplet.html, whats-new.html, etc.).

src/

Directory which houses all code for staging and testing purposes. Basically, here you find the source code, where things are split into components and other logical parts to help in development process.

test/

A place where we store a few test cases as well as test material.

scripts/

Contains automation task scripts or utility scripts that automate or facilitate various development and maintenance tasks related to the project.

scripts/build.js

A JavaScript file with Node.js syntax used to run all tasks in order to build the source code into the distribution directory.

scripts/build-my-theme.js

A JavaScript file with Node.js syntax that builds just the special “My Theme” Droplet theme which is a template placeholder for your custom theme. See Building My Own Theme.

package.json and package-lock.json

Various metadata relevant to the project for the npm package manager.

Installation & Customization#

Droplet comes in two flavours – as a regular web plugin or as a web component.

<div id="droplet" data-title="Hello!">Some content here.</div>

<script type="module">
    import { Droplet } from './droplet.min.js';
    const droplet = new Droplet(document.getElementById('droplet'), options);
</script>

Installing As Web Component#

Keep in mind that in order to use Droplet as a web component you need to download the web component package. The main difference here is that we need to use the custom <drop-let> element name. In this case the ID attribute is not required.

<drop-let data-title="Hello!">Some content here.</drop-let>

<script type="module">
    import { Droplet } from './droplet.min.js';
    customElements.define('drop-let', Droplet);
</script>

Loading As JavaScript Module#

Droplet can also be loaded as a JavaScript module in case you want to use it in your JavaScript program as a module. This can be achieved no matter which flavour you are using, whether it's regular web plugin or web component.

<script type="module">

import { Droplet } from './droplet.min.js';

// Droplet class is available now.

</script>

Enabling Animations & Effects#

You can enable and control animations and effects by adding class names to the host element. The main class name which switches on the animation system is d-anim. Please note that there is a distinction between the animation system and effects. When used alone, the d-anim class name will only turn on the animation system, but will not enable the main effects, though some less significant effects (eg. for the breadcrumb items) will come to life. To fully fire all effects you need to use the effect class names along with the d-anim class name. The third part of the puzzle is effect direction control. With effects that initiate movement you can define which way the moving element should travel to.

<div class="d-anim d-film-track" id="droplet" data-title="Hello!">

We are using Film-Track effect above which is represented by the d-film-track class name.

Available Effects#

Name Class Name Direction Control Description Constraints

Film-Track d-film-track Yes Both cards move simultaneously into the same direction. Cannot be used with “Slide-Over”.

Slide-Over d-slide-over Yes The inbound card slides on top of the leaving card from the chosen direction. Cannot be used with “Film-Track”.

Cross-Fade d-cross-fade No The inbound card fades into the view as the leaving card fades out at the same time. Works alongside all other effects.

Slide-Over Behind Unlock d-slide-over-behind Yes As the inbound card slides into the view, the leaving card slides out to the direction the inbound card has entered from. Cannot be used with “Film-Track” or other “Slide-Over” extensions.

Slide-Over Hide Unlock d-slide-over-hide Yes As the inbound card slides into the view, the leaving card slides out and shrinks at the same time to the direction the inbound card entered from, appearing as if it's trying to hide and avoid the inbound card. Cannot be used with “Film-Track” or other “Slide-Over” extensions.

Slide-Over Blink Unlock d-slide-over-blink Yes The leaving card shrinks into the chosen direction and right before it totally disappears the inbound card grows into the view, appearing as if the leaving card was replaced by it. Cannot be used with “Film-Track” or other “Slide-Over” extensions.

Effect Direction Control#

All currently available effects (except cross-fade) additionally support direction control. Basically, it's a method to control which way you want the moving element to travel to. Droplet currently supports 4 main directions horizontally and vertically in perpendicular lines. In contradiction to the general effects system, there is a default behavior even when no effect direction class name is used. The default direction is right-to-left.

Direction of Travel CSS Class Name Description

Leftwards (Default) d-anim-left Right-to-Left animation

Upwards d-anim-top Bottom-to-Top animation

Rightwards d-anim-right Left-to-Right animation

Downwards d-anim-bottom Top-to-Bottom animation

Customizing Behavior & Function#

There is a distinction for how we can handle Droplet's options with the regular setup and when using it as a web component. While in regular setup one can declare a new instance of the Droplet class and pass option parameters into it, the web component only adds the Droplet class to the Custom Element Registry. To pass options into such system, one needs to add custom data attributes to the host element.

<drop-let data-title="Hello!" data-option-name="option_value"></drop-let>

Options#

Name Data Attribute Description Type Defaults To

captureInsideLinks data-capture-inside-links Whether all links should be automatically captured inside the Droplet content area. boolean true

useLinkTitles data-use-link-titles Whether the title that appears in the menu bar should be copied over from hyperlink's text content instead of taking it from resource location's data. <title> tag. boolean false

defaultEffect data-default-effect A space separated list of effects that will be used when no effect classes were added on the host element and effects were not customized through the hyperlink. null|string null

returnOppositeDirection data-return-opposite-direction Whether opposite direction should be used with effects when navigating backwards (note: opposite direction can be calculated individually based on from which direction a card came into view). boolean true

showMenuBar data-show-menu-bar What variant of the menu bar should be used, or whether the menu bar should be rendered at all. string|boolean - “breadcrumbs”, “navigation”, false breadcrumbs

requestTimeout data-request-timeout How long (in miliseconds) it should wait for a network response before the request is terminated manually. integer 10000

Stylesheet path (JavaScript object option not available) data-stylesheet Path to the stylesheet that should be loaded. Works in web component only. string “css/droplet.min.css”

defaultFragment data-default-fragment Fragment name. string “content”

variableHeight data-variable-height Whether the height of the container should change based on the size of the available content (cannot exceed container maximum height, though). boolean true

homeButtonText data-home-button-text Home button text. string “Home”

homeButtonTitle data-home-button-title Advisory title text for the home button. string “Go to the Home card”

backButtonText data-back-button-text Back button text. string “Back”

backButtonTitle data-back-button-title Advisory title text for the back button. string “Go back”

onEnd - Callback function to be triggered when card transition ends. callable|null null

Commonly Used Methods#

With a declared Droplet class, one can programatically run the commonly used methods. For example, to add a new card programatically, you would do the following.

const droplet = new Droplet(document.getElementById('droplet'), options);
droplet.populateContent('<p>Content for the next card.</p><p><a href="more-card.html">Show even more</a></p>', 'Hello!', 'd-slide-over d-anim-bottom');

Function Description Return Value

populateContent(html_content, title, effects) Starts a new card and populates it with the given HTML content. Promise object.

goBack(id, effect) Goes back to one of the previous cards. Promise object.

goBackByOne() Goes back to the previous card. Promise object.

reload() Reloads the current card. If current card was added programatically, nothing will happen. Promise object.

terminateRequest(whetherToLeaveBreadcrumb) Terminates the running request. void

goHome() Restores the initial state and closes all previous cards. Promise object.

Special Host Element Classes#

d-anim

Enables all animations (works along with effect classes). When effect classes are used, but the d-anim class omitted, none of the effects will work.

d-no-bar-at-start

When used, the menu bar will not be shown initially. If the menu bar is enabled, it will appear only when user progresses to the next card.

d-content-fade-outs

Enables content fade-outs at the top and bottom of the content area. Basically, it's a horizontal gradient line which offers a more subtle way for the content to hide behind the border edge. Use this carefully, because it can decrease your plugin's performance when animations are in action.

[all effect classes]

All effect classes must be added to the host element. See Available Effects for more information.

Special Classes Working Inside The Content Area#

d-prevent

When added to a hyperlink, it prevents the default hyperlink action to be intercepted by Droplet system.

d-button

Droplet button which talks to the theme in action. Normally used on hyperlinks. With all built-in themes this button is optimized to fit into the general look and feel of the working theme.

Special Content Area Hyperlink URLs#

These are special hyperlink URLs. When used inside Droplet's content area, they will trigger special functions.

#back

Navigates back to the previous card and closes the current card.

#home

Restores the initial state and closes all cards.

Running Package Tasks#

While totally optional, sometimes you might want to build the source files in case you are putting together your own version of Droplet or you want to simply create your custom theme.

To meet the system requirements, install Node.js and npm package manager.

When you have the above installed and ready, perform the following steps.

• Launch your OS's terminal emulator.
• Navigate to the directory where you have your Droplet package files.
• Run npm install to install all required Node.js modules (they will be saved into a new node_modules/ directory).
• Run node ./scripts/build.js to process all build tasks.
• Alternatively, run node ./scripts/build-my-theme.js to build just a single custom theme (see Building Your Own Theme).

Droplet uses Clean CSS and Uglify JS to conduct main build tasks. These will be installed automatically into the node_modules/ directory by npm.

Building Your Own Theme#

• Get acquainted with download package contents summary, if you haven't done that yet.
• Familiarize with the running package tasks procedure and make sure your system meets all the requirements.
• Open file src/css/my-theme.css from the Droplet package files, read through all the comments, and choose which components you want to add to your theme.
• Next, open file src/css/components/variables-my-theme.css and amend the variable values to your liking.
• Under the Droplet package path run command node ./scripts/build-my-theme.js in your OS's terminal emulator.
• Once the above is successfully completed, your custom theme will be build into the dist/css/my-theme.min.css file.
• Launch dist/my-theme.html through your web server to view the resulting work.