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.

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

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.

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.

The Pulsar JSAPI allow you to create rich interactions with the local database, enabling you to run your business transactions completely offline.  Example code is available on GitHub.

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:

Name

List Of Home Page Content Library Tabs

Key

pulsar.home.contentLibraryTabs

Value

(List of) 15 or 18 digit Document ID(s) for .pulsarapp files, separated by newlines or commas/semicolons

Default Value (if any)

 

Compatibility

iOS
Windows
Android

Description

Value should be a list of Document IDs separated by new lines or commas. You can grab these IDs from Salesforce backend.

Notes/Comments

Example list of salesforce document IDs: 069E00000024nI0, 069E00000025nI0,...

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

Name

Tab Definition For Document

Key

pulsar.home.contentLibraryTabs.<DocumentID>

Value

R,G,B integer tuple

Default Value (if any)

 

Compatibility

iOS
Windows
Android

Description

Value should be a RGB code for the color of the background of the tab

Notes/Comments

Example Key: pulsar.home.contentLibraryTabs.069E00000024nI0

Example Value: 52,17,85

After Saving this setting, you can attach a 64x64 pixel icon.

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.

You can choose contentlibrarytabs position based on where you want to show the webapp icons on Pulsar Home screen.

Name

Home Screen Icons

Key

pulsar.home.topPositions

Value

List of special icons and tab positions, separated by newlines or commas/semicolons

Default Value (if any)

 

Compatibility

iOS
Windows
Android

Description

 

Notes/Comments

Example Value: user, calendar, tasks, documents, contentlibrarytabs

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.

Name

Show Tabs on Object Detail Screen

Key

pulsar.layout.<ObjectAPIName>.doclist

Value

List of DocumentIDs (e.g., 069i0000001i3wP), separated by newlines or commas/semicolons

Default Value (if any)

 

Compatibility

iOS
Windows
Android

Description

This setting will add a button to the toolbar shown when you select an Account. You will see the name of the document in a popup list, and selecting that document will open the document.

Notes/Comments

Example Keys: pulsar.layout.Account.doclist and pulsar.layout.Custom_Obj__c.doclist

Example Values: 069i0000001i3wP;069E00000024nI0

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.

Name

Show Tabs on Object Detail Screen

Key

pulsar.layout.<ObjectAPIName>.<RecordTypeName>.doclist

Value

List of DocumentIDs (e.g., 069i0000001i3wP), separated by newlines or commas/semicolons

Default Value (if any)

 

Compatibility

iOS
Windows
Android

Description

 

Notes/Comments

Example Keys: pulsar.layout.Account.Account_Type_1.doclist and pulsar.layout.Custom_Obj__c.A_Record_Type.doclist

Example Values: 069i0000001i3wP;069E00000024nI0

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

Name

DocListIcon Setup

Key

pulsar.layout.<ObjectAPIName>.doclist.icon

Value

 

Default Value (if any)

 

Compatibility

iOS
Windows
Android

Description

This setting lets you show a custom image rather than the standard HTML icon displayed on the toolbar of a record. You would create this Pulsar Setting, save and attach an image to the setting, and then it will be used as the button image instead of the standard image.

Notes/Comments

The custom icon image should be a square PNG image (same height and width) and be approximately 50px by 50px in size. We recommend that you use a simplified design in your image as iOS will transform the image into a monochromatic icon. It should also have transparency, anti-aliasing, and no drop shadow that uses a mask to define its shape.

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:

function getQueryVariable(variable) { var query = window.location.search.substring(1); var vars = query.split("&"); for (var i=0; i<vars.length; i++) { var pair = vars[i].split("="); if (pair[0] == variable) { return pair[1]; } } } var objectId = getQueryVariable("ref_id");

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

Name

Home Screen App Content

Key

pulsar.home.webContent

Value

15 or 18 character document ID

Default Value (if any)

 

Compatibility

Description

If specified with a valid document ID (that is a valid .pulsarapp), this will show that document as the home screen.

Notes/Comments

The custom icon image should be a square PNG image (same height and width) and be approximately 50px by 50px in size. We recommend that you use a simplified design in your image as iOS will transform the image into a monochromatic icon. It should also have transparency, anti-aliasing, and no drop shadow that uses a mask to define its shape.

Name

Show/Hide Salesforce App Browser

Key

pulsar.home.toolbar.enableAppBrowser

Value

TRUE or FALSE

Default Value (if any)

 

Compatibility

Description

When Pulsar default home page is replaced by a custom webapp, this button will show the standard Salesforce app browser as a button on the bottom toolbar. This setting can be used to hide that button if needed.

Notes/Comments

 

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:

Archive: MyWebApp.zip.pulsarapp Length Method Size Cmpr Date Time CRC-32 Name -------- ------ ------- ---- ---------- ----- -------- ---- 5640 Defl:N 1817 68% 11-06-2019 19:08 4576e64d index.html <--- !!! NOTICE: must be accessible at the root of the zipfile 6030 Defl:N 2367 61% 11-06-2019 19:08 026a3fb3 app.js 113151 Defl:N 34303 70% 11-06-2019 19:08 a7185172 lib/lib.js 7149 Defl:N 1854 74% 11-06-2019 19:08 5d885f01 resources/css/main.css 7885 Defl:N 2584 67% 11-06-2019 19:08 66386a7a resources/css/normalize.css 33804 Defl:N 33751 0% 11-06-2019 19:08 60048a72 resources/fonts/SalesforceSans-Bold.woff 2562 Defl:N 810 68% 11-06-2019 19:08 ec6caba0 resources/icons/logo.svg 231 Defl:N 126 46% 11-06-2019 19:08 8a415fe2 resources/styles/styles.css 540 Defl:N 291 46% 11-06-2019 19:08 f6cca24d resources/images/logo.png ...

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.

WARNING: The Windows platform imposes severe restrictions on total file path length!

If you deploy on Pulsar for Windows and run into problems loading some of your resources, you may need to reduce file name lengths and/or reduce the depth of your folder hierarchies.

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.

Name

Global Shared Web Resources

Key

pulsar.docs.enableHTMLResources

Value

TRUE

Default Value (if any)

 

Compatibility

Description

Attach a zipfile of your resources to this Pulsar Setting. If the setting is TRUE, then the attached zipfile will be unzipped into a toplevel resources/ directory.

  • Note that your zipfile should be the contents of the resources/ directory and not contain the resources/ directory itself.

  • For example, if you bundle both fonts/salesforce-sans/SalesforceSans-Bold.svg and js/global.js file in yourzipfile, then your code can access them at resources/fonts/salesforce-sans/SalesforceSans-Bold.svg and resources/js/global.js, respectively.

  • Developers need to ensure that file path names in your global resources do not collide with file path names in your various .pulsarapp webapps

  • Note: If you are replacing or updating the attachment/file, please make sure you edit and save the actual Pulsar setting to change the last modified date, so Pulsar knows to now download the latest file.

Notes/Comments

Â