Merge pull request #3953 from open-formulieren/docs/service-fetch-and…

…-template-filters-regex

Add more documentation

docs/configuration/general/external_services.rst

@@ -0,0 +1,123 @@
+.. _configuration_general_external_services:
+
+=================
+External services
+=================
+
+Open Forms can write and read information to and from external systems. This is great
+when you need to integrate with existing (JSON) APIs, SOAP webservices or HTTP endpoints
+in general.
+
+The connection parameters to these services are configurable in the admin interface,
+provided you have administrator permissions (typically this would be a different role
+than the people creating/managing forms).
+
+.. note:: If you got to this page via the manual and don't have permissions
+   to manage services, please contact your functional administrator.
+
+.. _configuration_general_external_services_api_services:
+
+(API) services
+==============
+
+We group services that (mostly) talk JSON under the (API) services. While they can be
+used for data in formats other than JSON, they are generally simpler to use and
+configure compared to SOAP and/or StUF-based services.
+
+Examples of this type of services are:
+
+* the ZGW API's
+* the Objects API
+* Haal Centraal services (BRP personen bevragen, KVK, Kadaster...)
+
+To configure such a service, you need to have:
+
+* the base URL where the service is hosted
+* credentials (if relevant), like an API key or client ID/secret
+
+Configuring a service
+---------------------
+
+#. In the admin interface, navigate to **Configuration** > **Services**.
+
+#. Click **Add a service** to bring up the configuration form.
+
+#. Fill out the form fields:
+
+    * **Label**: provide a recognizable label. This will be displayed in dropdowns to
+      select a service.
+
+    * Either enter the URL to the OpenAPI specification or upload a file. For *most*
+      services you can use a :ref:`dummy OAS <dummy_oas>` since these fields have become
+      obsolete (and will be removed in a future update).
+
+    * **Type**: Select the appropriate type or if none is relevant, select ``ORC (Overige)``.
+
+    * **API root URL**: the base URL where the API is hosted. All API endpoints will be
+      added relative to this. For example: ``https://example.com/api/``.
+
+    * **Client ID** and **Secret** - these are only relevant when the **Authorization type**
+      is set to ``ZGW client_id + secret``.
+
+    * **Header key** the header name for the API credential when the **Authorization type**
+      is set to ``API key``. Examples are: ``Authorization`` or ``X-API-Key`` - the value
+      depends on your API provider.
+
+    * **Header value** the API credential when the **Authorization type**
+      is set to ``API key``. The exact value and format depends on your API provider.
+      Some examples are: ``Token <api key>`` or just plainly
+      ``e2c98134-3dc8-4134-88fc-aec604bf8394``.
+
+    * If mutual TLS or particular server certificates are involved (typically
+      certificate chains signed by the G1 root), you can manage these through the
+      **Client certificate** and **Server certificate** fields. See also our support
+      for :ref:`self-signed certificates <installation_self_signed>` in the installation
+      documentation.
+
+    * The remaining form fields can be left blank.
+
+#. Click **Save** to persist the configuration.
+
+.. _dummy_oas:
+
+.. code-block:: yaml
+    :caption: Dummy OAS
+
+    version: 3.0.0
+    info:
+      title: Dummy
+      version: 1.0.0
+    paths: {}
+
+SOAP (and StUF) services
+========================
+
+.. note:: StUF services requires a SOAP service to be configured as they are a layer on
+   top of SOAP.
+
+Configuring a SOAP service
+--------------------------
+
+#. In the admin interface, navigate to **Configuration** > **SOAP services**.
+
+#. Click **Add a SOAP service** to bring up the configuration form.
+
+#. Fill out the form fields:
+
+    * **Label**: provide a recognizable label. This will be displayed in dropdowns to
+      select a service.
+
+    * **URL**: if you're defining a StUF-service, this field can be left blank because
+      the StUF endpoints are defined elsewhere. Otherwise, you must specify the URL
+      where SOAP messages are sent to.
+
+    * If mutual TLS or particular server certificates are involved (typically
+      certificate chains signed by the G1 root), you can manage these through the
+      **Client certificate** and **Server certificate** fields. See also our support
+      for :ref:`self-signed certificates <installation_self_signed>` in the installation
+      documentation.
+
+    * The remaining form fields are optional and configuration depends on the particular
+      service you're connecting with.
+
+#. Click **Save** to persist the configuration.

docs/configuration/general/index.rst

@@ -10,6 +10,7 @@ General configuration
    analytics
    cookies
    oidc
+   external_services
    cms_integration
    virus_scan
    payment_flow

docs/manual/forms/examples/service_fetch.rst

@@ -4,13 +4,8 @@
 Formulier met waarden uit externe registraties
 ==============================================
 
