document /static/ endpoint of merchant and how to customize templates

1 files changed, 50 insertions, 0 deletions

diff --git a/taler-merchant-manual.rst b/taler-merchant-manual.rst
index 392b3037..4517974d 100644
--- a/taler-merchant-manual.rst
+++ b/taler-merchant-manual.rst
@@ -923,6 +923,56 @@ fully exposed to the Internet, and wallets may have to interact with those
 endpoints directly without client authentication.
 
 
+Customization
+=============
+
+Templates
+---------
+
+The installation process will install various HTML templates to be served
+to trigger the wallet interaction. You may change those templates to your
+own design. The templating language used is Mustach, and the templates
+are in the ``share/taler/merchant/templates/`` directory.
+
+
+Static files
+------------
+
+The merchant backend also has the ability to serve small static files
+under the ``/static/{FILENAME}`` endpoint.  This is used by the templating
+logic to load a CSS file, but you can also put other resources such as
+images or JavaScript.
+
+Internationalization
+--------------------
+
+Both templates and static files can be internationalized.  This is done
+by having the language of the resource be a part of the filename.
+For templates the format is ``{BASENAME}.{LANGUAGE}.must``.  The
+language is mandatory for templates, the default language is English (en).
+
+For static files, the format is ``{BASENAME}.{LANGUAGE}.{EXT}`` for
+internationalized files, and ``{BASENAME}.{EXT}`` for resources that do not
+support internationalization.  The HTTP client will always request
+``/static/{BASENAME}.{EXT}``. If ``{BASENAME}.{EXT}`` exists, that resource is
+returned. Otherwise, an internationalized file based on the language
+preferences indicated by the browser is returned.
+
+Limitations
+-----------
+
+All of the static files must fit into memory and it must be possible for the
+process to hold open file handles for all of these files.
+
+The backend determines the mime type based on the file's extension. The list
+of supported extensions is hard-coded and includes common text and image
+formats.
+
+The current backend only provides a limited set of variables for the Mustach
+template expansion, and does not make use of scopes and other Mustach
+features.
+
+
 
 Upgrade procedure
 =================