Proxy Frame Introduction

The ProxyFrame module enables third parties to embed their applications into a Sitecore website. They can use any programming language available on the delivery system. The extenal web application can be developed and tested independently of Sitecore. The developer just marks the sections that should get injected into the hosting Sitecore page. Of course application specific stylesheets and javascripts can be added as well. Even page title and metadata can be injected through the ProxyFrame into the target page. For Sitecore > 8.0 The module supports both single page applications as well as complex applications that has multiple pages. To prevent problems with unknown file extensions on the target platform like .php on IIS, make sure that your application serves content without file extension. I.e for php use directories with index.php.

Before you start with implementing a ProxyFrame hosted application,
  1. Read this documentation carefully,
  2. Make yourself familiar with the hosting application. What client side frameworks are being used (jQuery, bootstrap, require, etc) and which framework versions,
  3. Define a strategy for resource sharing:


    Option A: Don't rely on scripts and CSS from the hosting application, include your own libraries:
    + Updates of the hosting application are unlikely to have a large impact on the embedded application
    – Additional libraries make the page slower to load

    Option B: Share as much as possible:
    + Page is lighter, less additional code to download.
    – Application is more likely to break when the hosting application is updated.

    When you include your own libraries, make sure they don't conflict with the hosting application (for example jQuery noConflict).
    Regardless if you share resources or not, you should run automated tests after each deployment to ensure your application did not break!

Table of Content

  1. Content Injection
  2. Resources
  3. Resources in CSS
  4. Meta Tags
  5. Sub Pages
  6. Get Parameters
  7. Forms
  8. Cookies
  9. Set Cookies
  10. Ajax
  11. Http Status Codes

Injecting Content

  • The target pages contains multiple placeholders, that can be filled by the external application page. On each tag that should be injected into a placholder add the attribute "data-pf-placeholder=[placeholer name]".
  • In general the following placeholders are available:
    • head - at the bottom of the head section
    • content - the ProxyFrame rendering
    • scripts - at bottom of the page
  • By default the nodes are injected in the order of occurence but can be reordered by adding the proxyframe-sortorder data attribute.
  • By default the complete tag is injected. If you only want to inject the inner HTML, add a data-proxyframe-options="innerhtml" attribute.

Example

    
<html>
 <head>
    <link data-pf-placeholder="head" rel="stylesheet" href="/resrc/css/embeddedStyles.css"/>
 </head>
 <body>
    <div data-pf-placeholder="content" data-pf-sortorder="1" data-pf-options="innerhtml">
        Hello World
    </div>

    <script type="application/javascript" data-pf-placeholder="scripts" src="/resrc/js/embeddedScript.js?v=3"></script>
 </body>
</html>

Resources

You can reference your local resources such as images without any limitations. The links are adjusted automaticaly and passed trough the proxyframe to the external application server.

Always use root-relative paths for resource files: src="/path/to/resource/resource.jpg"

Resources in CSS Files

Resources in CSS files are not processed. To make them work use relative paths from the css file to the resource file.

Always use relative paths for resource files in css files: src="../relative/path/from/css /to/fileresource/resource.jpg"
  • List Elements
  • with image arrow

Meta Tags

You can inject your own meta tags by targeting the "head" placeholder. You can also modify the following standard tags:
  • <title>
  • <meta name="title">
  • <meta name="description">
  • <meta name="keywords">
Just add these meta tags to your external page and the ProxyFrame will replace the values of the original page with those provided by the external application. If you don't want to replace the meta data, either omit the meta tags or add the $BASE placeholder in the content to append to the original values from the hosting page.

 

Always use root-relative paths for all references and links.

Subpages

The proxy frame module supports complex applications with more than just one page. All subpages are hosted in the same Sitecore page but the external application can append to the base path.

To generate links to subpages you have two options:

  • Use "~/" as a prefix. The ProxyFrame will expand the ~ with the path to the hosting page.
  • Read the target base url from the "X-Pf-Baseurl" request header and prefix your links in the external application

Examples

Go to sub-page with X-Pf-Baseurl

Go to subpage with ~/

 

You must use the "~/" prefix or the hosting page base url "X-Pf-Baseurl" for application relative links.
To prevent problems with unknown file extensions on the target platform like .php on IIS, make sure that your application serves content without file extension 
 <?php
 function getLinkUri($path){
      $basurl = (isset($_SERVER["HTTP_X_PF_BASEURL"]) ? $_SERVER["HTTP_X_PF_BASEURL"] : "//".$_SERVER["HTTP_HOST"]);
   or
      $headers = apache_request_headers();
      $basurl = "//".(isset($headers['X-Pf-Baseurl']) ? $headers['X-Pf-Baseurl'] : $_SERVER["HTTP_HOST"]);

      $basurl = rtrim($basurl,"/");
      $path = ltrim($basurl,"/");
     return "//$basurl/$path";
 }

 ?>
 <a href="<?php echo getLinkUri('/subfolder/')?>">Go to sub page with X-Pf-Baseurl</a>
 <a href="~/subfolder/">Go to sub page with ~/</a>

Get Parameters

All get parameters are passed through to the external application.

Example

Set get parameter to "Berlin"

Set get parameter to "Paris"

Set get parameter to "New York"

Your value for get parameter "param"

Paris

Forms

All POST data is also passed to the external application

Example

POST values

Currently no POST values available

FILES values

Currently no FILES values available

Cookies

The external application has read-access to all cookies of the hosting page. It can also write coookies that are prefixed with "pf_".

Example




Your cookie values

Ajax Requests

For ajax request you have to prefix your request urls. You can add the data-pf-proxy-url attribute to any tag and the ProxyFrame module will fill the tag with the required prefix.

Example

  <form method="post" data-pf-proxy-url="https://mydomain.com/">
                    
  ajaxForm.on('submit',function(event){
      var baseUrl = $('form').data('data-pf-proxy-url');
      $.ajax(baseUrl+'ajax').done(function(data){

Ajax Results

Http Status Codes

The ProxyFrame handels the status codes of the external page and handles the following status codes:

  • 301 Redirects
  • 302 Redirects
  • 500 Server Errors
  • 404 File not found

Test Status Code Behaviour




test