Component Descriptor - js-lib-com/wood Wiki

Component descriptor is a XML file storing component properties, mainly copied by build tool to generated page. Descriptor root element has a tag consistent with component type: page, template and compo. If descriptor is missing component type is assumed compo.

Descriptor is mandatory only for page components. It should be present even if it is empty; build tool uses it to recognize a component as page. If developer forget to create component descriptor, that page is not created by build tool event it has <body> element.

<page></page>

Component descriptor contains property elements, every property having a specific tag - see table below. There are value elements, for example page title <title>@string/app-name</title>, and page header elements that are embedded into generated pages.

Value elements have a tag and some text content. Page header elements are similar to HTML counterpart.

<compo>
	<title>@string/app-name</title>
	...
	<link rel="stylesheet" href="lib/format.css"></link>
	<script src="lib/format.js"></script>
</compo>

Optionally, for improved readability, page header elements can be declared inside a parent element, for example header or anything else. Anyway, they can be declared in descriptor root as well since build tool searches for header element tags on all component descriptor descendants.

<compo>
	<header>
		<link rel="stylesheet" href="lib/format.css"></link>
		<script src="lib/format.js"></script>
	</header>
</compo>

Also build tool takes care to avoid self closing element syntax when required by W3C HTML specs. For example, on component descriptor developer can use self closing syntax <script ... \> but on generated page will be inserted as <script ...></script> - as mandated by HTML specs.

Here is a summary of currently implemented properties, by tag.

Tag Property Description
description Page Description Description injected into page meta description.
group Resources Group Resources group to which this component belongs.
link Resource Link References to resources, mostly style files.
meta Page Meta Generic metadata elements copied into page header.
script Include Script Reference to JavaScript files or embedded script.
title Page Title Title injected into generated page header, <title> element.

Link Descriptors

A link descriptor is a reference to an external resource, usually style files but not limited to. Hyper-reference - href, attribute can be local file path, always relative to project root or third party, in which case hyper-reference is a full URL.

  • page/index/index.xml
<compo>
	<links>
		<link rel="stylesheet" href="page/index/toolbar.css"></link>
		<link rel="stylesheet" href="https://bootstrap.com/bootstrap.css"></link>
	</links>
</compo>

Optionally, link descriptor element can be declared inside a parent for improved readability, for example links; anyway, it can be declared anywhere since build tool searches for link tag on all descendants.

Note that link elements order maters. It will be preserved when included into generated page header. Anyway, all links declared on component descriptor are included before component core style.

  • site/index.htm
<HTML>
	<HEAD>
		<LINK href="style/page-index_toolbar.css" rel="stylesheet" type="text/css" />
		<LINK href="https://bootstrap.com/bootstrap.css" rel="stylesheet" type="text/css" />
		<LINK href="style/page_index.css" rel="stylesheet" type="text/css" />
	</HEAD>
</HTML>

Note that local style files path is updated by build tool in respect with generated site layout; also links from component descriptor are included with order preservation, but before component core style page_index.css.

Here are couple link attributes. For complete description see link reference.

Attribute Description
crossorigin Sets the mode of the request to an HTTP CORS request.
href URL of the linked resource: project relative path for local or full URL for external resource.
integrity Allows browser to check the fetched resource to ensure it has not been manipulated.
referrerpolicy Referrer information to send when fetching a script.
rel Relationship between page and linked resource, default to stylesheet.
type Link reference type, default to text/css.

Script Descriptors

Declare supplementary scripts needed by component. Remember that component core script file is included automatically into generated page.

Script source can be local file, always relative to project root or third party script in which case script source is a full URL.

  • page/index/index.xml
<compo>
	<scripts>
		<script src="lib/format.js" defer="true"></script>
		<script src="https://bootstrap.com/bootstrap.min.js" defer="true"></script>
	</scripts>
</compo>

Optionally, script descriptor element can be declared inside a parent for improved readability, for example scripts; anyway, it can be declared anywhere since build tool searches for script tag on all descendants.