-.. note::
-
-   Dit voorbeeld maakt gebruik van de **preview** functionaliteit "Bevragen
-   registraties", welke onder **Configuratie** > **Algemene configuratie** >
-   **Feature flags, test- en ontwikkelinstellingen** in te schakelen is.
-
-In dit voorbeeld maken we een deel van een formulier bestaande uit één stap. De uitgangspunten zijn:
+In dit voorbeeld maken we een deel van een formulier bestaande uit één stap. De
+uitgangspunten zijn:
 
 * de `dummyjson-service`_ bied een lijst van productcategorieën aan
 * de service biedt ook een lijst van producten aan, per categorie
@@ -23,6 +18,27 @@ basis van data uit een externe service.
 We gaan ervan uit dat u een :ref:`formulier met geavanceerde logica
 <example_advanced_logic>` kunt maken.
 
+Service aanmaken
+================
+
+.. note:: Het kan zijn dat je onvoldoende rechten hebt om services aan te maken. Indien
+   je deze rechten niet hebt, vraag dan aan een functioneel beheerder om de
+   :ref:`service in te stellen <configuration_general_external_services>`.
+
+#. Navigeer in de beheeromgeving naar **Configuratie** > **Services**.
+
+#. Klik op de **Service toevoegen** knop.
+
+#. Vul de formuliervelden in:
+
+    * **Label**: ``dummyJSON``
+    * **OAS URL**: ``https://tinyurl.com/dummyjson-oas``
+    * **Type**: ``ORC (Overige)``
+    * **API root url**: ``https://dummyjson.com/``
+    * **Authorization type**: ``No authorization``
+
+#. Klik op **Opslaan**.
+
 Formulier maken
 ===============
 

docs/manual/forms/form_fields.rst

@@ -177,8 +177,8 @@ Basis
 * **Show Character Count**: Indien aangevinkt, dan wordt een teller getoond aan
   de eindgebruiker met het aantal karakters dat is ingevuld.
 
-Location
---------
+Locatie
+-------
 
 * **Straatnaam afleiden**: Indien aangevinkt, dan zal in dit veld automatisch de
   straatnaam worden ingevuld op basis van het ingevulde postcode en huisnummer.
@@ -211,6 +211,70 @@ Stel er zijn 4 velden:
   Er is nu een formulier gemaakt waarbij de straat en de stad automatisch worden
   ingevuld als de postcode en het huisnummer zijn ingevuld.
 
+Validatie
+---------
+
+* **Reguliere expressie**: een patroon waar de veldwaarde aan moet voldoen. Reguliere
+  expressies zijn een soort van programmeertaal die snel erg complex kunnen worden. Op
+  regex101_ kun je deze uitproberen.
+
+  We hebben een aantal kant-en-klare patronen die je als inspiratie kan gebruiken.
+
+  ================ ===================== ===============================================
+  Expressie        Voorbeeldwaarde       Toelichting
+  ================ ===================== ===============================================
+  ``[0-9]*``       0123                  Een onbeperkt aantal getallen
+  ``\d*``          0123                  Een onbeperkt aantal getallen - ``\d`` is
+                                         equivalent aan ``[0-9]``
+  ``[0-9]{1,3}``   42                    Een tekst van minimaal 1 en maximaal 3
+                                         posities, waarbij elk karakter een getal moet
+                                         zijn
+  ``[a-zA-Z]``     X                     Eén (hoofdletterongevoelige) ASCII letter
+  ``[\w]{1,5}``    aF\_4                 1 tot 5 alfanumerieke karakters of liggend
+                                         streepje. ``\w`` is equivalent aan
+                                         ``[a-zA-Z0-9_]``
+  ================ ===================== ===============================================
+
+  Hieronder vind je nog een aantal concrete voorbeelden hoe je dit kan toepassen.
+
+
+  **Een Duits kenteken**
+
+  ``[a-zA-Z]{1,3}-[a-zA-Z]{1,2}\d{1,4}``
+
+  ==================    =====================
+  Voorbeeldwaarde       Geldig
+  ==================    =====================
+  AaA-Aa111             ✓
+  aA-aA1                ✓
+  a-AA1234              ✓
+  ==================    =====================
+
+  **Een 4 cijferige pincode**
+
+  ``[0-9]{4}``
+
+  ==================    =====================
+  Voorbeeldwaarde       Geldig
+  ==================    =====================
+  1234                  ✓
+  12                    ✗
+  12345                 ✗
+  ==================    =====================
+
+  **Een woonplaats die moet overeenkomen**
+
+  ``Formulierendam``
+
+  ===================   =====================
+  Voorbeeldwaarde       Geldig
+  ===================   =====================
+  Formulierendam        ✓
+  **f**\ormulierendam   ✗
+  ===================   =====================
+
+
+.. _regex101: https://regex101.com/
 
 Keuzelijst
 ==========

docs/manual/templates.rst

@@ -144,16 +144,62 @@ Expressie                           Voorbeeld waarde                   Toelichti
 ``{{ now|date:"Y" }}``              ``2022``                           Huidig jaar
 ``{{ now|date:"F" }}``              ``augustus``                       Huidige maandnaam
 ``{{ now|date:"l" }}``              ``dinsdag``                        Huidige dagnaam
