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.
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.
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:
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.
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
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.
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.
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#
- 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.
- 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.
- A place where we store a few test cases as well as test material.
- Contains automation task scripts or utility scripts that automate or facilitate various development and maintenance tasks related to the project.
- 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.
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.
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.
We are using Film-Track effect above which is represented by the
d-film-track class name.
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.
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.
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.
Special Host Element Classes#
- Enables all animations (works along with effect classes). When effect classes are used, but the
d-animclass omitted, none of the effects will work.
- 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.
- 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#
- When added to a hyperlink, it prevents the default hyperlink action to be intercepted by Droplet system.
- 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.
- Navigates back to the previous card and closes the current card.
- 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.
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.
npm installto install all required Node.js modules (they will be saved into a new
node ./scripts/build.jsto process all build tasks.
- Alternatively, run
node ./scripts/build-my-theme.jsto build just a single custom theme (see Building Your Own Theme).
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.cssfrom 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.cssand amend the variable values to your liking.
- Under the Droplet package path run command
node ./scripts/build-my-theme.jsin your OS's terminal emulator.
- Once the above is successfully completed, your custom theme will be build into the
dist/my-theme.htmlthrough your web server to view the resulting work.