4teamwork/ftw.pdfgenerator — Issue #4: Layout customization standard
Author: jone
Created: 2012-03-09 11:07:01+00:00
State: open

``ftw.pdfgenerator`` should provide a common way to customize unknown layouts for simple adjustments, such as providing a logo or changing the font. This allows us to customize multiple distinct layouts defined by multiple packages without customizing every single layout.

This should be approached by providing a general customization adapter ``ILayoutCustomization(context, request, layout)``, used by the ``MakoLayoutBase``.

Implementation:

- New interface ``ICustomizableLayout(ILaTeXLayout)``, marking a layout as customizable
- New interface ``ILayoutCustomization``
- New adapter ``LayoutCustomization``, implementing ``ILayoutCustomization``, adapting ``context, request, layout``
- has a ``before_render_hook()`` method, called after the ``before_render_hook`` of the adapted layout and used for adding additional ``use_package`` statements or other customizations.
- has a ``get_render_arguments(self, args)``, adding additional arguments to the passed arguments dict
- implements ``ITemplating``.
- setting ``template_directories`` results in a merged template lookup (original layout lookup directories + layout customization directories)
- setting ``template_name`` overrides the template defined by original layout and has to inherit from ``original_layout``, which is a alias for the real template of the original layout.
- A layout providing ``ICustomizableLayout`` has to define some mako blocks:
- ``documentclass``: contains the document class definition
- ``usePackages``: contains the use_packages statements (usually contains ${packages})
- ``beneathPackages``: empty block beneath ``usePackages```
- ``aboveDocument``: empty block right before ``\begin{document)``
- ``documentTop``: empty block right after ``\begin{document}``
- ``documentBottom``: empty block at the end of the document, before ``\end{document}``
- A layout providing ``ICustomizableLayout`` should insert ``${logo}`` somewhere, which may contain a ``\includegraphics{}`` command, meant to place a logo in the layout. It may be empty or not defined.
- ``ftw.pdfgenerator`` should provide some inheritable base tests:
- a base test for layouts implementing ``ICustomizableLayout``
- a base test for customization adapters implementing ``ILayoutCustomization``