Mitigate Browse / Search UI Code and Template Fragmentation

[techgique]

While looking at some PRs for both Whitman Rails and Habeas Corpus, I thought there was a lot of under utilization of Orchid Sections, but stepping back I now see that there are some places where it seemed like Orchid Sections was being conflated with Search Presets and just isn't necessary for the pages. There is a bit of fragmentation in how Search (Preset) pages are used across sites. I'll try to outline the different designs.

Some Orchid sites are using the whole range of pages and capabilities of Orchid Sections. WCA Letters is probably the best example, which makes sense as that is what Orchid Sections was originally built for. It has a custom home page, but beyond that it is using Browse routes with section-configured facets. The search pages use all of the search UI with a search box and facets. This kind of site functionality needs Orchid Sections.

Other sites have pages which are providing a search box and facets but no links to the browse routes. Whitman Scribal Documents is such an example. This requires Orchid Sections to use/customize the faceting, but it's not relying on Orchid Sections code and templates. I think this page should be using the main search template just with the header and intro text customized via overriding the header partial. Otherwise it is the same layout as the main search. Writing a controller action like for a Search Preset and the customized template nearly recreating the main search layout seems like both extra work and improvements in Orchid won't be automatically included because of overrides. But I can understand how one gets here after learning Orchid and using Search Presets elsewhere.

The next type of page I see is a Search Preset page but with the search box added back in. These sites aren't using the browse routes or facets of Orchid Sections with these subsets of documents as far as I've noticed. Habeas Case Documents and Whitman Manuscripts are examples of this. This page design doesn't use or need Orchid Sections, but is used many times throughout Whitman and Habeas Corpus. This example for Whitman is not using Orchid Sections (https://github.com/whitmanarchive/whitmanarchive_rails/blob/master/config/routes.rb#L58), but Habeas Corpus has an Orchid Section configured but currently unused (https://github.com/CDRH/habeascorpus/blob/master/config/routes.rb#L4).

Lastly we have pages which originated the need for Search Presets which have little to no search UI other than perhaps sorting and pagination. I think these were more intended as a starting point for making custom browse pages rather than for searching. I think it started with pages like the Cody Archive Books page. A more recent example using Orchid is Cather's Books page.

So we have a variety of different designs / use cases. The first and last require less overriding of Orchid code / templates out of the box, but the middle two cases where Search UI is being customized page by page were not really anticipated in past Orchid development. I worry this will lead to fragmentation across sites and away from Orchid itself due to lots of repetitive adding / redefining of code / templates. This will make it harder to keep things consistent over time and for Orchid improvements to make their way to apps using it without having to review all of each app's additional / overriding code and templates.

Potential Solution

I think the way to improve this situation will be to create additional methods and templates in Orchid that will handle the aspects of the middle cases where we're using some search UI for pages intended to search/browse a subset of a site's documents but not using faceting and browse routes. The goal will be to minimize redefining controller actions and templates and instead only configure the information that changes:

• API filter (e.g. "category|Documents")
• Page title
• Intro / header HTML
• Search UI config

I'm envisioning adding a new action to Orchid's items controller named something like browse_subset that all such pages can reuse and the API filter could be set by defining a route for a page such as Habeas Case Documents like:

get "/documents", to: "items#browse_subset", as: :documents_home, defaults: { api_filter: ["category|Documents"] }

And then a template file could be written with the same name as the path name so Orchid knows where to look. The template will provide the page title, intro / header HTML, and search UI config.

app/views/browse_subset/_documents_home.html.erb:

<%
  @page_title = "Case Documents"
%>
<%# Header HTML %>
<p>Here are the case documents available in TEI format…</p>
<%
  @search_ui = {
    input: true,
    sort_and_pagination: true,
    item_count: false,
    date_limiting: false,
    summary_boxes: false,
    …
  }
%>

This search UI config approach could be used in Orchid Sections as well to further reduce fragmentation in the code base. Some of this might be simplified by standardizing our page design, but I don't think we anticipated our needs varying so much depending on the subsets of documents. I imagine we will have more varying needs over time, so I hope we can find approaches to avoid fragmentation long-term.

[karindalziel]

Revisit with greg

[karindalziel]

This is about implementation in orchid, might be addressed in documentation, not code

[karindalziel]

see #238