Pulsar as a Platform

Overview

Pulsar is platform where you can customize the UI to provide your users with a familiar and branded experience, even when completely offline.

• Develop your own reports, order forms, or even a fully customized home page (dashboard) using industry-standard HTML/CSS/Javascript

• Deploy the bundled webapp to a Salesforce content library folder in your org and set user access permissions there

• Pulsar will sync the content library folder and webapp (subject to user permissions), and present it to your users in a manner you devise

Pulsar Platform Architecture

Pulsar Platform High Level Architecture

Luminix has developed Pulsar-specific Javascript APIs (Pulsar JSAPI) so that your webapp can communicate with the underlying Pulsar database.  This API makes it possible for you to develop full-featured webapps that can work in offline mode.

Through the Pulsar JSAPI, your embedded web app(s) have the ability to create, read, update, and delete records (and much more) even when completely offline.  Changes will be reflected on your Salesforce org when Pulsar next syncs.

• Simple examples of the Pulsar JSAPI are available on GitHub.

The below picture illustrates the data path from your custom webapp making a CRUD request through the Javascript API to the Pulsar database.

Open

Ways of showing your custom UI

There are several ways for your users to access your embedded webapp, listed here and documented in sections below:

• Naturally a user can navigate to the Content Library tab in the Pulsar App and open the webapp from there.  This requires no further configuration on your part, but can be a little difficult for your users to discover.

• You may wish to display a tab icon on the Pulsar home page that will launch your webapp when a user clicks on it

• You may wish to put a button on a record detail page and have your webapp launched from that detail page (and supplied with the record ID)

• You may wish to display your webapp as the home page (instead of showing the Pulsar default home page with various tabs)

Example Webapp

Here is an example webapp that shows what a user typically might expect.

The user clicks on the appropriate tab from the Pulsar home page to launch the webapp.

Open

Note that to facilitate quick access to your webapp, Pulsar lets you create an icon on the Pulsar home page. (This particular configuration and other ways to access your webapp are explained in following sections).
Pulsar shows a new page that displays the embedded webapp.
Notice how this example webapp lets you choose an Account and select Products — these are read from the Pulsar Database using the Pulsar JSAPI.

Notice that the HTML order form has logic built into it that recognizes that the third product qualifies for a promotion.

Show Custom UI Tab Icons on Home Screen

Launch your webapp from the home screen

You can provide quick link to your web app(s) as a tab icon(s) on the Pulsar home page.

You need to configure three different Pulsar Settings to show your webapp(s) as a tab icon(s).

1. Provide the values for each webapp Document ID which you want to show as an icon on Pulsar home page:

2. Now define how each of these tabs should look: 

The example webapp above used the following image:

3. Now, specify where to place the content library tabs in the list of special home screen icons.

Show Custom UI Button from Record

Launch your webapp from a record

Not only can you define a tab on the Pulsar home page, but you can define a button on a particular record, so that the user can open a custom webapp from a particular record.

The advantage of this is that the Record ID will be passed as an argument to the webapp which can then be used to look up relevant information and display (without the user having to specifically select the record).

Here is how you can configure Pulsar Settings to show your webapp from a record.

Let's say we wish to display the custom webapp from an Account object. (Note that it could be displayed on any object – just replace Account in the following examples with the API name of any object). 

1. Find the Id of the document you wish to display on the Account page. The easiest way is to navigate to the document in the content libraries and record the DocumentID from the URL in the browser’s navigation bar.

Example
https://na15.salesforce.com/sfc/#version?selectedDocumentId=069i0000001i3wP

2a. Add a Pulsar Setting with the following key and use the DocumentID as the value. Additional documents may be added to the setting, one per line or separated by commas.

2b. If you would like to restrict this functionality to only certain record types (for example, a record type with devloper name ‘Account_Type_1’), you would use the following syntax for the key.

3. Optional - Attach a new image as icon on doclist

Example Screen

Getting the RecordId in Javascript

Referencing the record ID from your webapp

The record Id is passed to the webapp using URL query parameters. The parameter name is ref_id and it is accessed from Javascript based on the URL string. See the following example:

Replace the Pulsar home page with your custom UI webapp

Launching your webapp as the main experience

