Closes #3899.

Fixes #4291.
Fixes #4042.
Fixes #4321.

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.

This PR introduces a standard pattern for keeping track of main tasks through a sequence of side task views and templates.

It includes:

• half a dozen new template tags and logic functions

• numerous updates to views and templates, especially to avoid hard-coding unpredictable URL elements

• new documentation both where it was missing and for new code

• ~40 new tests (see note below on middleware)

• fixing four bugs encountered in doing this work

• migrations for the removal of two deprecated fields that held outdated help text

• refactoring the user_login_orcid function (see note below)

• migrations for updated setting values related to password resets and account confirmation

Note on one change to the middleware

Testing the templates across themes is very difficult when using the Django test Client, because of the way we load theme directories. Initially I wrote a helper that would allow me to patch template_override_middleware.Loader.get_theme_dirs. It looked like this:

def get_theme_dirs(journal):
    """
    Together with the mock library,
    this lets you test public-facing views, once for each theme.

    Example usage:

    @patch('utils.template_override_middleware.Loader.get_theme_dirs')
    def test_a_view_for_each_theme(self, get_theme_dirs):
        for theme_dirs in testing_helpers.get_theme_dirs():
            get_theme_dirs.response_value = theme_dirs
            response = self.client.get('/my/path/', {})
            self.assertIn(
                'The text I am looking for',
                response.content.decode(),
            )
    """
    request = Request()
    request.journal = journal
    with request_context(request):
        engine = Engine()
        loader = template_override_middleware.Loader(engine)
        dirs = loader.engine.dirs
        return [
            [os.path.join(settings.BASE_DIR, 'themes', 'clean', 'templates')] + dirs,
            [os.path.join(settings.BASE_DIR, 'themes', 'OLH', 'templates')] + dirs,
            [os.path.join(settings.BASE_DIR, 'themes', 'material', 'templates')] + dirs,
        ]

However this did not work, because the Django test client handles the creation of the request independently. It gives you no way to modify the request when using Client.get. So the request used in my helper was different than the one used in the test, and the theme dirs were missing a lot of template locations that are important for includes in the templates I am testing. Basically, the Django test client’s request is artificially stale in comparison to Janeway’s typical requests.

To make the test run in an environment that more closely resembles production, I decided to make use of the simple query parameter theme=clean and theme=OLH, which we use for debugging. I expanded the if clause to include settings.IN_TEST_RUNNER.

If there is another way of mocking the themes comprehensively which can be used effectively with the Django test Client, I’m happy to consider it.

Note on integration with ORCiD

There is some tricky juggling of view logic and context in between this branch and the ORCiD work that Esther has been putting through.

Esther and I successfully merged some of our work in Esther’s PR about prefilling the registration form with info from ORCiD.

But there is another PR that has been open since Sept 2024 that this work will interfere with. @ajrbyers please assign me as a reviewer if you would like me to work with Esther to resolve the differences.

In terms of the ORCiD work on this branch, the user_login_orcid view was getting really complicated and hard to read, so I refactored the view logic and documented the behavior with comments. Hopefully it is now clear how next and action work independently but are both needed in the state parameter that is sent to ORCiD authentication and received back.

Future work

If we like this implementation, we can eventually refactor existing return URLs using the same pattern, so that we do not have to reason about code like this: