README.md

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 5 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.
• Inline - A module which can be inserted into an existing div on a page.

General Usage

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

<!-- Pathfora Tag -->
<script src="https://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 = new 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]);

Communication

slack - There’s a slack channel. Feel free to join and collaborate!

Contributing to Pathfora

See contribution notes

Development

Pathfora uses yarn for package management, rollup as a module bundler, and Gulp to manage build tasks.

Install Dependencies:

Note: Node v12 is not compatiable with the current set of dependencies. See gulpjs/gulp#2324

$ yarn global add gulp-cli
$ yarn install

Gulp tasks:

• gulp build - minify LESS files. Bundle, lint and uglify js modules in the src/rollup directory, and place output files 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 lint - lint all the js source files with the rules defined in .eslintrc.

• 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"
  }

Useful scripts:

• yarn test - builds and activates Karma test runner on PhantomJS.

• yarn run clean - removes files from the ./dist folder for a clean build.

• yarn run build:prod - sets NODE_ENV to production and builds minified files in ./dist folder.

• yarn run prod - run tests, clean and rebuild the /dist folder. This is built on top of the gulp build command. Important to know that this sets the NODE_ENV to production, removing instabul instrumentation for code coverage. Currently, this is the default command used for our Travis CI.

Documentation

Documentation for the most recent release is available here.

You can also view and add to the docs by running the gulp docs task. Our docs are powered by mkdocs which you must install before attempting to run the docs.

$ 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 are stored 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 may fail due to mismatching URLs.

Running tests:

$ yarn run test

License

MIT Copyright (c) 2017, 2016, 2015 Lytics