18 Renderers

    59 PyAMS defines a custom expression for TALES called *extension*.

    19 ---------

    60 

    61 When this expression is encountered, the renderer is looking for an

    62 :py:class:`ITALESExtension <pyams_utils.interfaces.tales.ITALESExtension>`

    63 multi-adapter for the current *context*, *request* and *view*, for the current

    64 *context* and *request*, or only for the current *context*, in this order.

    65 If an adapter is found, the renderer call it's :py:func:`render` method with

    66 the expression parameters as input parameters.

    67 

    68 For example, the *metas* extension is an *ITALESExtension* adapter defined into

    69 :py:mod:`pyams_skin.metas` module which can be used to include all required headers in

    70 a page template. Extension is used like this in the page layout template:

    71 

    72 .. code-block:: html

    73 

    74     <tal:var replace="structure extension:metas" />

    75 

    76 This extension is defined like this:

    77 

    78 .. code-block:: python

    79 

    80     from pyams_skin.interfaces.metas import IHTMLContentMetas

    81     from pyams_utils.interfaces.tales import ITALESExtension

    82     from pyramid.interfaces import IRequest

    83 

    84     from pyams_utils.adapter import adapter_config, ContextRequestViewAdapter

    85 

    86     @adapter_config(name='metas', context=(Interface, IRequest, Interface), provides=ITALESExtension)

    87     class MetasTalesExtension(ContextRequestViewAdapter):

    88         '''extension:metas TALES extension'''

    89 

    90         def render(self, context=None):

    91             if context is None:

    92                 context = self.context

    93             result = []

    94             for name, adapter in sorted(self.request.registry.getAdapters((context, self.request, self.view),

    95                                                                           IHTMLContentMetas),

    96                                         key=lambda x: getattr(x[1], 'order', 9999)):

    97                 result.extend([meta.render() for meta in adapter.get_metas()])

    98             return '\n\t'.join(result)

    99 

   100 Some TALES extensions can require or accept arguments. For example, the *absolute_url* extension can accept

   101 a context and a view name:

   102 

   103 .. code-block:: html

   104 

   105     <tal:var define="logo config.logo">

   106         <img tal:attributes="src extension:absolute_url(logo, '++thumb++200x36.png');" />

   107     </tal:var>

   108 

   109 The extension is defined like this:

   110 

   111 .. code-block:: python

   112 

   113     from persistent.interfaces import IPersistent

   114     from pyams_utils.interfaces.tales import ITALESExtension

   115 

   116     from pyams_utils.adapter import adapter_config, ContextRequestViewAdapter

   117     from pyramid.url import resource_url

   118     from zope.interface import Interface

   119 

   120     @adapter_config(name='absolute_url', context=(IPersistent, Interface, Interface), provides=ITALESExtension)

   121     class AbsoluteUrlTalesExtension(ContextRequestViewAdapter):

   122         '''extension:absolute_url(context, view_name) TALES extension'''

   123 

   124         def render(self, context=None, view_name=None):

   125             if context is None:

   126                 context = self.context

   127             return resource_url(context, self.request, view_name)

   128 

   129 

   130 .. _talesext:

   131 

   132 List of PyAMS TALES extensions

   133 ------------------------------

   134 

   135 Reformat text

   136 ^^^^^^^^^^^^^

   137 

   138 - br

   139 	*br*\(value, class) TALES expression

   140 

   141 This expression can be used to context a given character (‘|’ by default) into HTML breaks with given CSS class.

   142 

   143 For example:

   144 

   145 	${tales:br(value, 'hidden-xs')}

   146 

   147 If value is "Raining| cats and dogs", the output will be "Raining <br class='hidden-xs'> cats and dogs".

   148 

   149 ----

   150 

   151 - html

   152 	*html*\(value)

   153 

   154 Replaces line breaks in plain text with appropriate HTML (<br>).

   155 

   156 If value is:

   157 

   158 | "Raining

   159 | cats

   160 | and

   161 | dogs"

   162 

   163 The output will be "Raining<br>cats<br>and<br>dogs".

   164 

   165 

   166 ----

   167 

   168 - truncate

   169 	*truncate*\(value, length, max)

   170 

   171 Truncates a string if it is longer than the specified length of characters. Truncated strings will end with ellipsis sequence (“…”).

   172 

   173 

   174 For example:

   175 

   176 	${tales:truncate(value,9, 0)}

   177 

   178 If value is "Raining cats and dogs", the output will be "Raining...".

   179 

   180 	${tales:truncate(value,9, 1)}

   181 

   182 If value is "Raining cats and dogs", the output will be "Raining cats...".

   183 

   184 

   185 ----

   186 

   187 - i18n

   188 	*i18n*\(value)

   189 

   190 Return sentence according to the context user’s language, the value is a dict.

   191 

   192 

   193 Utilities

   194 ^^^^^^^^^

   195 

   196 - oid

   197 	*oid*(value)

   198 

   199 Return the **oid** of the value

   200 

   201 ----

   202 

   203 - cache_key

   204 	*cache_key*\(value)

   205 

   206 Return an unique ID based of the component value

   207 

   208 ----

   209 

   210 - timestamp

   211 

   212 Return incremental number based on the time past in second

   213 

   214 

   215 

   216 Media

   217 ^^^^^

   218 

   219 

   220 - picture

   221 	*picture*\(value, lg_thumb='banner', md_thumb='banner', sm_thumb='banner',xs_thumb='banner', css_class='inner-header__img', alt=alt_title)

   222 

   223 Search the illustration associated with the value.

   224 Return the first illustration found, by order: the component definition, content illustration navigation  and content illustration

   225 

   226 [lg, md, sm, xs]*_thumb

   227 	- banner

   228 	- pano

   229 	- portrait

   230 	- square

   231 

   232 [lg, md, sm, xs]*_width

   233 	[1-12] boostrat column size

   234 

   235 css_class

   236 	add a css class to the container of this illustration (<picture>)

   237 

   238 img_class

   239 	add a css class to the <img> balise

   240 

   241 alt

   242 	alternative title

   243 

   244 

   245 ----

   246 

   247 - thumbnails

   248 	*thumbnails*\(value)

   249 

   250 ----

   251 

   252 - thumbnail

   253 	*thumbnail*\(value, (value, lg_thumb='banner', md_thumb='banner', sm_thumb='banner',xs_thumb='banner', css_class='inner-header__img', alt=alt_title)

   254 

   255 Search the image associated with the value.

   256 

   257 [lg, md, sm, xs]*_thumb

   258 	- banner

   259 	- pano

   260 	- portrait

   261 	- square

   262 

   263 [lg, md, sm, xs]*_width

   264 	[1-12] boostrat column size

   265 

   266 css_class

   267 	add a css class to the container of this illustration (<picture>)

   268 

   269 img_class

   270 	add a css class to the <img> balise

   271 

   272 alt

   273 	alternative title)

   274 

   275 ----

   276 

   277 - conversions

   278 	*conversion*\(value)

   279 

   280 Return the list of conversion format supported by the value

   281 

   282 ----

   283 

   284 - audio_type

   285 	*audio_type*\(value)

   286 

   287 Return the type of the audio media

   288 

   289 ----

   290 

   291 - video_type*

   292 	*video_type*\(value)

   293 

   294 Return the type of the video media

   295 

   296 

   297 Find a resource

   298 ^^^^^^^^^^^^^^^

   299 

   300 - absolute_url

   301 	*absolute_url*\(object)

   302 

   303 Used to get access to an object URL

   304 

   305 ----

   306 

   307 - canonical_url

   308 	*canonical_url*\(context,request)

   309 

   310 Used to get access to an uniq object URL, based on current request display context

   311 

   312 ----

   313 

   314 - relative_url

   315 	*relative_url*\(context, request)

   316 

   317  Used to get an object's relative URL based on current request display context

   318 

   319 ----

   320 

   321 - *resource_path*\(value)

   322 

   323 Generates an URL matching a given Fanstatic resource.

   324 Resource is given as a string made of package name as value (in dotted form) followed by a colon and by the resource name.

   325 

   326 ----

   327 

   328 - *need_resource*\(value)

   329 

   330 

   331 This extension generates a call to Fanstatic resource.need() function to include given resource

   332 into generated HTML code.

   333 Resource is given as a string made of package name as value (in dotted form) followed by a colon and by the resource name.

   334 

   335 For example:

   336 

   337 .. code-block::

   338 

   339 	<tal:var define="tales:need_resource('pyams_content.zmi:pyams_content')" />

   340 

   341 

   342 ----

   343