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.1 the module only supports one page applications. 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. Get Parameters
  6. Forms
  7. Cookies
  8. Set Cookies
  9. Ajax
  10. Http Status Codes
  11. Using Resources of the surrounding NIVEA page

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.

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"

No value set for get parameter "param"

Important Note

The NIVEA MEN website always submitts both, desktop an mobile version markup in one page. When using forms in proxyframes this causes a problem as the same form is renderd twice, with the same field names and IDs. Therefore ProxyFrame Developers have to implement a Javascript which detects which version is shown and remove the other one via Javascript.

We are planing a common solution for this problem an will adjust this documentation as soon as it is available.

Forms

Sitecore < Version 8 uses the ASP Webforms Framework. This implies that the whole page is already surrounded by a form tag. You can not use your own form tag, as nested form tags are nat valid. They will be stripped off during the embedding process.
If you need special attributes or a different action as the same page you have to modify the page form tag via javascript.

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




Using Resources of the surrounding page

  • A few styles for CSS atomics and molecules, like e.g. body, headings, anchors, figures or images, are global.
  • All other CSS classes are prefixed with nx-.
  • You should not override our nx- CSS classes.
    But feel free to use them.
  • We are using jQuery 3.2.1 and we are using jQuery in noConflict mode.
    We are using our own jQuery alias $n.
    Feel free to use our alias, but you should not override it.
  • We are using RequireJS 2.2.0.
    If you need a script loader feel free to use our RequireJS.
    You should create your own config context to register your modules and to set your base url.
    Context names "nivea" and "niveax" are reserved.
    Do not override our contexts!
  • Below you will find a list with scripts and jQuery Plugins we are using:
    1. fancyBox — http://fancyapps.com/fancybox/
    2. jScrollPane — http://jscrollpane.kelvinluck.com/
    3. SelectBoxIt — http://gregfranko.com/jquery.selectBoxIt.js/
    4. slick slider — http://kenwheeler.github.io/slick/
    5. shariff — https://github.com/heiseonline/shariff
    6. smartresize — http://unscriptable.com/index.php/2009/03/20/debouncing-javascript-methods/

Keep in mind that our css classes can change at any time without warning.
We reserve the right to update jQuery, jQuery Plugins, RequireJS and Scripts we are using at any time without warning.

Examples

/* CSS atomics */
body {
    font-family: "NiveaBook",Arial,sans-serif;
    background: white;
    margin: 0;
    min-height: 100%
}

h1,h2,h3,h4,h5 {
    color: #00136f
}

h1 {
    font-family: "NiveaBold",Arial,sans-serif;
    font-size: 2.1875em;
    line-height: 1em;
    color: #00136f;
    margin-top: 0
}

figure {
    margin: 0
}

img {
    height: auto;
    max-height: 100%;
    max-width: 100%;
    vertical-align: top
}

/* CSS classes with nx- prefix */
.nx-text {
    font-family: Arial,sans-serif;
    font-size: .75em;
    line-height: 1.41666667em;
    color: #333333
}

.nx-text p {
    margin: .75em 0
}
                    
/* RequireJS config */
YourNamespace._require = require.config({
    context: 'your context name',
    baseUrl: '/path/to/your/modules',
    paths: {}
});

YourNamespace._require([/* your module(s) to load */])
test