Pathfora JS

Pathfora JS is a lightweight SDK for displaying personalized modules on your website, it integrates with your Lytics account to track user actions, and conditionally display modules based on your users' audience membership. For more info and full configuration examples check out the full documentation.

Modules

There are 4 types of modules and 4 layouts currently supported.

Modules can be of the following types:

• Message - Module with a simple text message.
• Form - Module with a form to capture user information, can contain fields for name, email, title and message.
• Subscription - Module with a single input field, email.
• Gate - Module which gates the page behind it, the user cannot view the page until they enter information into the gate form. Can contain form fields for name, email, organization, title.

Modules are displayed in one of following layouts:

• Modal - A large size module with an overlay behind it - meant to cover a substantial area of the browser window, so that it demands attention from the user.
• Slideout - A medium module which slides from either side into the window.
• Bar - A thin module which appears at the top or bottom of the browser window.
• Button - A small module which only allows for a short call to action and a single click action.

General Usage

1. Add Lytics tracking tag to your website, and import pathfora.js file.

<!-- Your Lytics JS Tag -->
<script src="https://c.lytics.io/api/tag/YOUR LYTICS API KEY/lio.js"></script>

<!-- Pathfora Tag -->
<script src="http://c.lytics.io/static/pathfora.min.js"></script>

2. Set up your module configuration, a simple example is provided below. See the documentation for a full list of settings and examples.

// example: show a bar module with a button leading to a new products page

var module = pathfora.Message({
  id: 'bar-valued-customers',
  layout: 'bar',
  msg: 'Thanks for being a valued customer, please check out our new products.'
  cancelShow: false,
  okMessage: 'View Now',
  confirmAction: {
    name: "view now",
    callback: function () {
      window.location.pathname = "/new-products";
    }
  }
});

pathfora.initializeWidgets([ module ]);

Development

Pathfora uses NPM for package management, and Gulp to manage build tasks.

Install Dependencies:

$ npm install --global gulp-cli
$ npm install

Gulp tasks:

• gulp build - minify LESS files and uglify js files in the src directory, and place output in dist directory.

• gulp - runs the build tasks above and watches for any changes in the src directory, files are served on localhost port 8080.

• gulp docs - see below.

• gulp local - reads some config params from an optional local file, .env.json and builds and watches as with the default gulp task. This can allow you to test CSS changes locally (by default dist/pathfora.min.js loads the most recently deployed CSS file) or override the Lytics API URL.

  Example .env.json file, (using local CSS):

  {
    "APIURL": "https://api.lytics.io",
    "CSSURL": "http://localhost:8080/dist/pathfora.min.css"
  }

Documentation

Soon we will be hosting Pathfora documentation externally, for now, documentation can be run locally using the gulp docs task. Our docs are powered by mkdocs which you must install before running the gulp docs task.

$ pip install mkdocs
$ gulp docs

Documentation will be served on localhost port 8000 while running this task.

The source code for all the examples provided in the documentation can be found in docs/docs/examples/src. Preview images for the examples live in docs/docs/examples/images.

The docs task will walk through every .js file in the examples source directory and compile it as a working html example in docs/docs/examples/preview using a handlebars template. These js files also get used as the source code to populate the <pre> elements within the docs.

This allows us to keep our source code in one place. Changing a js file in the examples source folder will change the code snippet in the docs and update the example .html file.

Testing

Pathfora uses Jasmine as a test framework, and Karma to run tests. Before running tests, or commiting changes be sure to run gulp build instead of gulp local, or tests will fail due to mismatching URLs.

Running tests:

$ gulp build && karma start --single-run --browsers PhantomJS