> For the complete documentation index, see [llms.txt](https://sws.gitbook.io/sws-questionnaires/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://sws.gitbook.io/sws-questionnaires/software/design/model/model-layout.md). # Layout The **layout** of questionnaires defines their *structure* and *appearance*: the components they're made of, how they relate to each other, and how they look. * layout components may be as simple as multi-lingual titles, paragraphs, and bulleted lists. They may be as complicated as forms bound to data selections or their metadata. ## Specifications Like most aspects of questionnaires, layout components are generated from specifications. * **component specifications** are part of questionare specifications, and component generation is a sub-process of questionnaire generation. * depending on the current state of questionnaires, component generation may be repeated after questionnaire generation, i.e. against the same data. ## Properties Components have **named properties** that carry over from their specifications. * **common properties** recur across many components, **custom properties** vary from component to component. * some properties are about the **style** of components, e.g. their size, orientation, typography, color, etc. Others concern their underlying **model**, e.g. visibility flags. Some model properties are about **content**, e.g. the multilingual text of titles, headers, paragraphs, etc. * **simple properties** have no structure, **object properties** aggregate other properties. * simple properties may refer to the properties of a cross-component **theme**. ## Parameters Component generation is a parametric process. * parameters are a superset of those provided to generate questionnaires. Accordingly, component specifications can refer to language, year, country, etc. * theme properties become generation parameters so that their reference in style properties can be resolved. ## Formats A key generation parameter specifies the **publication formats** of components, i.e. the medium on which they should be rendered. We target two main formats: * an *offline format* based on Excel. **Excel components** are rendered prior to publishing, into spreadsheet files via backend libraries such as Apache POI. After publication they cannot be re-rendered. * an *online format* based on HTML5/CSS3/JavaScript. **Web components** are continuously rendered after publication in the front-end of a dedicated SPA application. * we also use a plain-text format for debugging and quick prototyping of structure and content. **Debug components** are read-only and unstyled. Some properties are specific to given formats, that is have no bearing or meaning when the layout is rendered in other formats. * an example of **format property** is the number of column of an Excel `page`, which is ignored if the page is rendered online. Other properties are intepreted differently for different formats. * for example, a `size` property with a standard value of `large` may translate to different values in different formats. And a custom value for that property may in fact be valued in different unit, e.g. in points or in pixels. > **note**: component specifications generate only one component per format. Later, we may need to relax and allow users to pick one of a set of possible component choices. ## Containers Some components serve as **containers**, include other components as children and subsume their rendering. * containers project a tree structure on the layout of questionnaires. * components that do not occur as children of other components are **roots**. ## Types, Names and other Attributes Component and properties have a set of **attributes** that govern their management in front-end and back-end processes alike. These are all simply valued and fixed, i.e. do not depend on specific components or questionnaires. The key attribute is the component or property **type**, which identifies them in authoring and rendering processes. * `page`, `title`, `content`, `style`, `size`, etc. are all sample values of the `type` attribute. Collectively, component types and property types form the **component model** of layout. Besides types, components have **name** attributes that distinguish children of the same type inside containers. Similarly, properties have name attributes that distinguish properties of the same type inside complex properties. Properties have also a `mandatory` attribute to indicate whether the property should a value for a layout to be correctly specified. This is acted upon during **validation** of specifications. * validation does not cover the existence of cardinality of properties of certain types inside complex properties.