Project Descriptor - js-lib-com/wood GitHub Wiki
Project descriptor is a XML file that contains global project properties similar in structure with component descriptor. In fact there may be properties present on both project and component descriptor, in which case component takes precedence.
<project>
<title>Tiny Strore</title>
<authors>Iulian Rotaru<[email protected]></authors>
<asset-dir>asset</asset-dir>
<theme-dir>theme</theme-dir>
<build-dir>target/site</build-dir>
<exclude-dirs>target/</exclude-dirs>
<operators>XMLNS</operators>
<language>en-US</language>
<media-queries>
<media-query alias="portrait" expression="orientation: portrait" />
</media-queries>
<head>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0"></meta>
</head>
</project>Here is a summary of currently implemented properties, by tag. Directories and files have syntax described by file path and all list values are comma separated.
| Element | Property | Default | Description |
|---|---|---|---|
| authors | Authors | empty list | List of project authors. |
| asset-dir | Project Assets | asset | Project assets directory. |
| build-dir | Build Directory | build | Project build directory. |
| exclude-dirs | Excluded Directories | empty list | List of directories excluded by WOOD tools. |
| favicon | HTML Favicon | favicon.ico | File path to project favicon file. |
| link | Link Descriptors | empty list | References to resources, mostly style files. |
| language | Language | en | List of project languages. |
| media-query | Media Queries | empty list | Media queries definitions for responsive design. |
| meta | Meta Descriptors | empty list | Generic meta elements copied into page. |
| operators | Operators Naming | DATA_ATTR | Component operators naming strategy. |
| pwa-loader | PWA Service Loader | loader.js | Script implementing PWA service loader. |
| pwa-manifest | PWA Manifest | manifest.json | PWA manifest file path. |
| pwa-worker | PWA Service Worker | worker.js | Script implementing PWA service worker. |
| script | Script Descriptors | empty list | Reference to JavaScript files or embedded script. |
| theme-dir | Project Theme | theme | Project theme directory. |
| title | Page Title | project basename | Title injected into generated page header. |
All elements with text content can be refered in source files using @project/property at-meta reference.
List of comma separated developers authoring this project, used to initialize generated site pages meta author. Usually author name is its email address.
<project>
<authors>[email protected], [email protected]</authors>
</project>Authors value is copied as it is into all pages HEAD. If authors element is missing, meta author header is no included. If there are more authors, prefix the authors list with co-authored by.
<HEAD>
<META content="co-authored by [email protected], [email protected]" name="Author" />
</HEAD>Is not uncommon to use full email address, that is, email address with display name, for example John Doe<[email protected]>. In this case, because email address has angle brackets, we need to use XML CDATA construct or to escape with <, respective >.
<project>
<authors><![CDATA[John Doe<[email protected]>]]></authors>
</project>In this case, WOOD tools takes care to escape angle brackets and generate page is still a valid XHTML.
<HEAD>
<META content="John Doe<[email protected]>" name="Author" />
</HEAD>Project assets directory is the global store for resource files, mostly media files but no limited to, and variables definition files. Its value should be a directory path relative to project root; trailing path separator is optional so both res/asset/ and res/asset values are valid. Default value is asset.
<project>
<asset-dir>res/asset/</asset-dir>
</project>A component can have its own private resource files or can reuse global resources from project assets. In both cases uses the same at-meta reference to identify the resource file, for example @image/logo.
<div xmlns:wood="js-lib.com/wood">
<!-- image reference -->
<img src="@image/logo" />
</div>WOOD tools tries first to find resource file into component directory then on project assets.
Project build directory is where WOOD tools generate pages and related styles, scripts and resources. Its value should be a directory path relative to project root; trailing path separator is optional so both target/site/ and target/site values are valid. Default value is build.
<project>
<build-dir>target/site/</build-dir>
</project>Build directory is automatically added to excluded directories.
Comma separated list of directories to be excluded by WOOD tools. Its values should be directory paths relative to project root; trailing path separator is optional so both target/site/ and target/site values are both valid. Default value is empty list.
<project>
<exclude-dirs>target/site/</exclude-dirs>
</project>Build directory is added automatically into excluded directories list, on list post-processing. Hidden directories - those with leading dot on name, are excluded implicitly by WOOD tools and is not necessary to list them on excluded directories.
File path to project favicon file is declared using <favicon> element. Its value should be a file path, relative to project root. Default value is favicon.ico, an icon file stored on project root.
<project>
<favicon>asset/favicon.ico</favicon>
</project>Favicon resource link is declared into all generated page headers. If favicon file is not found at specified file path favicon resource link is not created.
<HEAD>
<LINK href="media/favicon.ico" rel="shortcut icon" type="image/x-icon" />
</HEAD>A link descriptor is a reference to an external resource, usually third party style files but not limited to.
A third party style file can be included remotely, from third party servers or can be downloaded and included as project file, perhaps in the lib directory. Consequently href attribute can be local file path, always relative to project root, or third party full URL.
Relation attribute rel is optional if its value is stylesheet.
<project>
<links>
<link rel="stylesheet" href="lib/toolbar.css"></link>
<link rel="stylesheet" href="https://bootstrap.com/bootstrap.css"></link>
</links>
</project>Optionally, link descriptor element can be declared inside a parent for improved readability, for example links; anyway, it can be declared anywhere since WOOD tools searches for link tag on all descendants.
Declared link elements are included into all generated pages. Note that link elements order maters; it is preserved. All links declared on project descriptor are included before all components styles, see styles inclusion order.
<HEAD>
<LINK href="style/lib_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>Note that local style files path is updated by WOOD tools in respect with generated site layout; also links from project descriptor are included with order preservation, but before component 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. |
For multi-language project, developer should declare the list of (comma separated) language using <language> element. If language element is missing project supports only en. Language are used as file variants.
<project>
<language>en, ro-RO</language>
</project>Language format is usually ISO two-letter code but language with country code is supported. Both en and ro-RO are valid language values.
Language declaration order maters: first language is considered the default one. All files without language variants are considered as default language.
WOOD tools will generate a complete sub-site for every language defined in project descriptor. Sub-site names are exactly as declared, en and ro-RO. The same goes for lang attribute from HTML element. See Language Usage.
Sub-site is generated even if the declared language is never used for any file variant. In this case default language is considered.
CSS styles media queries should be declared in project descriptor before using them as style file variant.
Use <media-query> element to declare a media query; alias attribute is the file variant and expression attribute is media feature always related to screen media type. Parent element <media-queries> is optional and is used only for readability.
<project>
<media-queries>
<media-query alias="portrait" expression="orientation: portrait" />
<media-query alias="lgd" expression="min-width: 1200px" />
<media-query alias="mdd" expression="max-width: 992px" />
<media-query alias="smd" expression="max-width: 768px" />
<media-query alias="xsd" expression="max-width: 560px" />
<media-query alias="h700" expression="max-height: 700px" />
</media-queries>
</project>For usage sample see CSS style description.
Meta descriptors are generic metadata elements, other than links or scripts. Meta descriptors are copied by WOOD tools into all generated pages header.
<project>
<metas>
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0"></meta>
</metas>
</project>Optionally, meta descriptor element can be declared inside a parent for improved readability, for example metas; anyway, it can be declared anywhere since WOOD tools searches for meta tag on all descendants.
Note that meta elements order maters. It will be preserved when include into (all) generated pages header.
<HEAD>
<META name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0" />
</HEAD>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. |
Define operator naming strategy using <operators> element. Default value is DATA_ATTR.
<project>
<operators>XMLNS</operators>
</project>Accepted strategy values:
| Strategy | Name | Description |
|---|---|---|
| ATTR | Attribute Name | Simple attribute name. Because it does not use prefix it is prone to name collision but is simple to use. |
| DATA_ATTR | Custom Attribute Name | Uses HTML custom attribute name, that is, prefixed with data-. This naming convention is a trade-off between simplicity to use and avoiding name collisions. |
| XMLNS | XML Namespace | This is default naming strategy and offer a clear separation for WOOD operator name space. Anyway, add complexity because name space should be declared with WOOD URI: xmlns:wood="js-lib.com/wood". |
Define manifest file path for PWA web applications. Uses <pwa-manifest> element and value should be a file path relative to project root. Default value is manifest.json.
<project>
<pwa-manifest>asset/manifest.json</pwa-manifest>
</project>See PWA sample usage.
Define PWA service loader file path for PWA web applications. Uses <pwa-loader> element and value should be a file path relative to project root. Default value is loader.js.
<project>
<pwa-loader>script/pwa-loader.js</pwa-worker>
</project>See PWA sample usage.
Define service worker file path for PWA web applications. Uses <pwa-worker> element and value should be a file path relative to project root. Default value is worker.js.
<project>
<pwa-worker>script/pwa-worker.js</pwa-worker>
</project>See PWA sample usage.
Declare supplementary scripts, usually third party libraries, needed by project. These will be included into all generated pages.
Script source can be local file, always relative to project root or third party script in which case script source is a full URL.
<project>
<scripts>
<script src="lib/format.js" defer="true"></script>
<script src="https://bootstrap.com/bootstrap.min.js" defer="true"></script>
</scripts>
</project>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 (all) generated page header. Anyway, all scripts declared on project descriptor are included before component scripts.
WOOD tools copy script descriptor elements into all generated pages header. Also WOOD tools take care to avoid self closing element so that script descriptor element can use shorter syntaxes <script ... \>.
<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>Note that local scripts path is updated by WOOD tool in respect with generated site layout; also scripts from project descriptor are included with order preservation, but before component script 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; default to true. |
| 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>Project theme directory is the global store for theme style files. Its value should be a directory path relative to project root; trailing path separator is optional so both res/theme/ and res/theme values are valid. Default value is theme.
<project>
<theme-dir>res/theme</theme-dir>
</project>See theme style for theme directory files description.
Style files from project theme directory are loaded into all generated pages. Excepting var.css, default.css and fx.css, inclusion order is not relevant since theme style files have no dependencies on each other. See style inclusion order.
<HEAD>
<LINK href="style/theme_var.css" rel="stylesheet" type="text/css" />
<LINK href="style/theme_default.css" rel="stylesheet" type="text/css" />
<LINK href="style/theme_fx.css" rel="stylesheet" type="text/css" />
<LINK href="style/theme_button.css" rel="stylesheet" type="text/css" />
...
</HEAD>Project title is injected into generated page header. It is free text and is declared in <title> element; it is optional.
<project>
<title>Site Title</title>
</project>Project title is combined with page component title and inserted into generate page title element. If both project and component title are defined, merged title looks like below.
Anyway, both project and component title are optional. If only one is defined uses that value. If both are missing infer page title from project directory name, to title case.
<HEAD>
<TITLE>Site Title - Page Title</TITLE>
</HEAD>Last updated 9/8/2022.