libervia-backend: doc/components.rst comparison

comparison doc/components.rst @ 3978:97fbe11c4476

doc (components/AP Gateway): `html_redirect_dict` option

author	Goffi <goffi@goffi.org>
date	Fri, 11 Nov 2022 13:51:22 +0100
parents	199598223f82
children	425d809a505b

comparison

equal deleted inserted replaced

-:6fa4ca0c047e
+:97fbe11c4476
 A boolean value indicating if received XMPP pubsub blog items bodies must be scanned to
 find ``@user@server.tld`` type mentions. If mentions are found, they'll be added to the
 resulting AP items.
 **default**: ``true``
+``html_redirect_dict``
+A dictionary use to redirect HTTP requests when it's not an ActivityPub request (i.e.
+when the ``Accept`` header is not set to ``application/json``). Several ActivityPub
+implementations link to original server when clicking on some links such as post author
+or item ID, and this result in a request to the corresponding ActivityPub endpoint, but
+made to retrieve HTML instead of ActivityPub JSON data.
+By default, this request is showing the corresponding AP JSON data, but if you set HTML
+redirection, you can redirect the page to your XMPP client web frontend (or anything
+making sense), which results in better user experience.
+The expected dictionary is a mapping URL request types to destination URL.
+The URL request types is the first path element after ``ap_path``, it can be:
+``actor``
+Actor information. It should link to the profile page of the corresponding XMPP entity
+``item``
+A specific publication. It should link to the rendered item
+``followers``
+Entities publicly subscribed to the actor. It is usually not used for redirection.
+``following``
+Entities that the actor is publicly subscribed to. It is usually not used for
+redirection.
+In the target URL you can uses template values in curly braces (something like
+``{item}``). The values that you can use are:
+``jid``
+Full JID corresponding to the AP actor.
+``jid_user``
+Only the user part of the JID (what is before the ``@``)
+``node``
+Name of the pubsub node corresponding to the AP actor.
+``item``
+ID of the XMPP pubsub item.
+You can use a slash ``/`` followed by a part of a node name to filter only on specific
+nodes. For instance, if you want to redirect microblog items to a different URL that
+event items, you can use ``item/urn:xmpp:microblog:0`` and ``item/urn:xmpp:events:0``,
+the first redirection to match will be used. Note that anything containing the filter
+value will match, thus you can also use ``item/microblog`` (but it then would match an
+event which has ``microblog`` in is node name).
+You can also use a dictionary as value instead of the target URL. This can be useful to
+filter on an other value than the node name, if you want to make specific redirection
+for a particular user for instance. If you use a dictionary, you must use a ``url`` key
+with the target URL (which may have template values as usual), and you may use a
+``filters`` key mapping to an other dictionary where each key is a filter on a specific
+template value (in other words: key is the template value, like ``jid`` or ``node``, and
+value is the filter to match).
+*examples*
+Redirect actor page to ``/profile/<JID user part>``, blogs items to ``/blog/<full
+JID>/<node name>/<item id>`` and events items to ``/event/<full JID>/<node name>/<item
+id>`` ::
+html_redirect_dict = {
+"actor": "/profile/{jid_user}",
+"item/microblog": "/blog/{jid}/{node}/{item}",
+"item/events": "/event/{jid}/{node}/{item}"
+}
+Redirect items of user ``louise@example.org`` to ``/b/<item>``::
+html_redirect_dict = {
+"item": {
+"url": "/b/{item}",
+filters: {
+"jid": "louise@example.org"
+}
+}
+}
 .. _ap-actor-from-xmpp:
 How to Address an AP Actor from XMPP

Mercurial > libervia-backend

comparison doc/components.rst @ 3978:97fbe11c4476