URL Routing
===========

Preserving app state with the next parameter
--------------------------------------------

Users often have a main task (e.g. submit an article) and a side task (e.g. log in / register) that they need to complete during the main task.

When Janeway invites them to start the side task, it registers the URL of the main task on a `next` parameter, like Django does by default. Then at the end of the side task, it redirects them to the main task, so they can pick back up where they left off.

Login and registration are a common side task, but Janeway does not use Django’s built-in `auth_views` because of legacy reasons and the need to support authentication via third-party services like ORCiD and OpenID Connect (OIDC). As a result, we handle `next` via custom template tags and explicit checks in the associated views.

  1. To initiate a `next` parameter in the main task template, use the `url_with_return` template tag (not the normal `url` tag) to form the URL that begins the side task. This will capture the current request URL as the return destination. Note that this can be recursive: you can initiate a side task from a side task, and the current next URL will be nested properly and encoded safely within the query string of the new URL that will be assigned to `next`.

  2. Then, to preserve that `next` parameter through a sequence of views and templates, use the `url_with_next` template tag. Note: there is also a variant called `url_with_next_and_orcid_action` for situations where the ORCiD action needs to be passed as well.

In all views related to the side task, make sure to check the GET request parameters for `next`, and pass them along in one of two ways:

  * If redirecting to another step in the side task: use `logic.reverse_with_next` when reversing the URL.

  * If the side task is concluded, redirect to the value of `next`.

Note that the `next` state is always transmitted as GET request parameter, and so it will always be visible in the query string. This is possible because Django makes GET parameters from the query string in the HTTP header available even when the request method is POST. Successive requests to the same endpoint will not remove or change the query string, even if the request method changes; only redirects in the view, or reformations of an `href` or form `action` in the template, can change it. While it is not often desirable to make use of both GET and POST data, we do it intentionally here for a few reasons: the `next` pattern is consistent across views, and we avoid interfering with the payload of actual form data sent via POST.