About

Here you will find the definition for the main concepts introduced in comp library.

1. Jinja

2. Components

3. Rendering

4. Other Docs

Jinja

jinja string.

A jinja string is a Python string preppended with the keyword jinja, and which contains jinja syntax. They form a type Jinja, which is a subtype of Str, the typed string type.

jinja delimiter.

The jinja delimiters are the logic delimiters used to define code blocks, variables and comments in the jinja syntax. In comp they are given by [%, [[ and [#, respectively, but can also be customized through the envs COMP_JINJA_BLOCK_DELIM, COMP_JINJA_VAR_DELIM and COMP_JINJA_COMMMENT_DELIM.

jinja inner var.

A jinja inner variable is a variable in the jinja syntax of a jinja string which is defined inside the jinja string by making use of the [% set ... %] block. Those variables can be accessed through the attribute .inner_vars of Jinja or through the typed function jinja_inner_vars.

jinja free var.

A jinja free variable is a variable in the jinja syntax of a jinja string which is not defined inside the jinja string. Their values should be included in the jinja context in order to render the jinja string. They can be accessed through the attribute .free_vars of Jinja or through the typed function jinja_free_vars.

jinja context.

The jinja context of a jinja string is a Python dictionary whose keys are the free jinja vars of the jinja string.

rendering.

In the context of jinja strings, jinja rendering is the process of turning them into raw HTML by giving a jinja context.

jinja factory.

A jinja factory is a type factory taking values into a subtype of the Jinja type. An example is Tag: Tuple(Str) -> TYPE, which assigns to a tuple of strings the subtype of Jinja consisting of those jinja strings which are delimited by the HTML tag named by some of the strings in the given tuple.

Components

component.

A component is a typed function decorated with the @component decorator and that returns a subtype of Jinja: the type of jinja strings. Components form the type COMPONENT. Components are typically structured by some component model.

local context.

The local context of a component is that defined by the special variable __context__.

component leak.

A leak of a component is a jinja free var on its underlying jinja string which is not declared in the {lib:local context}.

bounded component.

A bounded component is a component without leaks. In other words, it is a component such that every jinja free var is declared in the {lib:local context}.

inner var.

An inner variable in a component is a variable of type Inner, which is {lib:type equivalent} to Str. Such variables are used to denote a placeholder for future insert inside a component.

content var.

A content variable in a component is a variable of type Content, which is given by Union(Str, Extension('md', 'rst')). These variables represent static content (Markdown of ReStructuredText) to be included somewhere in a component.

component factory.

A component factory is a type factory that takes values into some subtype of COMPONENT. It is, therefore, a parameterized family of components. The main component factory is COMPONENT, when viewed as a callable entity. Other example is TAG, which receive strings *tags and build the subtype TAG(*tags) of COMPONENT given by the components taking values in Tag(*tags).

component model.

A component model is a model (typically an {lib:optional model}) that describes the structure of a component.

tag component.

A tag component is a component whose jinja string is encapsulated in some HTML tag block, hence that take values into the image of the jinja factory Tag. In other words, a tag component is an instance of TAG(*tags) for some *tags.

component operation.

A component operation is a typed function that receive components and return other component.

component join.

The component join is a component operation join: Tuple(COMPONENT) -> COMPONENT that receive components *comps and return the new component join(*comps) whose jinja string is the string join of the corresponding jinja strings.

component concat.

The component concat is a component operation join: Prod(COMPONENT(1),COMPONENT) -> COMPONENT that evaluates the inner var of a component with the jinja string of other component.

Rendering

rendering.

Rendering is the process of turning a component into raw HTML by means of providing a rendering context and fixing {lib:rendering flags}. It is implemented as a typed function render.

rendering context.

The rendering context is the information needed to be attached to a component in order to render it. This includes, for example, values for any component variable any component leak.

rendering flag.

The rendering flags are special {py:arguments} of the render typed function, which configures the rendering process. Examples are: __styled__, __minified__, and so on.

rendering style.

The rendering style is a special feature of the component rendering process in which style strings are automatically introduced as css classes in a <style> tag of the produced HTML.

style string.

A style string is a string representing a css class, used as values to the attribute <comp>_class of a component, and which are converted to the css class they represent during the rendering process. Typically the css class is composed by a single css property, so that the style string is named based into a style property. For example, margin-top-10px is a style string with a single style property: margin-top.

style property.

A style property is a css property inside the css class represented by a style string.

style alias.

A given css class can be represented by multiples style strings. Given a style string, the other style strings represented the same css class are style aliases for the given one. When the style string corresponds to a style property, then their style aliases are constructed from aliases for the underlying style property. For example, the style string margin-top-10px corresponds to the style property margin-top, which have mt as an aliases, defining the style alias mt-10px.

Other Docs

1. overview

2. jinja

3. components

4. models

5. rendering

6. compatibility

7. styles

8. changelog