Project - js-lib-com/wood GitHub Wiki

A WOOD project is a collection of loosely structured components; a component's files are stored in a single directory and component directory location into project file system is not constrained. Excepting project assets and theme there are no predefined directories.

Project has a root directory and all paths are relative to this project root. By convention component name is the file path of the component directory. For example, component page/index has component directory /$project/page/index/.

Project Properties

WOOD command line tool manages components and generate W3C site into project build directory. In order to be processed by build tool every WOOD project should have project properties file .wood.properties.

Project properties is a Java properties file that contains local development environment properties. Remember that Java properties API requires escaping for equal (=) and colon (:) characters. Project properties file is hidden and is not pushed to VCS.

.wood.properties

runtime.home=D\:/runtime/
runtime.port=8080
runtime.name=tiny-store

See WOOD command line tool for details.

Project Descriptor

Project instance is configured from a project.xml file; since there are sensible default value for all configurations this file is optional.

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.xml

<project>
	<asset-dir>asset</asset-dir>
	<theme-dir>theme</theme-dir>
	<build-dir>target/site</build-dir>

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

See project descriptor description.

File System

Project is a not constrained tree of directories and files: source files, resource files - mostly media, variables definition files, and descriptors. Directories hierarchy is indeed not constrained but there are naming conventions for component files - see component description.

It is recommended as good practice to have separated modules for user interface and back-end logic. Anyway, there are no constraints that impose this separation of concerns and there is the option to exclude certain directories from WOOD tool processing.

Here a sample project file system but is by no means imposed by WOOD tools. Please take it as it is, just a suggestion.

Above directories description and couple new suggestions:

Directory	Description
asset	Project global resource files.
compo	Project child components, optionally including widget components too.
gen	Generate script stubs for back-end services integration.
lib	Third party libraries, scripts and style files.
page	Web pages based on page templates from template directory.
template	Template components, both pages and child components.
theme	Styles files concerning visual aspect only, common to all pages. Layout styles are on components.
widget	Similar to compo but storing only widget components, optional; if missing, widgets are stored on compo.

Project core files:

File	Description
.wood.properties	Local development environment properties used by WOOD tools.
favicon.ico	HTML favicon can be stored on project root or on asset directory.
loader.js	PWA service loader script.
manifest.json	PWA manifest file.
project.xml	Project global properties, optional since all properties have sensible defaults.
worker.js	PWA service worker script.

File Path

File path identify project directories and files, usually component files like layout, styles and scripts. A file path is a standard Java file with couple syntax constrains: it is always relative to project root, always uses slash (/) for file separator, directory path is optional and file name supports variants, separated by underscore.

Syntax

Characters used by path segments and file base name are US-ASCII alphanumeric characters, dash and dot. Dot is allowed for file names with version, for example js-lib-1.2.3.js. Last dot is for extension. Underscore is reserved for variants separator and is not valid in names.

file-path    = *path-segment base-name *variant DOT extension 
path-segment = 1*CH F-SEP
base-name    = 1*CH
variant      = V-SEP 1*(ALPHA / DIGIT / "-")
extension    = 1*(ALPHA / DIGIT)
 
; terminal symbols definition
F-SEP = "/"                         ; file separator is always slash
V-SEP = "_"                         ; variant separator is always underscore
DOT   = "."                         ; dot as file extension separator
CH    = ALPHA / DIGIT / "-" / "."   ; character is US-ASCII alphanumeric, dash and dot

; ALPHA and DIGIT are described by RFC5234, Appendix B.1

Variants

Variants qualify file path so that one can create group of files with the same semantic content but differently presented, for example string variables for multi-language support.

Variants are appended to file names, separated by underscore (_) character. Is legal to have multiple variants, but every variant preceded by its separator - underscore (_) character. Currently supported variants are language and media queries for style files.

Language

Language variants are used for projects with internationalization support. This should be declared on language property from project descriptor. A not declared language variant is ignored.

Pattern for language variant has format similar to Accept-Language HTML header. Strictly speaking, language variant format is not identical with HTML header; it uses only 2 digit ISO 639 alpha-2 language code and additional information is always country code, into ISO 3166 alpha-2 format. Dash separator and country code are optional. For example, ro and ro-RO are both valid variants.

An example of a string definition file localized for Romanian language. See Language Usage.

asset/string_ro-RO.xml

<string>
	<title>Titlu pagină</title>
</string>

Language code has the same limitations regarding old language code as Java Locale class has. It accepts new codes but always generate old ones. For example an Hebrew file can use both iw and he code for language variant but generated site page will always use iw.

Media Queries

Media queries enable different styles based on device properties, for example screen width and height. On the other hand, WOOD allows to split media queries styles on style file variants with custom alias, for example page/index/index_portrait.css.

In order to use a media query file variant it should be declared on project descriptor, media-query element; alias attribute is the file variant and expression attribute is media feature always related to screen media type.

Declare media query with alias portrait.

project.xml

<project>
	<media-queries>
		<media-query alias="portrait" expression="orientation: portrait" />
	</media-queries>
</project>

Use media query variant portrait to annotate component style file.

page/index/index_portrait.css

.page > .header {
	width: 400px;
}

For details and usage see media query description.

Component Path

Component path is the file path of the project directory where component files reside. Being a file path it is always relative to project root and always uses forward slash as path separator; anyway, component path cannot have variants. Component path can be also viewed as a sequence of path segments. Last path segment is usually known as component name.

For widgets, component path is the layout file path but using file base name, that is, no variants or extension.

Component paths are used on layout files to declare components relations. Here is a sample usage: wood:template operator declares a reference to editable body from template template/page, whereas wood:compo operator is a reference to child component compo/button.

<div wood:template="template/page#body">
	<div wood:compo="compo/button"></div>
</div>

Both template/page and compo/button are component paths. Their related directory path is /$project/template/page/, respective /$project/compo/button/.

Site Layout

WOOD tools generates a complete W3C site - standard HTML, CSS and vanilla JavaScript, from project components. For now build file system layout - for short site layout, is hard coded.

Default site layout uses separated directories for styles, scripts and media files; all media files are stored in the same place. Pages are placed in site directory root.

For multi-language projects, replicates single language directories layout for every declared language. Uses textual language value - as declared on project descriptor, for sub-site name.

Sub-site is generated for every declared language, no mater language variant is actually used by any file, in which case default language is considered.

Last updated 9/8/2022.