Direct loading

Introduction

BDML files can be loaded directly by a browser, using the browser's built in XSLT 1.0 processor. This does not require the Bora document processor, and instead uses the the AGPL licensed BDML source pack.

How to

In order to use direct loading, first download the BDML source pack from the public BDML Git repository. Copy the BDML folder into the base folder of your BDML document root.

The BDML source pack contains the BdmlHtml.xsl XSLT 1.0 transform. The path to this file needs to be specified at the top of the BDML file, in order that the browser may use it to transform the BDML file into HTML during loading. Assuming your BDML file is in the root folder, place the following declaration at the top of the BDML file. 

			<?xml-stylesheet type="text/xsl" href="bdml/BdmlHtml.xsl"?>

Once the XSLT transform declaration has been added, the BDML file should load correctly in the browser.

If the BDML file is in a sub-folder, the relative path needs to be specified in the declaration. The following declaration is for a BDML file inside a single sub-folder. 

			<?xml-stylesheet type="text/xsl" href="../bdml/BdmlHtml.xsl"?>

For BDML files in sub-folders, there is one additional step required in order to load the BDML files in the browser. Recent versions of mainstream browsers have introduced restrictions on locally loaded XSLT files. In this case, refer to the documentation below in order to configure the browser to allow local loading of XSLT.

CSS files

The BDML source pack includes a set of example CSS files that can be used directly in your BDML files. The main CSS file to specify via a <stylesheet> metadata element is the bdml-hml.css file.

Javascript files

The BDML source pack includes a set of Javascript files which can be used for the syntax highlighting of <code> blocks. These can be added to the BDML file header if required.

Direct loading limitations

Direct browser loading of BDML files uses the XSLT version 1.0 BdmlHtml.xsl transform.

Due to the use of XSLT version 1.0, direct browser loading of BDML files has certain limitations compared to full processing into HTML by the Bora document processor.

Included files

When a set of standalone BDML files is created and the BDML files reference each other, these references work correctly when loaded directly by a web browser. If these same BDML files are used to compose a multiple file BDML file via <include> elements, the references will continue to point to the original standalone files instead of being converted into links which are internal to the resulting composite document.

Whilst the links will be valid, they will load the standalone documents instead of referencing a fragment of the composite document.

Variants

Variants are not supported in direct browser loading. Any metadata, include, or target elements which have a non-empty variant attribute will not be processed by the browser.

Browser configuration

If your BDML sources are contained in a local folder hierarchy, this will necessitate the use of a parent relative path for all BDML files in sub-folders. Recent browsers have by default disabled such local file access, in order to ensure that there is no possibility of executing an incorrectly specified XSLT stylesheet.

This section provides details for the popular browsers on the settings required in order to enable loading of local files in folders which have a parent path component.

This issue does not affect BDML files served by a web server.

Firefox

Note that XSLT transform errors in Firefox are only reported to the browser console. The console may be shown by typing ctrl-shift-j. This can be useful when a BDML file does not load, in order to determine the issue.

Chrome / Chromium

This browser blocks all access to local XSLT files, unless started with the --allow-file-access-from-files option.

Safari

Blocking of local XSLT file loading can be removed by setting the Developer -> Disable Local File Restrictions option.