Sending and receiving IPFEvent messages in static pages

An API is provided for handling IPFEvent messages in static pages. This API allows static HTML pages to communicate with IPF pages across an iframe boundary.

The API handles only IPF native IPFEvent alerts. Other messages passed using the JavaScript window.postMessage method are ignored. Also, using IPFEvent objects through this API supports only event variable values that are native to JavaScript, such as string, number, boolean, date, and array of strings.

To use this API, you must include a script tag that fetches the supporting JavaScript through the StaticPageContext HTTP handler. The URL in the src attribute referring to this handler should be relative to the page location in Assets and is constructed by going up one level (../) plus one level for each folder nesting level to where the page resides inside of Assets. For example, if the page exists inside of the root of Assets, the relative path is ../StaticPageContext. If the page exists inside of a folder inside of Assets, the relative path is ../../StaticPageContext.

An example script include to be used in an HTML page residing in the Assets root would look like this: <script src="../StaticPageContext"></script>.

-------------------------------------------------------------------------------
  API for handling IPFEvent in static pages
-------------------------------------------------------------------------------
Getting the StaticPageContext instance:

    ipf.StaticPageContext.Instance
    ------------------------------
        - Return the StaticPageContext instance.


Functions on the StaticPageContext instance:
(Function signatures prefixed with JS: are written using JavaScript syntax and
function signatures prefixed with TS: are written using TypeScript syntax.)


    JS: CreateEvent(eventName)
    TS: CreateEvent(eventName: string): IPFEvent
        ----------------------------------------
        - Create a new IPFEvent with name 'eventName'.


    JS: AlertWindow(win, event)
    TS: AlertWindow(win: Window, event: IPFEvent)
        -----------------------------------------
        - Alert the 'event' IPFEvent to the 'win' window.


    JS: SetAlertHandler(win, alertHandler)
    TS: SetAlertHandler(win: Window, alertHandler: (event: IPFEvent) => any)
        --------------------------------------------------------------------
        - Set the 'alertHandler' alert event handler for the 'win' window.
          'alertHandler' is a function taking an IPFEvent as the parameter.


    JS: RemoveAlertHandler(win)
    TS: RemoveAlertHandler(win: Window)
        -------------------------------
        - Remove the alert event handler registered for the 'win' window.

Writing JavaScript using the context

IntelliSense is currently not supported for this API. We recommend that you write the code that handles an IPFEvent in a layout client script and then move that code to the static page JavaScript file. This way, IntelliSense can help with an IPFEvent. This is a sample usage:
(function(context)
  {
    // Code that uses the static page context API.

    // Inside here, the context is referenced by using the name "context", for
    // example "context.CreateEvent('myEvent')".
    
    // in this example, window.parent is assumed to be an IPF window
    var ev = context.CreateEvent('myEvent');                // create IPFEvent
    ev.GetVariables().SetValue('someName', 'somePayload');  // add data
    context.AlertWindow(window.parent, ev);                 // alert into IPF
  })(ipf.StaticPageContext.Instance);

In this sample, there should be an OnAlert handler registered in the layout script for the grid that contains the IPFWebPage referencing the static page, taking care of the 'myEvent' alert when it arrives.

Relative path construction for StaticPageContext and other IPF resources

The portal site relative URL for the static page context supporting JavaScript is ipf/StaticPageContext.

The site relative URL used by IPF for fetching a resource inside of assets is ipf/assets/<path_to_asset>; for example, ipf/assets/staticpage.html or ipf/assets/somefolder/staticpage.html.

If you traverse the asset fetching path up to the ipf level, ../ in the first example and ../../ in the second, you can get the supporting JavaScript by appending StaticPageContext to that traversal.

Relative path construction to reference an IPF portal page is performed the same way, with the difference that you traverse up past the ipf level and add any paths down to the IPF portal page. For example, to reference the Pages/SamplePage IPF portal page from the static page, you would traverse up ../../ in the first example and ../../../ in the second, and then add Pages/SamplePage, resulting in these relative paths: ../../Pages/SamplePage and ../../../Pages/SamplePage.