Render Inline XBRL (iXBRL) with CellStore, Part 2: Prepare an iXBRL Template

This page is a placeholder, its contents are being worked on.

Estimated reading time: 8 minutes

Prepare an iXBRL Template

The iXBRL template file is a plain xhtml file with a few additional attributes. Therefore, the template file can be displayed in the browser without being rendered to iXBRL. And, it can also be validated with e.g. the W3C XHTML validator, given that it follows the suggested general scaffold.

iXBRL Template: Generic Scaffold Structure

In order to allow validation with common XHTML validators the general scaffold of the template file should look like this:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.1//EN" "http://www.w3.org/TR/xhtml11/DTD/xhtml11.dtd"
[
    <!ATTLIST meta ixtp:type (variable|parameter) #IMPLIED>
    <!ATTLIST span ixtp:factMatch CDATA #IMPLIED>
    <!ATTLIST span ixtp:footnote CDATA #IMPLIED>
    <!ATTLIST span ixtp:footnoteRefs CDATA #IMPLIED>
    <!ATTLIST span ixtp:format CDATA #IMPLIED>
    <!ATTLIST span ixtp:scale CDATA #IMPLIED>
    <!ATTLIST span ixtp:negate (true) #IMPLIED>
    <!ATTLIST span ixtp:escape (true) #IMPLIED>
    <!ATTLIST span ixtp:numberFormat CDATA #IMPLIED>
    <!ATTLIST span ixtp:booleanFormat CDATA #IMPLIED>
    <!ATTLIST span ixtp:forceKeepContent (true) #IMPLIED>
    <!ATTLIST div ixtp:header (true) #IMPLIED>
    <!ATTLIST div ixtp:schemaRef CDATA #IMPLIED>
]>
<html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:ixtp="http://reportix.com/2021-07-21/ixbrl/template" 
      xml:lang="en">
    <head>
       ...
    </head>
    <body>
       ...
    </body>
</html>

In the snippet above you can see a complete list of all rendering extension attributes (template attributes) allowed in the rendering template file.

iXBRL Templates: Variables and Parameters

Variables as well as parameters can be used to assign values to named placeholders which can be used in the scope of the document set (one or multiple iXBRL template files). This allows to use the variable or parameter name interchangeably in attributes as references (syntax of reference: ${<VARNAME>} - replace <VARNAME> with name of the variable or parameter) to the value instead of the value itself. As a result, simple convenient bulk updates of commonly used values can be performed, for example updates to common standard periods or custom number formats used in the document.

Variables and parameters are declared using the meta element together with the mandatory ixtp:type attribute to declare the value as either variable or parameter. Please note that meta elements will not be processed by the rendering engine if there is no ixtp:type attribute. The variable or parameter name is defined in the name attribute and the value is defined in the content attribute. If the ixtp:type attribute is set to parameter then the value defined in content is the default value in case no value is set by an outside mechanism, e.g. through the API’s rendering endpoint.

Here is an example code snippet visualizing the declaration of a variable, parameter, and their usage:

<html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:ixtp="http://reportix.com/2021-07-21/ixbrl/template" 
      xmlns:us-gaap="http://fasb.org/us-gaap/2020-01-31" 
      xml:lang="en">
    <head>
       ...
       <!-- define parameter currentPeriodInstant with default value '2020-12-30' (value can be overridden from outside,
            e.g. through the API) -->
       <meta ixtp:type="parameter" name="currentPeriodInstant" content="2020-12-30"/>
       <!-- define variable customNumberFormat with value '#,##0;(#,##0);0' (value can not be overridden from outside) -->
       <meta ixtp:type="variable" name="customNumberFormat" content="#,##0;(#,##0);0"/>
    </head>
    <body>
       ...
       <!-- use parameter currentPeriodInstant and variable customNumberFormat -->
       <span ixtp:factMatch="xbrl:concept=us-gaap:Assets; xbrl:period=${currentPeriodInstant};" 
             ixtp:numberFormat="${customNumberFormat}"/>
    </body>
</html>

As you can see in the above code snippet both variables and parameters are defined and used in the exact same manner. The only difference between variables and parameters is that parameters can be overridden from outside, e.g. by passing a specific value as parameter through the API rendering endpoint (see in part about the API).

iXBRL Templates: Header and Schema Reference

One iXBRL header is mandatory in a single iXBRL document or a set of several documents. Within the iXBRL header the following items will be automatically included:

hidden facts and footnotes
resources, i.e. contexts, units, and relationships

The schema reference (mandatory attribute ixtp:schemaRef) needs to be defined in the template in order to link the DTS to the iXBRL document. While it is not necessary to put the iXBRL header as the first element within the body of the iXBRL template, it is recommended to do so for optimal parseability.

Example iXBRL header:

