--- 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 <pyams_utils.interfaces.tales.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
+
+ <tal:var replace="structure extension:metas" />
+
+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
+
+ <tal:var define="logo config.logo">
+ <img tal:attributes="src extension:absolute_url(logo, '++thumb++200x36.png');" />
+ </tal:var>
+
+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 <br class='hidden-xs'> cats and dogs".
+
+----
+
+- html
+ *html*\(value)
+
+Replaces line breaks in plain text with appropriate HTML (<br>).
+
+If value is:
+
+| "Raining
+| cats
+| and
+| dogs"
+
+The output will be "Raining<br>cats<br>and<br>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 (<picture>)
+
+img_class
+ add a css class to the <img> 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 (<picture>)
+
+img_class
+ add a css class to the <img> 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::
+
+ <tal:var define="tales:need_resource('pyams_content.zmi:pyams_content')" />
+
+
+----
+
Sequences
---------