Adaptive Components Best Practices

Best Practices that emerged from our work with Adaptive Components.

Naming the Adaptive Component

Adaptive Components that are officially part of FIT always have the prefix ac- (e.g. ac-stage or ac-scroll). However, this is not mandatory for your own components. As a rule of thumb, we suggest to use the ac- prefix if you want to share your component with others or use it in multiple sites. In case your AC is specific to a certain project we suggest using a project prefix, such as {myproject}- (e.g. myproject-header or myproject-cart).

README

Every Adaptive Component should have a README file that explains the installation, dependencies, usage, known issues and everything else you consider important.

• Installation
  • how to register the AC in the Flow
• Dependencies
  • config options that have to be set
  • 3rd party libraries that are needed, including versions if necessary
• Syntax
  • required elements and attributes
  • optional elements and attributes
• Delivery Context properties
  • properties that the AC uses for decisions
  • properties that will be changed by the AC
  • properties that will be added by the AC
• API
  • JavaScript function documentation
• Known Issues
  • any issues with certain devices?
  • any issues with 3rd party scripts or other ACs?
• Examples
  • show some examples for all aspects (markup, JS API calls, …)

Setting or omitting the version attribute in the manifest

Because you usually want FIT to use an up to date XSL during development, omitting the version attribute during development is usually a good idea.

Determining the last modified time of the XSL file on the other hand is a relatively expensive operation to perform.

So in production use you should usually have a version attribute set so the expensive operation will not be performed for every request.

Naming files

For compatibility and flexibility of the Adaptive Component you should avoid using the Adaptive Components name as file names.

XSL files

Your XSL file should be named main.xsl rather than ac-example.xsl.

JavaScript and CSS files

Your JavaScript or CSS files should be named main.js rather than ac-example.js. Especially because some FIT 14 features (e.g. auto-inlining) could remove the src respective href attributes it is advised to assign a unique ID to your resources. System ACs will have their IDs set following to the scheme AC__ACNAME_HINT. For example <script id="AC__STAGE_trackbox"></script>.

JavaScript API

If your Adaptive Component features a JavaScript API we advise you to locate it within window.ac.name. Any API calls for our ac-example should look like window.ac.example.apiCall(). Also please remember that your JavaScript will most likely not be the only JavaScript in the client. Using closures to prevent your code from polluting the global scope is strongly recommended. If you do not know where to start, feel free to copy the example below and change it to your liking.

JavaScript Example

(function(__global) {

  var acExample = {};

  /* ac API functions here */

  acExample.broadcast = function broadcast() {
    console.log(arguments);
  };

  /* make the acExample api available */
  __global.ac = __global.ac || {};
  __global.ac.example = acExample;

})(this);

CSS classes

Your CSS is probably not the only CSS that is delivered to the client. To make sure that all components work together and your style definitions do not interfere with others, you should avoid using rather general selectors and we encourage you to prefix your class names with the ac name. We advise you to use tagnames only in combination with class names (e.g. do not use div > ul but div.AC_example_container > ul.AC_example_list). In most cases you should avoid using ID selectors (e.g. #avoidIDs), too.

Using XIncludes

ACs with a lot of XSLT code can quickly become confusing. In this case it is possible to outsource templates and include them using XIncludes.

Example main.xsl

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="ac-example" mode="ac-example">
    <div>
      <xsl:attribute name="class">ac-example</xsl:attribute>
      <xsl:apply-templates select="ac-example-template"/>
    </div>
  </xsl:template>
  <xi:include xmlns:xi="http://www.w3.org/2001/XInclude" href="template.xsl" xpointer="xmlns(xsl=http://www.w3.org/1999/XSL/Transform) xpointer(/xsl:stylesheet/xsl:template)"/>
</xsl:stylesheet>

Example template.xsl

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:template match="ac-example-template" mode="ac-example">
    <div>
      <xsl:attribute name="class">ac-example-template</xsl:attribute>
    </div>
  </xsl:template>
</xsl:stylesheet>

It is possible to include outsourced XML Files using the document() function.

Example

<?xml version="1.0" encoding="UTF-8" ?>
<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
  <xsl:variable name="ac-example-config" select="document('ac-config.xml')"/>
  <xsl:template match="ac-example" mode="ac-example">
    <div>
      <xsl:attribute name="class"><xsl:value-of select="$ac-example-config/class/text()"/></xsl:attribute>
      <xsl:apply-templates/>
    </div>
  </xsl:template>
</xsl:stylesheet>