Poly JS Utils

A set of common client-side tools used in Hearsay Sites themes and locators.

The goal of this module is to encapsulate common patterns that have emerged during the development of themes for Hearsay Sites, and provide an API for working with the data that is passed to sites from our servers.

Getting Started

To start working with poly-js-utils, install the module as a dependency in the consuming theme project.

npm install -S poly-js-utils

Once installed, you can access the various submodules in the theme's main scripts.

/* app/js/scripts.js */
var $ = require('jquery');
var _ = require('underscore');
var JSContext = require('poly-js-utils').JSContext;
var ViewHelpers = require('poly-js-utils').ViewHelpers;
var template = require('./templates/header.jst.html');

// Make profile data and helpers available to template, and render to page.
var templateData = _.extend(JSContext.getProfile(), ViewHelpers);
$('#header').append(_.template(template)(templateData));

<!-- app/js/templates/header.jst.html -->
<div id="header">
    <img src="<%- resize(profile, 'profile_photo', 250) %>">
    <div><%- first_name + ' ' + last_name %></div>
</div>

API Reference

Asynchronous Raven

To use an asynchronous version of Raven, follow these two steps:

1. gulp include the src/raven-async.js file from this package
2. call Raven.config().load() as normal

You can optionally define a string variable named 'ravenOverrideVersion' before the include which will override the version specified in this library's source code.

JSContext

JSContext provides getters for the various data that are loaded into each site by Hearsay, such as a site's profile, available categories, news posts, events, etc.

getProfile

Retrieves profile data, if available.

JSContext.getProfile()

Params: None

Return Type: object

Example Profile:

{
    slug: 'fbar',
    first_name: 'Foo',
    last_name: 'Bar',
    profile_photo: 'https://placehold.it/350x150',
    address: {
        street: '185 Berry St.',
        city: 'San Francisco',
        ...
    },
    ...
}

getThemeData

Retrieves theme data, if available.

JSContext.getThemeData()

Params: None

Return Type: object

Example Theme Data:

{
    corporate_logo: 'https://placehold.it/150x150',
    about_company: 'Lorem ipsum dolor sit amet, <b>consectetur adipisicing</b> elit.',
    ...
}

getLocatorLink

Retrieves link url (string) to organization locator, if available.

JSContext.getLocatorLink()

Params: None

Return Type: string

getBaseLink

Returns url (string) for site.

JSContext.getBaseLink()

Params: None

Return Type: string

getSlug

Returns the url slug (the agent-specific string following the organization-specified domain) for the site.

JSContext.getSlug()

Params: None

Return Type: string

getPosts

Retrieves list of content posts.

JSContext.getPosts(limit|options)

Params:

• limit (int, optional): Maximum number of posts to retrieve.
• options (object, optional):
  • maxPosts (int, optional): See limit
  • dateFormat (string, optional): Moment.js formatter string to apply to post publish dates [default: "MMMM DD YYYY, h:mm a"]

Return Type: [object]

Individual posts are of the form:

{
    formattedPublishDate: <string>, // Ex: "July 26 2016, 10:06 pm"
    id: <int>,
    image: <url>,
    image_resize_ready: <boolean>,
    link: <url>,
    link_summary: <string>,
    link_title: <string>,
    message: <string>,
    organization_id: <int>,
    publish_date: <date_string>, // Ex: "2016-07-27T05:06:47",
    site_id: <int>
}

Image, link and and message fields are all optional and should be handled accordingly.

getEvents

Retrieves list of events.

JSContext.getEvents(limit|options)

Params:

• limit (int, optional): Maximum number of events to retrieve.
• options (object, optional):
  • maxEvents (int, optional): See limit
  • dateFormat (string, optional): Moment.js formatter string to apply to event date [default: "MMMM DD YYYY, h:mm a"]
  • dateEndFormat (string, optional): Formatter string for event end date [default: "MMMM DD YYYY, h:mm a"]

Return Type: [object]

Individual events are of the form:

{
    details: <string>,
    event_date: <date_string>, // Ex: "2016-09-01T22:00:00",
    event_date_end: <date_string>,
    event_name: <string>,
    formattedDate: <date_string>,
    formattedDateEnd: <date_string>,
    formattedDateRange: <date_range_string>,
    id: <int>,
    location_coords: [<int>, <int], // latitude and longitude
    location_text: <string>,
    organization_id: <int>,
    photo: <url>,
    photo_resize_ready: <boolean>,
    publish_date: <date_string>,
    rsvp_info: <string>, // can be phone, email, etc. depending on type
    rsvp_link: <string>, // `rsvp_info` prefixed by protocol for type - ex: tel:5555555555
    rsvp_type: <string>, // phone, email, etc.
    site_id: <int>
}

getEvent

JSContext.getEvent(eventID, options)

Params

• eventID (int): ID of desired event
• options (object, optional): See similar options in getEvents
  • dateFormat
  • dateEndFormat

Return Type: object

getCategories

Returns a map of category names onto their available options.

JSContext.getCategories()

Params: None

Return Type: object

Example:

// categories
{
    all_languages: {
        'en': 'English',
        'es': 'Spanish',
        'fr': 'French',
        ...
    },
    states: {
        'AL': 'Alabama',
        'AK': 'Alaska',
        ...
    }
}

In general, you can use ViewHelpers.getTagDisplayValue to avoid working with categories directly.

getCategoryMap

Returns an object mapping canonical names of fields to their source categories. Useful when retrieving display values for fields that are populated from select or multi-select widgets. In general, use ViewHelpers.getTagDisplayValue instead, which wraps getCategoryMap and getCategories.

JSContext.getCategoryMap()

Params: None

Return Type: object

Example category map (see getCategories for matching categories):

{
    languages: 'all_languages',
    states_licensed: 'states'
}

getGoogleMapsKey

Retrieves Hearsay browser key for Google Maps API.

JSContext.getGoogleMapsKey()

Params: None

Return Type: string

getKalturaPartnerId

Used for Kaltura Client Libraries

JSContext.getKalturaPartnerId()

Params: None

Return Type: string

ImageResizing

When images are uploaded through the Hearsay platform, they are preprocessed and saved in multiple sizes. ImageResizing.resize takes the url for the original image, as well as a desired width, and returns a url for the closest available resized image from those output by Hearsay's image resizer.

resize

ImageResizing.resize(data, photoKey, targetWidth)

Params:

• data (object): Object containing key photoKey with a url value for the photo to be resized
• photoKey (string): Key in data for photo url
• targetWidth (int): Desired width

Return Type: string

Resizing is also available in ViewHelpers as ViewHelpers.resize.

Example Usage

For the data below, let's say we want to retrieve our profile photo to display in a thumbnail image thats 125 pixels square.

// profile
{
    ...
    profile_photo: 'https://hsl-pnw-downloadable-files.s3.amazonaws.com/99999/abcdefg.jpg',
    ...
}

We simply call resize with our desired parameters, and it outputs a url that targets a resized version of our original image.

/* app/js/scripts.js */
var JSContext = require('poly-js-utils').JSContext;
var ImageResizing = require('poly-js-utils').ImageResizing;

var profile = JSContext.getProfile();

var resizedUrl = ImageResizing.resize(profile, 'profile_photo', 125);
// ==> https://hsl-pnw-downloadable-files.s3.amazonaws.com/99999/abcdefg-width-154.jpg

Note that the resized url indicates that the image will have a width of 154 pixels. The image is not available at a width of 125 pixels, so resize outputs the closest available width (rounding up), which happens to be 154 in this case.

KalturaHelpers

KalturaHelpers provides useful functions for initializing and modifying the Kaltura video player.

init

Initializes the Kaltura video player for any videos in the queue.

KalturaHelpers.init() KalturaHelpers.init(kalturaCallback)

Params:

• callback (func, optional): The callback to be called once the Kaltura videos are fully loaded. This is a useful place to use KWidget (see Kaltura documentation)

Return Type: None

Example:

