Component Descriptor - js-lib-com/wood GitHub 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.

Page Description

Description injected into page meta description, declared with <description> element. Description is a free text.

page/index/index.xml

<page>
	<description>Page description...</description>
</page>

Description is copied as it is into page head, the meta description element, from the page generated from this component. If description is not defined, page meta description is not set.

site/index.htm

<HEAD>
	<META content="Page description..." name="Description" />
</HEAD>

Link Descriptors

A link descriptor is a reference to an external resource, declared by <link> element. It is the same as project link but with smaller scope.

page/index/index.xml

<page>
	<link rel="stylesheet" href="lib/toolbar.css"></link>
	<link rel="stylesheet" href="https://bootstrap.com/bootstrap.css"></link>
</page>

If component is a page, as in example above, resource links are included only in page created from page component. If declared in a template or child component, resource links are included in all pages using that component.

Resource links declared in component descriptor are included after those declared in project descriptor, see styles inclusion order.

See project links for details.

Script Descriptors

Declare supplementary scripts needed by component. Remember that component core script file is included automatically into generated page. It is the same as project script but with smaller scope.

page/index/index.xml

<page>
	<script src="lib/format.js" defer="true"></script>
	<script src="https://bootstrap.com/bootstrap.min.js" defer="true"></script>
</page>

If component is a page, as in example above, scripts are included only in page created from page component. If declared in a template or child component, scripts are included in all pages using that component.

Scripts declared in component descriptor are included after those declared in project descriptor.

See project scripts for details.

Meta Descriptors

Meta descriptors are generic metadata elements, other than links or scripts. It is the same as project meta but with smaller scope.

page/index/index.xml

<page>
	<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0"></meta>
</page>

If component is a page, as in example above, meta elements are included only in the page created from page component. If declared in a template or child component, meta elements are included in all pages using that component.

Meta elements declared in component descriptor are included after those declared in project descriptor.

See project meta elements for details.

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 default 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>

WOOD tools 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>

Page Title

This property has to do with the title injected into generated page header. It is free text and is declared in <title> element; it is optional.

page/index/index.xml

<page>
	<title>Page Title</title>
</page>

Project title is combined with component title and inserted into page title element. If component title is missing uses only project title. For a discussion about page title generation logic see project title.

site/index.htm

<HEAD>
	<TITLE>Site Title - Page Title</TITLE>
</HEAD>

Last updated 9/15/2022.