core.elements
=============

.. py:module:: core.elements

.. autoapi-nested-parse::

   Elements are mini chameleon macros, usually used to render a single
   element. Sometimes it is useful to not just apply a macro, but to have an
   actual object representing that code snippet. The prime example being links.

   Elements are rendered in chameleon templates by calling them with the layout
   object::

       <tal:b replace="structure element(layout)" />

   Note that no matter how quick the elements rendering is, using chameleon
   templates directly is faster.

   This module should eventually replace the elements.py module.



Classes
-------

.. autoapisummary::

   core.elements.Element
   core.elements.AccessMixin
   core.elements.Link
   core.elements.Button
   core.elements.BackLink
   core.elements.LinkGroup
   core.elements.Trait
   core.elements.Confirm
   core.elements.Block
   core.elements.Intercooler


Module Contents
---------------

.. py:class:: Element(text: str | None = None, attrs: dict[str, Any] | None = None, traits: collections.abc.Iterable[Trait] | Trait = (), **props: Any)

   Provides a way to define elements trough multiple variables. These
   elements may then be rendered by the elements.pt templates.

   Elements are simple, they render whatever text and attributes the get.
   They also carry a dictionary with properties on them, so any kind of
   value may be attached to an element. For example this works::

       user = object()
       element = Element(model=user)
       assert element.user == user

   Since we might use a complex set of attributes which need to be set in
   a certain way we use a traits system to avoid having to rely too heavily
   on class inheritance.

   Basically traits are callables called with attributes which they may
   manipulate. For example, a trait might turn a simple argument into
   a set of attributes::

       Element(traits=[Editor(buttons=['new', 'edit', 'delete'])])

   See the link traits further down to see examples.



   .. py:attribute:: id
      :type:  ClassVar[str | None]
      :value: None



   .. py:attribute:: __slots__
      :value: ('text', 'attrs', 'props')



   .. py:attribute:: text
      :value: None



   .. py:attribute:: props


   .. py:attribute:: attrs


   .. py:method:: normalize_attrs(attrs: dict[str, Any] | None) -> dict[str, Any]

      Before we do anything with attributes we make sure we can easily
      add/remove classes from them, so we use a set.




   .. py:method:: __eq__(other: object) -> bool


   .. py:method:: __getattr__(name: str) -> Any


   .. py:method:: __call__(layout: core.layout.ChameleonLayout, extra_classes: collections.abc.Iterable[str] | None = None) -> markupsafe.Markup


.. py:class:: AccessMixin

   Hidden links point to views which are not available to the public
   (usually through a publication mechanism).

   We mark those links with an icon. This mixin automatically does that
   for links which bear a model property.



   .. py:attribute:: __slots__
      :value: ()



   .. py:property:: access
      :type: str


      Wraps model.access, ensuring it is always available, even if the
      model does not use it.




.. py:class:: Link(text: str | None, url: str = '#', attrs: dict[str, Any] | None = None, traits: collections.abc.Iterable[Trait] | Trait = (), **props: Any)

   Bases: :py:obj:`Element`, :py:obj:`AccessMixin`


   A generic link. 


   .. py:attribute:: id
      :value: 'link'



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __repr__() -> str


.. py:class:: Button(text: str | None, url: str = '#', attrs: dict[str, Any] | None = None, traits: collections.abc.Iterable[Trait] | Trait = (), **props: Any)

   Bases: :py:obj:`Link`


   A generic button. 


   .. py:attribute:: id
      :value: 'button'



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __repr__() -> str


.. py:class:: BackLink(text: str = '', **props: Any)

   Bases: :py:obj:`Link`


   A button that goes back in the history. 


   .. py:attribute:: id
      :value: 'back_link'



   .. py:attribute:: __slots__
      :value: ()



   .. py:method:: __repr__() -> str


.. py:class:: LinkGroup(title: str, links: collections.abc.Sequence[Link], model: Any | None = None, right_side: bool = True, classes: collections.abc.Collection[str] | None = None, attributes: dict[str, Any] | None = None)

   Bases: :py:obj:`AccessMixin`


   Represents a list of links. 


   .. py:attribute:: __slots__
      :value: ['title', 'links', 'model', 'right_side', 'classes', 'attributes']



   .. py:attribute:: title


   .. py:attribute:: links


   .. py:attribute:: model
      :value: None



   .. py:attribute:: right_side
      :value: True



   .. py:attribute:: classes
      :value: None



   .. py:attribute:: attributes
      :value: None



.. py:class:: Trait

   Base class for all traits. 


   .. py:attribute:: __slots__
      :value: ('apply',)



   .. py:attribute:: apply
      :type:  collections.abc.Callable[[dict[str, Any]], dict[str, Any]]


   .. py:method:: __call__(attrs: dict[str, Any], **ignored: Any) -> dict[str, Any]


.. py:class:: Confirm(confirm: str, extra: str | None = None, yes: str | None = 'Yes', no: str = 'Cancel', **ignored: Any)

   Bases: :py:obj:`Trait`


   Links with a confirm link will only be triggered after a question has
   been answered with a yes::

       link = Link(_("Continue"), '/last-step', traits=(
           Confirm(
               _("Do you really want to continue?"),
               _("This cannot be undone"),
               _("Yes"), _("No")
           ),
       ))



   .. py:attribute:: __slots__
      :value: ()



   .. py:attribute:: apply


.. py:class:: Block(message: str, extra: str | None = None, no: str = 'Cancel', **ignored: Any)

   Bases: :py:obj:`Confirm`


   A block trait is a confirm variation with no way to say yes. 


   .. py:attribute:: __slots__
      :value: ()



.. py:class:: Intercooler(request_method: Literal['GET', 'POST', 'DELETE'], target: str | None = None, redirect_after: str | None = None, **ignored: Any)

   Bases: :py:obj:`Trait`


   Turns the link into an intercooler request. As a result, the link
   will be exeucted as an ajax request.

   See http://intercoolerjs.org.


   .. py:attribute:: __slots__
      :value: ()



   .. py:attribute:: apply