Documentation

Last updated: Oct 22nd, 2016

Folly.js Configuration

Hosted Script

It's important to note that folly.js is a hosted script. This means you should reference the file directly on our servers, not host it yourself. This is important because we constantly make small tweaks to folly.js to fix bugs, increase performance, and all around make things more efficient.

Including the script

To get started with Folly, simply include this script at the top of the <head> section of every page on your website:

<script src="https://plugins.folly.io/release/folly.min.js" folly-sitekey="your-sitekey"></script>

Make sure you replace your-sitekey with your actual site key you were emailed when you signed up.

Advanced configuration

Folly is configured by specifying attributes on any element on the page. We recommend specifying the attributes on the script tag itself whenever convenient, but any element on the page, such as an empty <div>, may have these attributes.

folly-domain="example.com"

The folly-domain attribute used in the example above definitively tells Folly what domain to pull data from. While technically not required (if not present, Folly will detect and use the domain of the current page), use of the folly-domain attribute is highly recommended.


folly-mode="js"

The folly-mode attribute specifies whether the data-injection is done server-side (folly-mode="server") or client-side (folly-mode="js"). js is the default mode. Server side data injection allows the webpage to be delivered to the client slightly more quickly, and can save on bandwidth. However, it requires a more advanced implementation, including caching strategies. To read more about server side injection, see Server Side Rendering.


folly-auth="/account/signin"

The folly-auth attribute used to specify a custom authentication endpoint, overriding Folly's default login process. Jump to the Custom Authentication section for more details.


folly-disable-login-button

Include the folly-disable-login-button attribute to hide the login button in the bottom corner of the screen. Instead, users must type #edit at the end of the URL in the address bar.

Editable Elements

With Folly, you define what exactly on the page is editable by attaching an attribute to the element you wish to be editable. There are three such attributes, explained in detail below.

Data Keys identify editable elements on the page. They look and behave the same way as relative URLs. More Info

Rich Text Editing folly-html="[data_key]"

Enable rich editing on this content. Add lists, drop in images, add headers, etc.

Example:
<div folly-html="page-content">This is my default content for this page</div>

Plain Text Editing folly-text="[data_key]"

Sometimes you want the user to be able to edit text, but you need a consistent style. Works great when editing titles, tags, button text, captions, etc.

Example:
<button type="submit" folly-text="/shared/main-call-to-action">Click Here</button>

Uploading and Editing Images folly-img="[data_key]"

To allow an image to be uploaded (drag-and-drop or pick-a-file) or edited, use this attribute on <img> tags, or on a <div> with the background-image inline css style set.

Use folly-img-params="[image_parameters]" to specify the default parameters that should be used to render this image. Folly uses imgix for all our image processing, so you can read more on their docs for details on everything you can do. If you do not specify this parameter, we will automatically populate it from your default source URL.

The most popular parameters you are likely to use are to set the size of an image. For example:

<img src="http://placehold.it/350x150" folly-img="/docs/editable/example-1" folly-img-params="w=350&h=150" />
allows a full-size image to be uploaded, but a 350x150 version of it will be rendered server-side and sent to the client. This prevents your users from having to properly resize images before uploading them.

Data Keys

When tagging elements as editable with folly attributes, you must specify a data key as the value of the attribute to uniquely identify the element.

Data keys follow the same format as relative URLs, and are relative to the page they appear on.

  • A data key that starts with a forward slash (/) will be relative to the website's root.
    Example: The data key
    /logo
    on the page
    https://www.example.com/docs/code
    will have a absolute path of /logo.
  • A data key that starts with two dots followed by a forward slash (../) will start one directory up from the current directory.
    Example: The data key
    ../logo
    on the page
    https://www.example.com/docs/code
    will have an absolute path of /docs/logo.
  • A data key that does not start with dots or a slash will start on the current page.
    Example: The data key
    logo
    on the page
    https://www.example.com/docs/code
    will have an absolute path of /docs/code/logo.
Data keys on the root page of your site (http://www.example.com/) will begin in the /index directory.