def render(self, context):
id_prefix = f'{self.id_prefix}HtmlUtils'
return <DocPart kind="HtmlUtils" id_prefix={id_prefix} level={self.h_level}>
<DocHeader menu="HTML utils">HTML utils</DocHeader>
<Class h_level={self.h_level+1} id_prefix="{id_prefix}-" obj={resolve_class(
klass=html.RawHtml,
attrs=[],
methods=[],
name='RawHtml',
only_proptypes=['text'],
)} />
<Function h_level={self.h_level+1} id_prefix="{id_prefix}-" open=False open_details obj={resolve_function(
func=html.Raw,
name='Raw',
)} />
<Class h_level={self.h_level+1} id_prefix="{id_prefix}-" obj={resolve_class(
klass=html.Fragment,
attrs=[],
methods=[],
name='Fragment',
only_proptypes=[],
)} />
<DocPart kind="HtmlUtils" subkind="if-else" id_prefix={id_prefix} level={self.h_level+1}>
<DocHeader menu="if / else tags">if / else tags</DocHeader>
<Rst>{h.Raw(
# language=RST
"""
Mixt avoids support for logic within the HTML flow, except for one case where we found it especially
useful: conditionally rendering HTML.
That is why Mixt provides the ``<if>`` tag, which takes a prop named ``cond``.
Children of an ``<if>`` tag are only rendered if ``cond`` evaluates to ``True``.
It comes with the ``<else>`` tag, not taking any prop, that is optional but if
used, must come right after the closing ``</if>`` tag.
Children of an ``<else>`` tag are only rendered if the ``cond`` prop of the
``<if>`` tag evaluates to ``False``.
"""
)}</Rst>
<DocPart kind="HtmlUtils" subkind="if-else-example" id_prefix="{id_prefix}" level={self.h_level+2} open>
<DocHeader menu="Example">Example</DocHeader>
<SourceCode language="python">{h.Raw(
# language=Python
"""
>>> class Component(Element):
... class PropTypes:
... flag: Required[bool]
...
... def render(self, context):
... return <div>
... <if cond={self.flag}>
... <span>It's TRUE</span>
... </if>
... <else>
... <p>It's FALSE</p>
... </else>
... </div>
>>> print(<Component flag=True />)
<div><span>It's TRUE</span></div>
>>> print(<Component flag=True />)
<div><p>It's FALSE</p></div>
# A more pythonic way to do this without using these if/else tags:
>>> class Component(Element):
>>> def render(self, context):
...
... if self.flag:
... conditional_render = <span>It's TRUE</span>
... else:
... conditional_render = <p>It's FALSE</p>
...
... return <div>
... {conditional_render}
... </div>
# Or using the fact that ``None`` is not rendered:
>>> def render(self, context):
...
... part_if_true = part_if_false = None
...
... if self.flag:
... part_if_true = <span>It's TRUE</span>
... else:
... part_if_false = <p>It's FALSE</p>
...
... return <div>
... {part_if_true}
... {part_if_false}
... </div>
"""
)}</SourceCode>
</DocPart>
<DocPart kind="HtmlUtils" subkind="comments" id_prefix={id_prefix} level={self.h_level+1}>
<DocHeader menu="Comments">Comments</DocHeader>
<p>HTML and python comments are correctly handled but not rendered in the final HTLM.</p>
<DocPart kind="HtmlUtils" subkind="if-else-example" id_prefix="{id_prefix}" level={self.h_level+2} open>
<DocHeader menu="Example">Example</DocHeader>
<SourceCode language="python">{h.Raw(
# language=Python
"""
>>> class Component(Element):
... def render(self, context):
... return <div>
... <!-- inside the div -->
... Foo # bar?
... </div>
>>> print(<Component />)
<div>Foo</div>
""",
)}</SourceCode>
</DocPart>
</DocPart>
<Class h_level={self.h_level+1} id_prefix="{id_prefix}-" obj={resolve_class(
klass=html.Doctype,
attrs=[],
methods=[],
name='Doctype',
only_proptypes=['doctype'],
def render(self, context):
lexer = get_lexer_by_name(self.language, stripall=True)
return h.Raw(
highlight(str(self.children()[0]), lexer,
HtmlFormatter(cssclass="code")))
def render(self, context):
id_prefix = f'{self.id_prefix}Context'
return <DocPart kind="Context" id_prefix={id_prefix} level={self.h_level}>
<DocHeader menu="Context">Context</DocHeader>
<Rst>{h.Raw(
# language=RST
"""
**Context provides a way to pass data through the component tree without having to
pass props down manually at every level.**
In a typical Mixt application, data is passed top-down (parent to child) via props,
but this can be cumbersome for certain types of props (e.g. locale preference,
UI theme, authenticated user...) that are required by many components within an
application.
Context provides a way to share values like these between components without
having to explicitly pass a prop through every level of the tree.
A context is a simple element than simply render its children, passing itself
down the tree. So every element in a tree under a context, gain this context.
You cannot pass anything to a context. A context has a ``PropTypes`` class
defining the expected props and their types.
You can have many contexts in the tree. They are merged so their children elements
can access props of all of them. You just cannot set the same prop in these
different contexts.
"""
)}</Rst>
<DocPart kind="Context" subkind="example" id_prefix={id_prefix} level={self.h_level+1} open>
<DocHeader menu="Example">Example</DocHeader>
<SourceCode language="python">{h.Raw(
# language=Python
"""
>>> from mixt import BaseContext, Element, NotProvided, html
>>> class AuthenticatedContext(BaseContext):
... class PropTypes:
... auth_username: str
>>> class App(Element):
... def render(self, context):
... return <div>
... <if cond={context.prop('auth_username', None)}>
... Welcome back, {context.auth_username}.
... </if>
... <else>
... Hello. You need to idenfify yourself.
... </else>
... </div>
>>> print(<App />)
<div>Hello. You need to idenfify yourself.</div>
>>> who = 'John'
>>> print(
... <AuthenticatedContext auth_username={who}>
... <App />
... </AuthenticatedContext>
... )
<div>Welcome back, John.</div>
>>> who = NotProvided
>>> print(
... <AuthenticatedContext auth_username={who}>
... <App />
... </AuthenticatedContext>
... )
<div>Hello. You need to idenfify yourself.</div>
"""
)}</SourceCode>
def render(self, context):
id_prefix = f'{self.id_prefix}PropTypes'
return <DocPart kind="PropTypes" id_prefix={id_prefix} level={self.h_level}>
<DocHeader menu="PropTypes">PropTypes</DocHeader>
<Rst>{h.Raw(
# language=RST
"""
**PropTypes are at the heart of Mixt. The aim si to specify precisely
what kind of data a component is allowed to receive.**
It is then "strongly typed" (sort of). And of course largely inspired by React.
It works by defining a class named ``PropTypes`` inside your components. (see full
example below).
Then, you must define the type
(using the `python typing syntax <https://docs.python.org/3.6/library/typing.html>`_),
and, if you want, a default value. The format is ``prop_name: type`` or
``prop_name: type = default``.
"""
)}</Rst>
<DocPart kind="PropTypes" subkind="types" id_prefix={id_prefix} level={self.h_level+1} open>
<DocHeader menu="Special types">Special types</DocHeader>
<NamedValue id_prefix="{id_prefix}-types-" h_level={self.h_level+2} value={
datatypes.NamedValue(
name="Required",
type='',
doc=datatypes.SimpleDocString(
["By default all props are optional. Enclosing a prop type with ``Required[]`` make it... required."],
[
["Note: A required prop cannot have a default value."]
]
),
example=datatypes.Code(
# language=Python
"""
>>> from mixt import Required
>>> class Component(Element):
... class PropTypes:
... optional_prop: str
... required_prop: Required[str]
""", language="python"
)
)
} open_doc_details />
<NamedValue id_prefix="{id_prefix}-types-" h_level={self.h_level+2} value={
datatypes.NamedValue(
name="Choices",
type='',
doc=datatypes.SimpleDocString(
["``Choices`` allows to define a list of acceptable value."],
[
["In the ``PropTypes`` class, ``Choices`` is used as the type. And the value of this prop is the list of choices."]
]
),
example=datatypes.Code(
# language=Python
"""
>>> from mixt import Choices
>>> class Component(Element):
... class PropTypes:
... size: Choices = ['XS', 'S', 'M', 'L', 'XL', 'XXL']
""", language="python"
)
)
} open_doc_details />
<NamedValue id_prefix="{id_prefix}-types-" h_level={self.h_level+2} value={
datatypes.NamedValue(
name="DefaultChoices",
type='',
doc=datatypes.SimpleDocString(
["``DefaultChoices`` is like ``Choices`` but the first entry will be the default prop value."],
[]
),
example=datatypes.Code(
# language=Python
"""
>>> from mixt import DefaultChoices
>>> class Component(Element):
... class PropTypes:
... size: DefaultChoices = ['XS', 'S', 'M', 'L', 'XL', 'XXL']
>>> <Component />.size
'XS'
""", language="python"
)
)
} open_doc_details />