Smooth.JS
Tired of loading feed items directly from your backend? Smooth.js uses super-simple XMLHttpRequests to dynamically and smoothly serve content instead!
Concept
Smooth.JS takes a URL, a container and a template. It queries the URL (which should return a JSON array) and outputs the template into the container for each item in the array (the amount to output at a time is specified in the options).
Smooth.JS is useful, for example, when loading a user's timeline. Instead of loading every single feed item into the page at once (which could be very slow), you can use Smooth to load them systematically and display a 'Load more' button to load the next batch. The button can be made to disappear when the array has been completely exhausted.
Installation
To install Smooth.js, you can use NPM and then link the installed module into your HTML file's head:
npm i smooth-javascript
My First Smooth Project
You can also use a CDN (we recommend jsDelivr):
My First Smooth Project
Starter
Smooth.JS is a complex and expanding JS library which supports a variety of usage complexities. The following starter file, however, shows the simplest implementation of Smooth. It gets entries from a placeholder API and outputs them into a container 5 at a time, and hides the 'More' button when all items have loaded:
My First Smooth Project More...
This page can be found at examples/index.html.
Reference
Smooth()
Intializes Smooth.JS class with specified URL.
Parameters
Parameter | Purpose |
---|---|
URL [String] | Specifies the JSON API that Smooth should query. Requesting this page should return a JSON array, like the example in the Starter. |
Usage
var smooth = url;
Returns
Smooth.JS class object, must be assigned to variable.
.setOptions()
Sets custom options for using Smooth with a specified JSON object.
Parameters
Parameter | Purpose |
---|---|
Options [JSON] | Specifies custom options in the form of a JSON object. See JSON information below. |
Options
Field | Purpose | Required | Default |
---|---|---|---|
step [Integer] | The amount of items Smooth should load on each call. Defaults to 5. | Yes | None |
verb [String] | Either "GET" or "POST" - the HTTP verb to use in the query. |
Yes | None |
useAsync [Boolean] | true - XMLHttpRequest should be async; false - it should be sync. |
No | true |
urlParams [String] | Parameters to place into the URL. This shouldn't include the preceding ? . These will act as POST parameters if the verb is set to POST |
No | null |
Usage
var smooth = ;smooth;
Returns
None
.setTemplate()
Sets the template that should output for each item in the specified container.
Parameters
Parameter | Purpose |
---|---|
Template [String] | A special string of HTML to output for each item. See below for custom values. |
Template
The template can be simple HTML:
smooth;
However, you can also use {{variable}}
to output any field from the JSON object per item:
smooth;
You can also use [[javascript]]
, which will eval() any JS inside it and place the result in the output. For example:
smooth;
The specified JS will be evaluated individually for every single item.
Usage
var smooth = ;smooth;smooth;
Returns
None
.setContainer()
Sets the container to output parsed templates into for each item.
Parameters
Parameter | Purpose |
---|---|
Container [Element] | A DOM element to output each (parsed) template into per item. |
Usage
var smooth = ;smooth;smooth;smooth;
Returns
None
.more()
Loads the next (or first) batch of items, as specified by options (which must be set before this function is called).
Parameters
Parameter | Purpose |
---|---|
Callback [Function (error)] | Function to execute on completing start of all request or at first error. |
Usage
var smooth = ;smooth;smooth;smooth; smooth;
sm_object_render
Event: Dispatched to window
when a single item has been rendered.
Usage
window;
sm_sequence_rendered
Event: Dispatched to window
when an instance of .more()
has finished outputting items.
Usage
window;
sm_all_rendered
Event: Dispatched to window
when all items have been rendered (the JSON array has been exhausted).
window;