function kalturaCallback() {
    kWidget.addReadyCallback(function( playerId ){
	var kdp = document.getElementById(playerId); 
        kdp.kBind("openFullScreen", function(){
            console.log("Full screen OPEN");
        });
        kdp.kBind("closeFullScreen", function(){
            console.log("Full screen CLOSED");
        });
    });
}

KalturaHelpers.init(kalturaCallback);

queueVideoForLoading

Adds the specified (by video ID) video to the loading queue.

KalturaHelpers.queueVideoForLoading();

Params:

• videoId (string, required): The video ID (not HTML ID) of the video you would like to add to the queue

Return Type: None

Example:

KalturaHelpers.queueVideoForLoading("0_k7375t06");

MapTools

Most themes have pretty similar requirements for displaying maps, so the MapTools submodule is provided to cover common cases, and can be customized as necessary.

googleGeocodeAddress

Calls out to Google's geocoding API with address and runs callback with the response (a set of latitude/longitude coordinates).

MapTools.googleGeocodeAddress(address, callback)

Params:

• address (string): String representation of address
• address (object): Object representation of address
• callback (function): Function called upon response from Google Geocoder API. Params:
  • latlng ([int, int] | false): Lat/long pair corresponding to address, or false if geocoding failed
  • status (google.maps.GeocoderStatus): Only present in case of geocoding failure

Return Type: None

Address objects are of the form:

{
    street: <string>,
    suite: <string>,
    city: <string>,
    state: <string>,
    country: <string>,
    zip_code: <int>
}

showGoogleMap

Displays a customizable Google map on the page.

MapTools.showGoogleMap(latlng, containerID, useDefaultMarker, options)

Params:

• latlng ([int, int]): Lat/lng pair to center the map around
• containerID (string): ID of element to contain map
• useDefaultMarker (boolean, optional): If true, map will be shown with a marker placed at the center (latlng) [default: true]
• options (object, optional): Google Maps options literal. Uses Google defaults, extended with:
  • zoom: 15
  • mapTypeControl: false
  • scrollWheel: false

Return Type: Google Map

showStaticGoogleMap

Displays a static Google map on the page with a marker at the center.

MapTools.showStaticGoogleMap(latlng, containerID)

Params:

• latlng ([int, int]): Lat/lng pair to center the map around
• containerID (string): ID of element to contain map

Return Type: None

Utils

Provides various utility functions used across products/themes/etc

formatEventDates

Returns a date range string for events in the following formats depending on certain conditions being met:

All full dates are formatted with the specified dateTimeFormat or the default. All stand-alone times are formatted with the specified timeFormat or the default.

• Only a start date: full start date and time with period
• Start date and end date are the same and times do not cross am/pm (period): full start date and time without period - end time with period
• Start date and end date are the same and cross am/pm: full start date and time with period - end time with period
• Start date and end date are different: full start date and time with period - full end date and time with period

Params:

• startDate (string): Start date of the event, typically in YYYY-MM-DDThh:mm:ss format
• endDate (string): End date of the event, typically in YYYY-MM-DDThh:mm:ss format
• dateTimeFormat (string, optional): Moment.js formatter string to apply to full datetimes in the range string [default: "MMMM DD YYYY, h:mm a"]
• timeFormat (string, optional): Moment.js formatter string to apply to end times in the range string [default: "h:mm a"]

Return Type: string

loadGoogleMapsScript

Used to load Google Maps after the page has loaded. This takes a callback parameter that can be used if you need a callback once Google Maps is loaded. This function should go inside something like $(document).ready().

Params:

• key (string, optional): The Google Maps API key
• callback (string, optional): The function name of your callback

Return Type: None

Contributing

Installing dependencies

npm install

Running tests

npm test

Example app

A very basic example app using poly-js-utils can be viewed by running npm run example.

Documentation

API Documentation

To generate this documentation run npm run gendocs which will create api.md from JSdoc comments

Release process

To release a new version of this project into hearsay's npm registry, you have to increase the version in the package.json first.

You can see the github process under the .github/workflows/publish-release.yml file.

The publishing and release will happen automatically when you merge your feature branch into the master.

After the merge, you can follow the process under the Actions menu in github.