Note that script elements order maters. It will be preserved when included into generated page header. Anyway, all scripts declared on component descriptor are included before component core script.

Build tool copy script descriptor elements into generated page header. Also build tool takes care to avoid self closing element so that script descriptor element can use shorter syntaxes <script ... \>.

  • site/index.htm
<HTML>
	<HEAD>
		<SCRIPT src="script/lib.format.js" type="text/javascript" defer="true"></SCRIPT>
		<SCRIPT src="https://bootstrap.com/bootstrap.min.js" type="text/javascript" defer="true"></SCRIPT>
		<SCRIPT src="script/page.index.js" type="text/javascript" defer="true"></SCRIPT>
	</HEAD>
</HTML>

Note that local scripts path is updated by build tool in respect with generated site layout; also scripts from component descriptor are included with order preservation, but before component core script page.index.js.

Here are couple script attributes. For complete description see script reference.

Attribute Description
async Load script asynchronously and execute as soon as download is complete.
crossorigin Sets the mode of the request to an HTTP CORS request.
defer Load script asynchronously and execute at page completely parsed.
embedded WOOD proprietary attribute to force script source code inclusion into generated page.
integrity Allows browser to check the fetched script to ensure it has not been manipulated.
referrerpolicy Referrer information to send when fetching a script.
type Script type, always text/javascript. If missing, build tool injects this attribute.

Beside standard W3C attributes script descriptor supports embedded boolean attribute: if true, script content is loaded in place into generated page.

<script src="lib/format.js" embedded="true" />
<HTML>
	<HEAD>
		<SCRIPT type="text/javascript">FormatFactory = {
...
};</SCRIPT>
	</HEAD>
	...
</HTML>

Meta Descriptors

Meta descriptors are generic metadata elements, other than links or scripts. Meta descriptors are copied by build tool into generated page header.

  • page/index/index.xml
<compo>
	<metas>
		<meta http-equiv="X-UA-Compatible" content="IE=9; IE=8; IE=7; IE=EDGE"></meta>
		<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0"></meta>
	</metas>
</compo>

Optionally, meta descriptor element can be declared inside a parent for improved readability, for example metas; anyway, it can be declared anywhere since build tool searches for meta tag on all descendants.

Note that meta elements order maters. It will be preserved when included into generated page header.

  • site/index.htm
<HTML>
	<HEAD>
		<META http-equiv="X-UA-Compatible" content="IE=9; IE=8; IE=7; IE=EDGE" />
		<META name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0" />
	</HEAD>
</HTML>

Here are couple meta element attributes. For complete description see meta reference.

Attribute Description
content Contains the value for the http-equiv or name attribute.
http-equiv Pragma directive, providing information equivalent to a similarly-named HTTP header.
name Element provides document-level metadata, applying to the whole page.

Resources Group

Resources groups allow to split HTML files for a large site into sub-domains, for example security domains, but not limited to.

On classic site layout all HTML files are stored on the site directory root. In this case there is no page component with group property declared (missing group property means that generated page belongs to root).

Here is an example how to use resources group to hide private pages, like error page. This example is working on web applications deployed on JEE Servlet Container. Remember that on servlets, files from WEB-INF directory are not publicly visible.

Lets assume we decided to store private pages in a directory named private. There we have a page component for error page.

  • private/error/error.htm
<body>
	<h1>Error Page</h1>
</div>

On private/error component descriptor we declare group property to WEB-INF.

  • private/error/error.xml
<page>
	<group>WEB-INF</group>
</page>

Build tool uses group property and store generated HTML file for error page into WEB-INF directory. This way error page becomes private.

Servlet container is configured to user private error page when detects a erroneous condition - but site clients cannot load this page using direct URL.

<web-app>
	<error-page>
		<location>/WEB-INF/error.htm</location>
	</error-page>
</web-app>

Last updated 9/15/2022.

⚠️ **GitHub.com Fallback** ⚠️