14.6.18

Fragments

FIT can be used to deliver only fragments instead of complete HTML documents. This can be useful for AJAX requests, with other frameworks instead of Partial Page Loading. For this to work, the fragment has to be marked explicitly.

By default FIT parses all content it receives as a complete document. The fragment:

<div>foobar</div>

will be parsed to the following document:

<!DOCTYPE html>
<html>
  <head/>
  <body>
    <div>foobar</div>
  </body>
</html>

This document will be processed by FIT. URLs will be rewritten, ACs will be processed and FIT JavaScript will be added. That way a simple response for a few elements is a lot bigger (several KB depending on the enabled features) than it needs to be and contains additional JavaScript elements that may result in client side errors upon insertion into the document.

Using fragments the resulting response is smaller and contains no interfering JavaScript.

To make sure all FIT features work after a fragment request, all enabled features used in the fragment must already be present in the client (e.g. do not enable the Delivery Context API in the flow.xml only for the fragment request).

If fragment handling is enabled, registering Adaptive Components conditionally in your flow may result in incomplete initialization of the respective Adaptive Components, e.g. if the flow registers an AC for the requested fragment that was not registered for the referring page, that AC’s JavaScript may be missing.

We stronlgy recommend registering ACs unconditionally if fragment handling is enabled.

Delayed Images should be deactivated for fragment requests. Alternatively you have to initiate the loading of Delayed Images yourself after the content is inserted in your document.

FIT automatically disables Delayed Images if the Delivery Context property request/fragment is set to true. This property is set automatically when using the ;m=fragment URLMark or can be set manually with the set-dc Action.

Note: Be careful when using the register-xslt Action on fragment requests. This action can result in faulty behaviour of some FIT features, especially Adaptive Components.

1. Fragment Markers

To send only the desired content via FIT, it has to be enclosed in <ai-document-fragment> elements. Everything but the child elements of these document fragments are filtered before transporting the content to the client.

This feature cannot be enabled or disabled in the config.xml file. It will be used every time the document contains an <ai-document-fragment> element.

The markers are set automatically by FIT for the whole requested content if the request is sent with a certain URLMark.

The markers can also be inserted by hand using XSL or already be included in the requested document.

2. Automatic Fragment Mode

In automatic fragment mode, FIT automatically adds <ai-document-fragment> elements around the document fragment received from the backend during the Parse Action. It is triggered if

  • the URLMark ;m=fragment is set, or
  • the config option content-handling/retain-html-fragments is enabled, the resource is sent with a proper HTML Content-Type response header, and contains fragment HTML markup unless the first start tag is one of the following tags: html, head, base, link, meta, script, style, title.

Setting the URLMark ;m=fragment can be achieved by setting the role of an URL to role="fragment".

<a href="foo.html" ai-url-role="fragment">foobar</a>

The JavaScript URL API does not support setting roles for URLs, but the URLMark can be set explicitly with ai.urls.composeUrl.

ai.urls.composeUrl('foo.html', [{name: 'm', value: 'fragment'}]);

After the normal processing of the document is done, only the content between <ai-document-fragment> elements is sent to the client.

In automatic fragment mode, the Delivery Context property request/fragment is set to true. In the second case (with option content-handling/retain-html-fragments enabled), this is true only after the parsing of the response.

Warning: The <ai-document-fragment> markers are inserted when the Parse Action is executed. If a xslt Action has already run, the document fragment received from the backend is already parsed when the Parse Action is executed and the markers cannot be inserted correctly.

Content received from backend:

<div id="foo">
  A
  B
</div>
<div id="bar">
  <h1>foo bar</h1>
  <p>
    <span>ABC</span>
    <span>DEF</span>
  </p>
</div>
<ac-stage id="foobar">
  [...]
</ac-stage>

Document after Parse Action:

<html>
  <head/>
  <body>
    <ai-document-fragment>
      <div id="foo">
        A
        B
      </div>
      <div id="bar">
        <h1>foo bar</h1>
        <p>
          <span>ABC</span>
          <span>DEF</span>
        </p>
      </div>
      <ac-stage id="foobar">
        [...]
      </ac-stage>
    </ai-document-fragment>
  </body>
</html>

Result sent to the client:

        <div id="foo">
          A
          B
        </div>
        <div id="bar">
          <h1>foo bar</h1>
          <p>
            <span>ABC</span>
            <span>DEF</span>
          </p>
        </div>
        <div id="foobar" class="AC_stage">
          [...]
        </div>
        <script id="AC_stage_stageInit_foobar">...</script>

3. Multiple Fragment Elements

Alternatively the <ai-document-fragment> elements can be set via xslt Action or already contained in the received content. This way it is also possible to have more than one <ai-document-fragment> in the document.

The content of multiple <ai-document-fragment> elements is simply concatenated in the output.

The document before processing:

<html>
  <head>
    <title>foo</title>
  </head>
  <body>
    A
    B
    <ai-document-fragment>
      Fragment 1
      <span>Y</span>
      Z
    </ai-document-fragment>
    <div>
      <p>
        <ai-document-fragment>
          Fragment 2
          <span>foobar</span>
        </ai-document-fragment>
      </p>
    </div>
    C
    D
    <ai-document-fragment>
      Fragment 3
      1
      2
    </ai-document-fragment>
    E
    F
  </body>
</html>

Result sent to the client:

        Fragment 1
        <span>Y</span>
        Z
            Fragment 2
            <span>foobar</span>
        Fragment 3
        1
        2

4. Delivery Context Property request/fragment

The Delivery Context property request/fragment is automatically set to true if the URLMark ;m=fragment is used. You should consider setting it to true with set-dc Action when you insert <ai-document-fragment> elements manually.

<flow>
  ...
  <set-dc property="request/fragment" xpath="true()" />
  ...
</flow>

If request/fragment is set to true, only Delayed Images with ai-priority="visibility" are used for the request.

5. Caveats

Some points to keep in mind while using fragments:

  • When using the ;m=fragment URLMark, you should not use a xslt Action on the requested content before using the Parse Action. Otherwise the <ai-document-fragment> markers cannot be inserted correctly.
  • Delayed Images are not automatically loaded for fragment requests. Either disable them for the request, or manually load them after the images are inserted.
    • If the Delivery Context property request/fragment is set to true (either because of the ;m=fragment URLMark or set using the set-dc Action), FIT automatically disables Delayed Images whose ai-priority attribute are not set to visibility.
  • Multiple fragments can never have a root element, single fragments may not have a single root element. Because of that, the client cannot parse the content as XML. Only responseText will be available, not responseXML.
  • Avoid using the register-xslt Action with fragment requests.
  • No features should be enabled in the flow.xml only for the fragment request.

4.1 AC Stage and fragments

Particular attention has to be paid when using fragments together with AC Stages.