How to generate/control forms on Workflow/Publications

[jardakotesovec]

Issue description

There is long tradition on OJS creating Form configurations on backend PHP side. This will provide configuration for form and individual fields and than its rendered by Vue.js Form component. We are always passing these configurations on the page load as part of the page state.

This mostly works fine, but want to explore scenario where this approach is causing some tricky duplicated coding.

In 3.4, if you go to Workflow page as part of that page load it also generates all forms that are related for Publication (abstractTitle, metadata, citations, identifiers, issue, license). And these forms are generated in context of current publication and ready to be displayed with data and everything.

Where it gets problematic is once you have multiple publication versions and you switch between these. To update the forms with the different publication object, it unfortunately needs to do more than just update form values. But also handle things like maxLimit for abstract, or correct description for licenses base on given publication. These special cases are handled here and here. Thats not ideal.

And for 3.5 I would make it even worse. Because we have page load only for submission listing - so that opportunity for me to pass the form configurations to the client side. But these have even more thing missing (metadataLocales, other tricky fields description that require publication data), because at that point dashboard controller don't know what submission user will open.

Ideas how to make it better

I can think of only two options how to get around it:

1. Generate some forms client side - we might want to consider this approach in future. But this would be significant decision, which would require significant work to provide helpers on JS side, similarly like we have FormComponent and all related classes.

2. Create dedicated API endpoint to return form configuration in context of given publication. That should be quite quick and easy addition to the API and could look like

GET /submissions/{$submissionId}/publications/${publicationId}/form/titleAbstract

And it would simply return form configuration for given publication.

Implementation of such endpoint would roughly be something like:

        $locales = collect($submissionContext->getSupportedSubmissionMetadataLocaleNames() + $submission->getPublicationLanguageNames())
            ->map(fn (string $name, string $locale) => ['key' => $locale, 'label' => $name])
            ->sortBy('key')
            ->values()
            ->toArray();
        $latestPublicationApiUrl = $request->getDispatcher()->url($request, Application::ROUTE_API, $submissionContext->getData('urlPath'), 'submissions/' . $submission->getId() . '/publications/' . $selectedPublication->getId());
        $titleAbstractForm = $this->getTitleAbstractForm($latestPublicationApiUrl, $locales, $latestPublication, $submissionContext);
        $section = Repo::section()->get($selectedPublication->getData('sectionId'), $context->getId());
        $titleAbstractForm = TitleAbstractForm(
            $latestPublicationApiUrl,
            $locales,
            $selectedPublication,
            (int) $section->getData('wordCount'),
            !$section->getData('abstractsNotRequired')
        );

I think the logic can be literally cherry-picked from the WorkflowHander.php.

Additional considerations

• And in terms of the permissions - probably same as for given Publication. Not sure whether we hide some of the information for example for user.
• Additionally have to consider that there are also other 'components' like PublicatioNSectionJats, which also gets configured in publication context. So maybe would make sense to include these as well. And having /submissions/{$submissionId}/publications/${publicationId}/component/titleAndAbstract, so its more flexible.
• As alternative - having one endpoint providing all form/components configurations for given publication would technically work.. but that feels getting bit more UI specific than we would like. But open to that.

[asmecher]

Thanks for walking me through this, @jardakotesovec! I agree with your proposal to add an endpoint that exposes form state, potentially with a new e.g. submission, which can be used from the UI to update the VueJS state on a pre-existing form. I'd suggest prefixing the endpoint with a _ to indicate that it's subject to change (and probably not useful outside the dev team).

Down the road I think we're likely to reduce our server-side form generation, eventually doing all of that in VueJS. But that's too big for 3.5, so we're looking probably at an interim solution for 3.5 that's subject to change in 3.6 or 3.7 (when we have a good pattern to replace it fully on the client side and have the time to reduce tech debt). So re-using the existing PHP form classes as proposed makes sense as a limited intervention.

We talked a little about whether to code this up as a one-by-one exposure of form state at different API URLs, vs. allowing several to be fetched at once in a batch, and my intuition is that a batched fetch of several forms might be harder to maintain. But coding this up as a proof of concept might reveal what's easier/harder.

[ewhanson]

I'll do a bit more thinking about this, but some initial first thoughts:

I think taking approach number 2 of creating dedicated API endpoints is probably the best solution for our needs at the moment. I also like the idea of keeping them to a _'d namespace that is flagged pretty much for internal use only. I also think any form generating endpoints should all be located within this scope as I don't think we'd want to open up "forms-as-a-service" as part of the official API. Keeping all the form generating endpoints contained there and adding them as needed seems like a solid approach and also give us one place to maintain them (and eventually yank them out if that's the direction we go in).

To @asmecher point of whether these should be coded on a one-by-one basis or grouping them, I would favour having one API endpoint per thing we're trying to fetch. If we find we need things in batches, I suspect we could come up with some pattern to collect these nicely in JS, but as these things grow in complexity, having one endpoint do only one thing seems like a good approach.

[jardakotesovec]

@ewhanson From frontend point of view, I don't have any strong preferences about the url, or whether it would be batched or not. Especially given that this is likely being intermittent solution. So I would say whatever is more practical and make the security also easy to cover. Its important to note, that these forms comes with actual values. So these needs to follow same permissions as we would (in case of publication forms) apply on publications. Thats why I was suggesting to put it behind publications/{publicationId}/_components or _forms, but not sure if that make things easier to align with publication permissions

[ewhanson]

I will look into that. It would be nice to take advantage of any authorization that's already happening in e.g. the publications API controller.

[nils-stefan-weiher]

Thats why I was suggesting to put it behind publications/{publicationId}/_components or _forms, but not sure if that make things easier to align with publication permissions

I would also agree to that!