diff -r 7205ae7c43dc -r d632f8d6140b src/source/dev_guide/internals.rst --- a/src/source/dev_guide/internals.rst Thu Dec 20 17:59:43 2018 +0100 +++ b/src/source/dev_guide/internals.rst Fri Dec 21 15:20:06 2018 +0100 @@ -3,6 +3,7 @@ Understanding PyAMS internals ============================= + Annotations ----------- @@ -12,11 +13,334 @@ Namespaces ---------- + +.. _renderer: + +Renderers +--------- + +**Renderer** are the layout of the utility data content. A renderer combine un context, a skin and +a template to produce the front office html + + To create new renderer you can override an already exist renderer or create a new one from scratch. Steps below + we will create a renderer for a `IContact` paragraph + + +HTML renderer +------------- + +Chameleon +^^^^^^^^^ + +To generate html page with dynamic content PyAMS renderer use Chameleon as a template engine + +Once *pyramid_chameleon* been activated **.pt** templates can be loaded either by looking names +that would be found on the Chameleon search path. + + +.. seealso:: + + https://chameleon.readthedocs.io/en/latest/ + https://zope.readthedocs.io/en/latest/zope2book/ZPT.html + + + +PyAMS defines a custom expression for TALES called *extension*. + +This expression are used in the html template (.pt) to ease to display +or manipulate content. + + +.. _tales: + TALES Extensions ---------------- -Renderers ---------- +PyAMS defines a custom expression for TALES called *extension*. + +When this expression is encountered, the renderer is looking for an +:py:class:`ITALESExtension ` +multi-adapter for the current *context*, *request* and *view*, for the current +*context* and *request*, or only for the current *context*, in this order. +If an adapter is found, the renderer call it's :py:func:`render` method with +the expression parameters as input parameters. + +For example, the *metas* extension is an *ITALESExtension* adapter defined into +:py:mod:`pyams_skin.metas` module which can be used to include all required headers in +a page template. Extension is used like this in the page layout template: + +.. code-block:: html + + + +This extension is defined like this: + +.. code-block:: python + + from pyams_skin.interfaces.metas import IHTMLContentMetas + from pyams_utils.interfaces.tales import ITALESExtension + from pyramid.interfaces import IRequest + + from pyams_utils.adapter import adapter_config, ContextRequestViewAdapter + + @adapter_config(name='metas', context=(Interface, IRequest, Interface), provides=ITALESExtension) + class MetasTalesExtension(ContextRequestViewAdapter): + '''extension:metas TALES extension''' + + def render(self, context=None): + if context is None: + context = self.context + result = [] + for name, adapter in sorted(self.request.registry.getAdapters((context, self.request, self.view), + IHTMLContentMetas), + key=lambda x: getattr(x[1], 'order', 9999)): + result.extend([meta.render() for meta in adapter.get_metas()]) + return '\n\t'.join(result) + +Some TALES extensions can require or accept arguments. For example, the *absolute_url* extension can accept +a context and a view name: + +.. code-block:: html + + + + + +The extension is defined like this: + +.. code-block:: python + + from persistent.interfaces import IPersistent + from pyams_utils.interfaces.tales import ITALESExtension + + from pyams_utils.adapter import adapter_config, ContextRequestViewAdapter + from pyramid.url import resource_url + from zope.interface import Interface + + @adapter_config(name='absolute_url', context=(IPersistent, Interface, Interface), provides=ITALESExtension) + class AbsoluteUrlTalesExtension(ContextRequestViewAdapter): + '''extension:absolute_url(context, view_name) TALES extension''' + + def render(self, context=None, view_name=None): + if context is None: + context = self.context + return resource_url(context, self.request, view_name) + + +.. _talesext: + +List of PyAMS TALES extensions +------------------------------ + +Reformat text +^^^^^^^^^^^^^ + +- br + *br*\(value, class) TALES expression + +This expression can be used to context a given character (‘|’ by default) into HTML breaks with given CSS class. + +For example: + + ${tales:br(value, 'hidden-xs')} + +If value is "Raining| cats and dogs", the output will be "Raining cats and dogs". + +---- + +- html + *html*\(value) + +Replaces line breaks in plain text with appropriate HTML (
). + +If value is: + +| "Raining +| cats +| and +| dogs" + +The output will be "Raining
cats
and
dogs". + + +---- + +- truncate + *truncate*\(value, length, max) + +Truncates a string if it is longer than the specified length of characters. Truncated strings will end with ellipsis sequence (“…”). + + +For example: + + ${tales:truncate(value,9, 0)} + +If value is "Raining cats and dogs", the output will be "Raining...". + + ${tales:truncate(value,9, 1)} + +If value is "Raining cats and dogs", the output will be "Raining cats...". + + +---- + +- i18n + *i18n*\(value) + +Return sentence according to the context user’s language, the value is a dict. + + +Utilities +^^^^^^^^^ + +- oid + *oid*(value) + +Return the **oid** of the value + +---- + +- cache_key + *cache_key*\(value) + +Return an unique ID based of the component value + +---- + +- timestamp + +Return incremental number based on the time past in second + + + +Media +^^^^^ + + +- picture + *picture*\(value, lg_thumb='banner', md_thumb='banner', sm_thumb='banner',xs_thumb='banner', css_class='inner-header__img', alt=alt_title) + +Search the illustration associated with the value. +Return the first illustration found, by order: the component definition, content illustration navigation and content illustration + +[lg, md, sm, xs]*_thumb + - banner + - pano + - portrait + - square + +[lg, md, sm, xs]*_width + [1-12] boostrat column size + +css_class + add a css class to the container of this illustration () + +img_class + add a css class to the balise + +alt + alternative title + + +---- + +- thumbnails + *thumbnails*\(value) + +---- + +- thumbnail + *thumbnail*\(value, (value, lg_thumb='banner', md_thumb='banner', sm_thumb='banner',xs_thumb='banner', css_class='inner-header__img', alt=alt_title) + +Search the image associated with the value. + +[lg, md, sm, xs]*_thumb + - banner + - pano + - portrait + - square + +[lg, md, sm, xs]*_width + [1-12] boostrat column size + +css_class + add a css class to the container of this illustration () + +img_class + add a css class to the balise + +alt + alternative title) + +---- + +- conversions + *conversion*\(value) + +Return the list of conversion format supported by the value + +---- + +- audio_type + *audio_type*\(value) + +Return the type of the audio media + +---- + +- video_type* + *video_type*\(value) + +Return the type of the video media + + +Find a resource +^^^^^^^^^^^^^^^ + +- absolute_url + *absolute_url*\(object) + +Used to get access to an object URL + +---- + +- canonical_url + *canonical_url*\(context,request) + +Used to get access to an uniq object URL, based on current request display context + +---- + +- relative_url + *relative_url*\(context, request) + + Used to get an object's relative URL based on current request display context + +---- + +- *resource_path*\(value) + +Generates an URL matching a given Fanstatic resource. +Resource is given as a string made of package name as value (in dotted form) followed by a colon and by the resource name. + +---- + +- *need_resource*\(value) + + +This extension generates a call to Fanstatic resource.need() function to include given resource +into generated HTML code. +Resource is given as a string made of package name as value (in dotted form) followed by a colon and by the resource name. + +For example: + +.. code-block:: + + + + +---- + Sequences ---------