document challenger forms

1 files changed, 152 insertions, 0 deletions

diff --git a/taler-challenger-manual.rst b/taler-challenger-manual.rst
index e4a59ee6..c45dcb1d 100644
--- a/taler-challenger-manual.rst
+++ b/taler-challenger-manual.rst
@@ -519,3 +519,155 @@ The Challenger database can be re-initialized using:
 
 However, running this command will result in all data in the database
 being lost.
+
+
+.. _ChallengerCustomization:
+
+Template Customization
+======================
+
+The Challenger service comes with various HTML templates that are shown to
+guide users through the process. Challenger uses `Mustach
+<https://gitlab.com/jbol/mustach>`__ as the templating engine.  This section
+describes the various templates.  In general, the templates must be installed
+to the ``share/challenger/templates/`` directory. The file names must be of
+the form ``$NAME.$LANG.must`` where ``$NAME`` is the name of the template and
+``$LANG`` is the 2-letter language code of the template. English templates
+must exist and will be used as a fallback.  If the browser (user-agent) has
+provided language preferences in the HTTP header and the respective language
+exists, the correct language will be automatically served.
+
+The following subsections give details about each of the templates. The
+subsection title is the ``$NAME`` of the respective template.
+
+enter-$ADDRESS_TYPE-form
+------------------------
+
+These templates are used to ask the user to enter the address that challenger
+is expected to validate. Here, ``$ADDRESS_TYPE`` will be replaced by the
+``ADDRESS_TYPE`` configuration option in the ``[challenger]`` section of the
+configuration file.  Typical values include ``address`` (for physical mailing
+addresses), ``phone`` (for mobile phone numbers) and ``email`` (for email
+addresses). For testing, ``file`` (where the TAN code is written into a local
+file) is also supported.
+
+The template is instantiated using the following information:
+
+  * fix_address: boolean; indicates if the given address cannot be changed
+    anymore, the form should be read-only if set to true.
+
+  * nonce: String; unique value identifying the challenge, should be shown
+    to the user so that they can recognize it when they receive the TAN code
+
+  * last_address: Object; form values from the previous submission if available,
+    details depend on the ``ADDRESS_TYPE``, should be used to pre-populate the form
+
+  * changes_left: Integer; number of times the address can still be changed,
+    may or may not be shown to the user
+
+enter-tan-form
+--------------
+
+This page should generate the HTML form for the user to enter the TAN code
+that they received at the respective address.
+
+The template is instantiated using the following information:
+
+  * nonce: String; unique value identifying the challenge, should be shown
+    to the user so that they can match it to the TAN code they received
+
+  * attempts_left: Integer; how many more attempts are allowed, might be
+    shown to the user, highlighting might be appropriate for low values
+    such as 1 or 2 (the form will never be used if the value is zero)
+
+  * address: Object; the address that is being validated, might be shown
+    or not
+
+  * transmitted: boolean; true if we just retransmitted the challenge,
+    false if we sent a challenge recently and thus refused to transmit it
+    again this time; might make a useful hint to the user
+
+  * next_tx_time: String; timestamp explaining when we would re-transmit
+    the challenge the next time (at the earliest) if requested by the user
+
+
+invalid-pin
+-----------
+
+The user has provided an invalid TAN code (HTTP 403 Forbidden).
+
+The template is instantiated using the following information:
+
+  * ec: Integer; numeric Taler error code, should be shown to indicate the
+    error compactly for reporting to developers
+
+  * hint: String; human-readable Taler error code, should be shown for the
+    user to understand the error
+
+  * addresses_left: Integer; how many times is the user still allowed to
+    change the address; if 0, the user should not be shown a link to jump
+    to the address entry form
+
+  * pin_transmissions_left: Integer; how many times might the PIN still
+    be retransmitted
+
+  * auth_attempts_left: Integer; how many times might the user still try
+    entering the PIN code
+
+If both *pin_transmissions_left* and *auth_attempts_left* are zero, the link
+to re-enter the PIN should be hidden and the user should only be allowed to
+specify a different address. The form will never be generated if all three
+values are zero. (Thus there is always at least one valid choice when the form
+is shown.)
+
+
+validation-unknown
+------------------
+
+The user has tried to access a validation process that is not known to the
+backend (HTTP 404 Not Found).
+
+The template is instantiated using the following information:
+
+  * ec: Integer; numeric Taler error code, should be shown to indicate the
+    error compactly for reporting to developers
+
+  * hint: String; human-readable Taler error code, should be shown for the
+    user to understand the error
+
+  * detail: String; optional, extended human-readable text provided to elaborate
+    on the error, should be shown to provide additional context
+
+
+invalid-request
+---------------
+
+The request of the client is invalid (HTTP 400 Bad Request).
+
+The template is instantiated using the following information:
+
+  * ec: Integer; numeric Taler error code, should be shown to indicate the
+    error compactly for reporting to developers
+
+  * hint: String; human-readable Taler error code, should be shown for the
+    user to understand the error
+
+  * detail: String; optional, extended human-readable text provided to elaborate
+    on the error, should be shown to provide additional context
+
+
+internal-error
+--------------
+
+The service experienced an internal error (HTTP 500 Internal Server Error).
+
+The template is instantiated using the following information:
+
+  * ec: Integer; numeric Taler error code, should be shown to indicate the
+    error compactly for reporting to developers
+
+  * hint: String; human-readable Taler error code, should be shown for the
+    user to understand the error
+
+  * detail: String; optional, extended human-readable text provided to elaborate
+    on the error, should be shown to provide additional context