Skip to content

Generating a URL Map from local application paths to runtime Web Content Manager URLs

You can generate a JavaScript based URL map from local application file system paths to runtime Web Content Manager Library URL paths to application artifacts, when necessary. This feature is advanced and is disabled by default.

When you push or import a JavaScript, HTML, and CSS-based application to be used as a Script Application, the import and push function locates every URL, such as js/app.js or images/background.png, and replaces them in the imported content. The URL is replaced with Web Content Manager URL plug-in markup that generates the corresponding Web Content Manager URL at render time. Keep all application URLs simple and in one quoted string so that the import and push functions can do URL repair when the application is being stored in Web Content Manager.

Some uses of JavaScript frameworks or existing JavaScript applications can construct relative URLs at run time in the browser, such as partials/viewDetails.html. They then attempt to make an Ajax request to load that artifact directly from that path. This situation occurs where a JavaScript framework does not generate relative URLs until run time. When the application artifacts are stored in Web Content Manager content item elements, they no longer have simple relative paths and lookups fail. To enable use of such frameworks and existing application JavaScript with Script Application, instruct the import and push mechanisms to generate a JavaScript URL map in the application page. You can then use an extra helper method to retrieve the corresponding Web Content Manager URL that uses a local application path URL generated by the JavaScript framework at run time. For details, read JavaScript API for spHelper.

  1. Add the attribute data-scriptportlet-generate-url-map="true" to the <html> element in your applications primary HTML file, such as index.html.

  2. If you have JavaScript that must load a dynamically constructed path at run time, pass the local path to __SPNS_spHelper.getElementURL, with the local path as a prefix. Use the results of that function to determine the runtime path.

    For example, instead of this code:

    $.get(localpathURL);

    use the following code instead:

    var runtimeURL = __SPNS__spHelper.getElementURL( localPathURL ) ;
$.get( runtimeURL  );

  3. To test your application outside your portal and the Script Application where spHelper does not exist, you must add extra code. Wrap the sample code in the previous step with the following extra protective statements.

    For example, in the following code, you can add an if-statement and a try-and-catch block. This code replaces the local URL if the namespaced spHelper exists and has the optional getElementURL method available. That method returns a runtime URL for the specified local URL. With these additional statements that wrap the lookup, when run locally, the original local path-based URL is used for testing purposes, as spHelper does not exist.

    // Start with the local URL (eg, htmlFragments/viewDetails.html )
var runtimeURL = localpathURL;    

  try { 
    if ((__SPNS__spHelper) && (__SPNS__spHelper.getElementURL) ) {
      // if running as script application, find the WCM URL equivalent
      var tmpURL = __SPNS__spHelper.getElementURL(localpathURL);  

      // only replace the original URL if there is 
      // an equivalent WCM URL in the map matching it.
      if (tmpURL)
        runtimeURL = tmpURL;   
    }
  // ignore error if generated by browser when looking 
  // for spHelper running locally, outside of portal
  } catch(error) { 
  }
  $.get(runtimeURL);

If the results are not what you expected, consider the following issues.

The map must be initialized before the lookup from the map is done. Therefore, make sure that this JavaScript runs on a page onload handler or in JavaScript that is used in the page later. Do not run JavaScript inline on the page before the page finishes loading.

If the runtime equivalent of __SPNS__spHelper.getElementURL is not found, then ensure that you pushed or imported the application with the data-scriptportlet-generate-url-map="true" attribute set correctly in the <html> element on the primary application page.

Related information