Best Practices that emerged from our work with Adaptive Components.
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
).
Every Adaptive Component should have a README
file that explains the installation, dependencies, usage, known issues and everything else you consider important.
version
attribute in the manifestBecause 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.
For compatibility and flexibility of the Adaptive Component you should avoid using the Adaptive Components name as file names.
Your XSL file should be named main.xsl
rather than ac-example.xsl
.
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>
.
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.
(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);
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.
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>