XhBtRmL

From XBRLWiki
Revision as of 14:37, 8 January 2019 by Agil (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to navigationJump to search

Product page

XhBtRmL XBRL to HTML Template language

XhBtRmL template language to produce HTML representation of XBRL reports

Description

XhBtRmL is a simple language designed to create templates that produce HTML representation of the content of XBRL reports. It can be used for multiple purposes as, for example, to produce a nice web page directly from the content of an XBRL report or for transforming the XBRL report into another XML document, for example; an iXBRL report or an XML-FO (for the production of PDF) etc.

The idea regarding the architecture behind XhBtRmL is the same as in XSLT. There is an Infoset (Information and structure of information) and a transformation language that is able to provide access to the information that exist on the Infoset and produce an output document. The reason why XSLT is not the right solution for working with XBRL is because XSLT was designed to work with the limited infoset of XML nodes (elements, attributes, namespaces, values, ...) while the XBRL Infoset is much richer that just elements and attributes. It contains concept definitions with specific XBRL properties, labels in multiple languages, presentation, calculation and reference relationships, definition relationships with other concept definitions etc. All this information may be diseminated in multiple files composing a complex DTS. This is certainly not an efficient scenario for XSLT or the production of XSLT pages.

Testing XhBtRmL

The best way to test XhBtRmL is creating your own templates or modifying the content of existing templates. The first thing the user needs is a testing environment in which the user can start submit a web page and see the result. This walkthrough will guide the user step by step about the following topics:

  1. Installation instructions of the testing environment
  2. Understanding the testing environment
  3. Reference documentation

Installation instructions of the testing environment

The testing environment can be installed under the Java platform using the Tomcat Application Server or it can be installed using the .NET platform on windows.

Installation under Windows .NET

  1. Download and install the latest version of Reporting Standard tools Direct access to the downloads Page.
  2. Install the required licenses in order to be able to run Reporting Standard code in your computer. Direct link to request evaluation licenses form.
  3. Download the .NET version of the XBRL Libraries from this link: RS_XBRL_API_in_DotNET.zip. The zip file contains a directory with 7 DLLs. The DLLs will be used later as references from .NET code. The user can install the DLLs in the GAC or in a folder. During this walkthrough we will assume the user has extracted the DLLs into a directory called RS_XBRL_API_in_DotNET. Note: Starting with version 2.6.9 of Reporting Standard Tools, if you have already installed the Excel Mapper Plug-in you already have the DotNet library on your hard drive in a directory called "Excel Mapper lib". So there is no need to download anything additional. Starting with version 2.6.11, the DotNet library will always be installed on a directory called "Excel Mapper lib" regardless the Excel Mapper Plug-In is installed or not.
  4. Download the sample project from this link: [XhBtRmL_DotNET.zip]. Now uncompress the content somewhere in your hard drive.
  5. The XhBtRmL solution contains a web project also called XhBtRmL. Depending on the user's operating system version he'll have to configure different things in the IIS web server in order to start serving .aspx pages. Under Windows XP Proffessional edition this requires installing IIS 5.1 and Windows .NET framework 2.0 (3.5 is recommended for working with the XBRL API). After that, it is necessary giving read permissions to the ASPNET user to the following directories:
    1. The lib directory where Reporting Standard License files and library files are installed.
    2. The XhBtRmL directory where the project source code is located (this is, for example, the directory where the file AssemblyInfo.cs is located).
    3. and write permissions to the temp directory under the XhBtRmL directory. This is because the web server will write downloaded files here.
  6. Under Windows Vista, similar work will be necessary regarding the permissions of the users running the web server process.
  7. Open the project with you C# IDE (Visual Studio or Sharp Develop)
  8. Now resolve the unresolved references. There may be unresolved references to the following files: IKVM.AWT.WinForms, IKVM.OpenJDK.ClassLibrary, IKVM.Runtime, IKVM.Runtime.JNI, xbrljlib-2.0, xbrlmap and xbrlpojolib. The user will find that all required DLLs in order to resolve the references are located in the RS_XBRL_API_in_DotNET directory.
  9. Compile the project
  10. If you have not already do so, configure your web server to serve web pages under the directory where the Default.aspx file exist use the directory name XhBtRmL as the name of the virtual directory.
  11. Start the web server and point your browser to the root page http://localhost/XhBtRmL/Default.aspx
  12. After some seconds (the application takes some time to start) the user would see a simple web form to submit a sample XBRL report followed by an OK button on the next row
  13. Press the Browse button and search for the sampleInstance.xbrl document that is located in the project directory XhBtRmL
  14. Press the OK button and submit that file for processing. The process will take more time the first time it is executed because the templates are not compiled. The compiled templates are stored in memory in order to accelerate further executions.
  15. Read the Reference Documentation section in order to know how the process works and how to create new templates adapted for other taxonomies.

Installation under Java platform

  1. Download the Java sample project from this link: [XhBtRmL_Java.zip]
  2. Use Eclipse or your favorite IDE in order to set-up the project. The project contains a simple form in a web page called default.html and JSP page called process.jsp that contains all required code in order to produce an HTML representation of the sample XBRL report. There is also a static class called Config that is used from the JSP page and from a Servlet called InicializationServlet. The only purpose of the Initialization Servlet is to create an instance of the transformer object using the configuration file. The Transformer will be reused between calls and it is thread safe so the reated instance will be stored in the Config object for later use.
  3. Review the content of the web.xml file and deploy the application according to your application server settings.
  4. Start the web server and point your browser to the root page http://localhost/XhBtRmL/Default.html
  5. After some seconds (the application takes some time to start) the user would see a simple web form to submit a sample XBRL report followed by an OK button on the next row
  6. Press the Browse button and search for the sampleInstance.xbrl document that is located in the project directory XhBtRmL
  7. Press the OK button and submit that file for processing. The process will take more time the first time it is executed because the templates are not compiled. The compiled templates are stored in memory in order to accelerate further executions.
  8. Read the Reference Documentation section in order to know how the process works and how to create new templates adapted for other taxonomies.

Understanding the testing environment

The testing environment consist of the following components:

  1. A sample XBRL Taxonomy. This taxonomy is local (not officially published, used only for this prototype and is not stored in Reporting Standard Taxonomy Catalog). The taxonomy schema can be located in the project directory config/samples/taxonomies/sample/sampleTaxonomy.xsd.
  2. A sample XBRL Report. The report is in a file called sampleInstance.xbrl that is valid according to the sampleTaxonomy.xsd. In order to validate the instance document the user may need to store the instance document in the temp directory.
  3. A Web form called Default.aspx in the .NET windows platform or process.jsp in the Java platform that receives the xbrl file and send it to the TransformProcessor instance for transformation from XBRL format to HTML format. The TransformProcessor is initialized with a configuration file when the application is started.
  4. A Configuration file for the TransformProcessor. With information about the DTS, the templates etc.
  5. A set of Templates that defines the final user interface

The .NET Windows project

The Web.config file contains the following project properties:

<syntaxhighlight lang="xml"> 

 ...
   <appSettings>

<add key="tpConfig" 

	     value="config/transformationParameters.xml"
	/>

<add key="tempFolder" value="temp" /> 

   </appSettings>
 ...

</syntaxhighlight>

The file Global.asax.cs contains the following code:

<syntaxhighlight lang="csharp"> 

 ...

protected void Application_Start(Object sender, EventArgs e) { // Initialization of the TransformProcessor GetTransformProcessorInstance(); }

public string GetTempFolderInstance() { if (incomingFolder == null) { incomingFolder = Server.MapPath("~/")+ConfigurationSettings.AppSettings["tempFolder"]; } return incomingFolder; }

public TransformProcessor GetTransformProcessorInstance() { if (tp == null) { string tpConfig = Server.MapPath("~/")+ConfigurationSettings.AppSettings["tpConfig"]; File tpf = new File(tpConfig); try { // Initialization of the XBRL library InitDotNet.Initialize();

initializationError = null; tp = new TransformProcessor(tpf.toURI()); Properties props = new Properties(); props.put(OutputKeys.METHOD,"xhtml"); props.put(OutputKeys.DOCTYPE_PUBLIC,"-//W3C//DTD XHTML 1.0 Transitional//EN"); props.put(OutputKeys.DOCTYPE_SYSTEM, "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"); props.put(OutputKeys.OMIT_XML_DECLARATION, "no"); props.put(OutputKeys.ENCODING,"ISO8859-1"); props.put(OutputKeys.VERSION,"1.0"); tp.setOutputProperties(props); } catch (Exception ex) { tp = null; initializationError = ex; } } return tp; } </syntaxhighlight>

The Java project

The web.xml file contains the following information:

<syntaxhighlight lang="xml"> 

 ...
   <env-entry>

<description>TransformProcessor config file</description> <env-entry-name>tpConfig</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>config/transformationParameters.xml</env-entry-value> 

   </env-entry>
   <env-entry>

<description>Incoming instance documents will be downloaded here</description> <env-entry-name>tempFolder</env-entry-name> <env-entry-type>java.lang.String</env-entry-type> <env-entry-value>temp</env-entry-value> 

   </env-entry>
 ...

</syntaxhighlight>

The Config.java class contains the following method

<syntaxhighlight lang="java">

public static synchronized void init(ServletContext application) { if (bInitialized) return; bInitialized = true;

try { String tempFolder = null; Context ctx = new javax.naming.InitialContext(); Context env = (Context)ctx.lookup("java:comp/env");

tempFolder = (String)env.lookup("tempFolder"); incomingFolder = application.getRealPath(tempFolder);

String tpConfig = (String)env.lookup("tpConfig"); String tpReal = application.getRealPath(tpConfig); File tpf = new File(tpReal); tp = new TransformProcessor(tpf.toURI()); Properties props = new Properties(); props.put(OutputKeys.METHOD,"xhtml"); props.put(OutputKeys.DOCTYPE_PUBLIC,"-//W3C//DTD XHTML 1.0 Transitional//EN"); props.put(OutputKeys.DOCTYPE_SYSTEM, "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"); props.put(OutputKeys.OMIT_XML_DECLARATION, "no"); props.put(OutputKeys.ENCODING,"ISO8859-1"); props.put(OutputKeys.VERSION,"1.0"); tp.setOutputProperties(props); } catch (NamingException e) { bInitialized = false; e.printStackTrace(); } catch (TransformConfigurationFileException e) { bInitialized = false; e.printStackTrace(); } } </syntaxhighlight>

Information about the global properties

The tempFolder property will be used in order to store downloaded files. DTS resolution should use either absolute files or relative files that will be resolved using this directory as the base directory for relative resolution if there is no xml:base or any other indication inside the file according to the XML and XBRL specifications.

The tpConfig property is used to indicate the name of the configuration file for the initialization of the TransformProcessor. Refer to the section XhBtRmL Configuration file for more information about the syntax and configuration file content.

Reference documentation

Retrieved from "https://reportingstandard.com/wiki/index.php?title=XhBtRmL&oldid=689"