<html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:ixtp="http://reportix.com/2021-07-21/ixbrl/template" 
      xml:lang="en">
    <head>
       ...
    </head>
    <body>
       <div style="display:none" 
            ixtp:header="true" 
            ixtp:schemaRef="jpcrp040300-q1r-001_E02144-000_2020-06-30_01_2020-08-07.xsd"></div>
       ...
    </body>
</html>

iXBRL Templates: Facts

Facts can be created in the template by adding a span element with attribute ixtp:factMatch. The ixtp:factMatch attribute is a mandatory attribute of a fact. All other attributes are optional. Each attribute value might contain references to variables and/or parameters.

Attribute	Applicable to Facts of Type…	Description	Example Attribute Value
ixtp:factMatch	All	Defines the aspects to match the fact for rendering the value. This will also consistently create a context (and potentially a unit declaration) in the hidden resources.	`xbrl:concept=us-gaap:Assets; xbrl:period=${currentPeriodInstant};`
ixtp:format	All	The QName referencing a transformation from a transformation registry (see also Inline XBRL 1.1 Specification).	`ixt:num-dot-decimal`
ixtp:scale	numeric fact types	The scale of the rendered value (actual fact value = ten to the power of the scale attribute value; see also Inline XBRL 1.1 Specification).	`-2`
ixtp:negate	numeric fact types	Defines whether the actual value of the fact is the negated value of the rendered fact value (actual fact value = -1 * rendered fact value; cf. also sign attribute in Inline XBRL 1.1 Specification).	`true`
ixtp:escape	non-numeric fact types	If set to `true` the actual fact value is the XML-escaped value of the mixed content value of the rendered fact (see also Inline XBRL 1.1 Specification). If not set to `true` any mixed content will be atomized according to the respective fact value.	`true`
ixtp:numberFormat	numeric fact types	Number format for the rendered fact value in Excel number format syntax. No format for text values is supported. Use placeholder `[CURR]` to use the applicable currency symbol for the fact value.	`[CURR] #,##0.00;[CURR] (#,##0.00);[CURR] 0.00`
ixtp:booleanFormat	boolean derived fact types	Format for rendered boolean fact values. Values are separated by `<true-value>;<false-value>`. Useful for example with the SEC transformation format `ixt-sec:boolballotbox`.	`☒;☐`
ixtp:forceKeepContent	All	[Advanced Users] If this attribute is set to true the value given in the template will be used as output value. Hence, the value is not dynamically rendered from the DB. It effectively overrides the DB value of the fact.	`true`
ixtp:footnoteRefs	All	References to footnote ids (space separated list).	`fn_id1 fn_id2 fn_id5`

Some examples:

<html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:ixtp="http://reportix.com/2021-07-21/ixbrl/template" 
      xmlns:us-gaap="http://fasb.org/us-gaap/2020-01-31" 
      xml:lang="en">
    <head>
       ...
    </head>
    <body>
       ...
       <!-- percent number formatting (fact value: '0.153', rendered value: '15.30 %') -->
       <span ixtp:factMatch="xbrl:concept=us-gaap:SubsidiaryOrEquityMethodInvesteeCumulativePercentageOwnershipAfterAllTransactions; xbrl:period=2020-01-01/2020-12-31" 
             ixtp:numberFormat="#,##0.00%;-#,##0.00%;0.00 %" 
             ixtp:scale="-2">15.30%</span>
    </body>
</html>

ix:continuation elements will automatically be created if several facts have the same ixtp:factMatch attribute and have ixtp:forceKeepContent=true. In all other cases, the complete value of the fact is rendered. There is no reasonable algorithm to automatically split a fact value into several continuations.

iXBRL Template: Footnotes

Footnotes can be created in the template by using a span element with attribute ixtp:footnote. The ixtp:footnote attribute is a mandatory attribute for footnotes and must match a footnote xbrl:id aspect of a footnote from the DB. Each attribute value might contain references to variables and/or parameters.

Attribute ixtp:forceKeepContent is allowed for footnotes to override the value of footnotes from the DB. This is especially necessary if the footnote needs to get split accross one or more ix:continuation elements. There is no reasonable algorithm to automatically split a footnote value into several continuations.

All ix:relationship elements will be automatically created in the rendered iXBRL output document.

Some examples:

<html xmlns="http://www.w3.org/1999/xhtml" 
      xmlns:ixtp="http://reportix.com/2021-07-21/ixbrl/template" 
      xmlns:us-gaap="http://fasb.org/us-gaap/2020-01-31" 
      xml:lang="en">
    <head>
       ...
    </head>
    <body>
       ...
       <span ixtp:factMatch="..." ixtp:footnoteRefs="fn_id1 fn_id2">...</span>
       ...
       <span ixtp:footnote="fn_id1">this content will be replaced by the rendering engine</span>
       ...
       <span ixtp:footnote="fn_id2" ixtp:forceKeepContent="true">this content will be kept from the template.</span>
    </body>
</html>

On to Part 3 »

cellstore, Inline XBRL, XBRL, guide, tutorial, template, rendering