Rather than display the Pulsar default home page showing the tab grid, you can display your custom webapp immediately after your users login.  To enable this, you need to configure pulsar.home.webContent to reference the document Id you want displayed.

Home Screen App Best Practices

• Sync:

  • Don't assume that your organization is fully synced when your app first starts

  • Note that Pulsar may need to initiate a sync to get the document specified, and that sync may still be ongoing

  • When starting, your app should check for an ongoing sync or if sync is needed

  • We highly recommend that your app blocks your own UI when sync is running

• UI:

  • Pulsar will not draw a top toolbar (and therefore with none of the usual buttons there)

  • You may choose to provide your own top toolbar with actions for the user (e.g., a Javascript "refresh page" button)

  • Pulsar will draw the default home screen (bottom) toolbar with full functionality (e.g., the online status and settings page buttons)

  • If you would like to enable access to the Salesforce apps and tabs, you can do that with the pulsar.home.toolbar.enableAppBrowser Pulsar Setting.  If enabled, this will show a button in the home screen (bottom) toolbar giving access to the apps/tabs.

Pulsar Settings

Bundling and deploying your webapp as .pulsarapp format

Video - Bundling your Pulsar webapp

Bundling your webapp for deployment

Trivial web apps can be created with a single .html file (with in-line HTML, CSS, and Javascript).  But this in-line approach hits serious limitations when the complexity of your webapp grows even just a little bit.

Luckily bundling all your resources (HTML, CSS, Javascript, images, fonts, etc) for deploying in Pulsar is easy.  Simply zip up your components in one file with the extension .pulsarapp -- Pulsar will unzip and load the top-level index.html file (which itself can reference the other bundled scripts and resources).

So essentially there are just 2 requirements for a bundled webapp:

1. Name your zipped webapp with a .pulsarapp file name extension

   1. NOTE: If you are having trouble loading your webapp, double-check that the File Extension is listed as "pulsarapp" on the File Detail page.

   2. One way to accomplish this is through the command line:

      1. ^{zip -r myapp.pulsarapp .}

2. An index.html file must exist at the top level of the zipfile (that is the single entry point to your web app)

   1. NOTE: when Pulsar unzips and launches your webapp, the toplevel index.html file is renamed as <DocumentId>.html, (renamed with its Salesforce document Id)

Here, for example is a listing for a zipped MyWebApp.pulsarapp bundle:

Once you have zipped up your webapp, named with a .pulsarapp file extension, you simply upload it to a content library folder in your Salesforce org.

You can control access to the webapp for different users by using Content Library folder permissions on Salesforce.

When your users next sync Pulsar, they will pick up the new/changed version of your webapp.

Multiple webapps and namespacing

TL;DR: multiple .pulsarapp webapps need to ensure that zipped file path names are unique between them (except for the toplevel index.html) to avoid file path name collisions.

Your organization can supply multiple .pulsarapp webapps that display at different times across different pages.  By design, Pulsar unzips all webapps to the same toplevel directory (on a per-login-user basis).  Because all webapps running for a particular user share this same runtime location, you need to ensure that file path names in each .pulsarapp are distinct from each other (except for the index.html which gets renamed).

Let's imagine the following problematic scenario.  You have both App1.pulsarapp and App2.pulsarapp.  These both bundle a js/lib.js file.  Now consider the possibilities:

1. If the two js/lib.js files are completely different libraries, then the webapp that is unzipped first will break after the other one is unzipped (and the first js/lib.js is overwritten with the other)

   • You should make sure these different libraries are named differently

2. If the two js/lib.js files are different versions of the same library, then subtle bugs may result.  Possibly one webapp expects version 1.0, but the other expects version 1.1 of the library.

   • You should remove the js/lib.js from both webapps and re-bundle it as a shared resource – see the Global Shared Resources section below.

3. If the two js/lib.js files are identical versions of the same library, this is a ticking timebomb.  The next time you update one library but not the other, you hit problem #2 above.

   • Ditto to rectification for #2 above

Multiple webapps and embedding

It is possible to have one .pulsarapp webapp reference and "embed" another, possibly in an <iframe/>.  Document soon

Global shared resources 

Bundling global resources.zip

You can bundle various common resources (HTML, CSS, Javascript, images, fonts, etc) independently of your individual .pulsarapp webapps so that these resources can be shared among them all.