+``{{ now|date:"W" }}``              ``34``                             ISO-8601 weeknummer
 ``{{ now|time:"H:i" }}``            ``09:08``                          Huidig tijstip (uren en minuten)
 ``{{ now|time:"H:i:s" }}``          ``09:08:42``                       Huidig tijstip (uren, minuten en seconden)
-``{{ now|date:"W" }}``              ``34``                             ISO-8601 weeknummer
 ``{{ legeVariabele|default:"-" }}`` ``-``                              Terugvalwaarde indien de variabele "leeg" is
 ``{{ filesize|filesizeformat }}``   ``117,7 MB``                       Weergave van bytes (nummer) in leesbare vorm
 ``{{ consent|yesno:"ok,niet ok"}}`` ``niet ok``                        Weergave op basis van ``True``/ ``False`` waarde
+``{{ getal|add:"2" }}``             ``5``                              Equivalent van de som ``getal + 2``
+``{{ getal|add:"-2" }}``            ``1``                              Verminder de variabele ``getal`` met 2
+``{{ getal|floatformat }}``         ``3,1``                            Rond een getal af op één decimaal als er een
+                                                                       decimaal gedeelte is
+``{{ getal|floatformat }}``         ``3``                              Indien er geen decimaal gedeelte is, toon dan
+                                                                       geen decimalen
+``{{ getal|floatformat:"2" }}``     ``3,00``                           Rond altijd het getal af op twee decimalen
+``{{ getal|floatformat:"-2" }}``    ``3``                              Rond het getal af op twee decimalen als er een
+                                                                       decimaal gedeelte is
+``{{ getal|floatformat:"2g" }}``    ``3.000,00``                       De ``g`` suffix past groepering toe
+``{{ getal|stringformat:"i" }}``    ``2023``                           Geef de waarde (als integer) zonder groepering
+                                                                       van duizendtallen
+``{{ lijst|join:", " }}``           ``a, b, c``                        Voeg elementen in een lijst van waarden samen,
+                                                                       gescheiden door een komma
+``{{ variabele|length }}``          ``12``                             Bereken de lengte van een lijst of string
+``{{ variabele|lower }}``           ``kleine letters``                 Converteer een tekst naar kleine letters
+``{{ variabele|upper }}``           ``HOOFDLETTERS``                   Converteer een tekst naar hoofdletters
+``{{ value|timesince }}``           ``1 week, 2 dagen``                Tijd geleden, relatief ten opzichte van "nu"
+``{{ value|timesince|yesterday }}`` ``1 dag``                          Tijd geleden, relatief ten opzichte van de
+                                                                       variabele ``yesterday``
+``{{ value|timeuntil }}``           ``1 week, 2 dagen``                Tijd tot, relatief ten opzichte van "nu"
+``{{ value|timeuntil|tomorrow }}``  ``1 dag``                          Tijd tot, relatief ten opzichte van de variabele
+                                                                       ``tomorrow``
+``{{ variabele|title }}``           ``Een Omgezette Tekst``            Maak alle woorden startend met hoofdletter, de
+                                                                       rest worden kleine letters
+``{{ variabele|truncatechars:5 }}`` ``Twee…``                          Breek tekst af tot 5 karakters
+``{{ variabele|truncatewords:3 }}`` ``Eén twee …``                     Breek tekst af tot 3 woorden
+``{{ variabele|urlize }}``          ``<a href="$url">$url</a>``        Maak hyperlinks in de variabele klikbaar
+``{{ getal|divisibleby:"3" }}``     ``True``                           ``True``/``False`` indien de variabele wel/niet
+                                                                       deelbaar is
+``{{ lijst|first }}``               ``Eerste waarde``                  Geef het eerste element in een lijst van waarden
+                                                                       terug
 =================================== ================================== ================================================
 
-.. note:: Op dit moment krijgt u altijd de Nederlandse vertalingen/lokalisatie.
-   Er is nog geen ondersteuning voor andere talen.
+Je kan ook meerdere filters combineren om geavanceerde manipulaties te doen,
+bijvoorbeeld:
+
+.. code-block:: django
+
+    {{ today|date:'Y'|add:"-1"|stringformat:"i" }}
+
+In het jaar 2024 produceert dit de output ``2023``:
+
+#. ``today`` is een ``datetime`` met de waarde 29 februari 2024
+#. ``today|date:'Y'`` leidt tot enkel het jaar, dus ``2024``
+#. ``1`` aftrekken van ``2024`` geeft ``2023``
+#. Tot slot wordt ``2023`` als integer weergegeven zodat de output ``2023`` is en niet
+   ``2.023`` (dus zonder groepering van duizendtallen)
+
+.. note:: Sjablonen worden in dezelfde taal/localisatie gerenderd als de taal van de inzending.
 
 Template tags
 -------------