About

Here you will find an overview for the comp library.

1. Overview: Components

2. Overview: Special Vars

3. Overview: Rendering

4. Other Docs

Overview: Components

The lib comp deals with components. These are typed functions (in the sense of typed) which return jinja strings, i.e, Python strings of type Jinja, which contain jinja2 syntax. Components should also be defined using the @component decorator.

The typical way to define a component is to first define a model (in the sense of typed, typically a {lib:optional model}) containing the structure of the component, and then take this model as argument:

from typed import optional, null, SomeType, OtherType
from comp import component

@optional
class MyModelib:
    some_var:  SomeType=null(SomeType)
    other_var: OtherType=null(OtherType)
    ...

@component
def my_comp(my_compy: MyModel) -> Jinja:
    ...
    return """jinja
    ...
"""

Components define a type COMPONENT and there are four main component operations between them, each of them corresponding to an arithmetic symbol ({py:magic methods} in Python):

operation	symbol	description
join	+	join the jinja strings of the components
concat	*	put a jinja string inside the other
eval	/	fixes some arguments
copy	^	copy a component, eventually changing var names

table 1: component operations

This means that we can construct complex components through component equations:

my_comp = (
    (comp_1 * comp_2) +
    (comp_3 / {'some_var': some_value})
) ^ {"some_var": new_name}

Remark 1. The modules comp.models and comp.components provides, respectively, a plethora of already defined models and corresponding components, one for each builtin HTML tag.

Overview: Special Vars

A component have certain special vars:

1. __context__: defines the {lib:local context} of the component, where needed information to render it is introduced (see below);

2. vars of type Inner: used as placeholder to introduced content of other components;

3. vars of type Content: receive static context in the form of Markdown or ReStructuredText.

For example, inner vars are used in the component concat operation, while content vars allows the use of comp in both dynamic and static environments.

Overview: Rendering

After being constructed, components can be rendered, producing raw HTML. This is done using a typed function render:

from comp import render

html = render(my_comp, **context)

To render a component one needs to pass a context, which is a dictionary. It attaches values to each argument of the component, as well as to other {lib:free variables}.

The rendering process can be customized to produce optimized raw HTML by passing certain special variables to render:

argument	type	description
__minified__	Bool	return minified HTML
__styled__	Bool	auto-generate <style> for inline classes
__scripts__	List(Script)	include given script data in the HTML
__assets__	List(Asset)	include given asset data in the HTML

table 1: render variables

Remark 2. During the construction of a component you can preview it using the preview function, which renders the component and creates a server that looks automatically for updates in the component file.

Other Docs

1. jinja

2. components

3. models

4. rendering

5. compatibility

6. styles

7. glossary

8. changelog