Refactor of interview list page

[nonprofittechy]

Here's the high level overview (also possible to get it from the code. currently this message is duplicated in one long comment at the top of the file)

Customize by:

1. Editing the global configuration (see below), or

2. Including this file and overriding the default values in a replacement YAML file

   Relevant options and defaults:

   app homepage: https://courtformsonline.org
   assembly line:
   enable answer sets: True
   interview list:
     page title: In progress forms # Title of the tab in your browser
     page question: In progress forms
     page subquestion: null
     new form label: Start a new form
     new form url: https://courtformsonline.org
     logo url: null # Defaults to `app homepage`
     logo image url: https://app.yourserver.org/packagestatic/docassemble.AssemblyLine/ma_logo.png
     logo image alt: Logo
     answer sets title: Answer sets
     logo title row 1: null # Defaults to `interview page title`
     logo title row 2: null # Defaults to `interview page heading`
     exclude from interview list:
       - docassemble.AssemblyLine:data/questions/al_saved_sessions_store.yml
       - docassemble.AssemblyLine:data/questions/interview_list.yml

   interview page title, interview page heading, interview page pre, logo url, interview page url, and new form url can also be set to a dictionary of languages, like:

   interview page title:
     en: In progress forms
     es: Formularios en progreso

   These deprecated configuration options will also be respected at a lower priority:

   new form url: https://courtformsonline.org
   assembly line:
   exclude from interview list:
     - docassemble.AssemblyLine:data/questions/al_saved_sessions_store.yml
     - docassemble.AssemblyLine:data/questions/al_saved_sessions_store.yml

   As will the following options from the global config:

   interview page title
   interview page heading
   interview page pre

   Some authors will prefer to customize this page by importing it and overriding the default values in the YAML file rather than the global configuration. This is slightly more advance than editing the configuration, but may be just as easy to maintain. To do this, make a new YAML file and include your custom theme/settings YAML. It's important to include your theme AFTER the interview list page:

   e.g., my_new_interview_list.yml would only need to contain:

   ---
   include:
   - docassemble.AssemblyLine:data/questions/interview_list.yml
   - docassemble.MyState:my_custom_theme.yml
   ---
   metadata:
   title: |
     In progress forms
   short title: |
     In progress forms

   Then you would set the following in your global config:

   interview list: docassemble.MyState:my_new_interview_list.yml

   In some instances, this may be all that is required to use your branding on the interview list page. You can individually override additional variables as follows:

   • PAGE_QUESTION
   • PAGE_SUBQUESTION
   • NEW_FORM_LABEL
   • NEW_FORM_URL
   • al_sessions_to_exclude_from_interview_list

   The following settings are usually best to leave undefined if you want the ordinary behavior of your theme:

   • PAGE_TITLE
   • LOGO_URL
   • LOGO_IMAGE_URL
   • LOGO_IMAGE_ALT
   • LOGO_TITLE_ROW_1
   • LOGO_TITLE_ROW_2 (defaults to value from the metadata block)

   And of course you can also override the YAML block by block if you want to further customize it.

[nonprofittechy]

This very deliberately does not work in the same way as pages that are normally included inside another package. It's installed systemwide and is made so people can change its behavior without forking it. Forking and then changing the global config to point to your custom version of the file is a pretty advanced technique at the moment, while this basic version of the file is installed by the dashboard install script.

I think I described this in more detail on our Friday call.

In contrast, the assembly_line.yml and dependencies are all included into another interview. You can override and control their behavior naturally, by adding a different value for the variable in the file that you already are editing.

Edit: another point is that this is a server wide file. It's not uncommon to co-host orgs on one server. Like Suffolk hosts Northeast Legal Aid and MassLegalHelp content.

Does that all make sense?

The use of AL_ORGANIZATION_HOMEPAGE, etc is only for backwards compatibility with the custom version of this that @BryceStevenWilley made. I didn't document that intentionally. I'm interested to know if he's open to changing or removing his fork or if he thinks this backwards compatibility is still useful.

[nonprofittechy]

I'm interested to know if he's open to changing or removing his fork or if he thinks this backwards compatibility is still useful.

Yeah, please keep the backwards compatibility. IMO, the maintenance and mental burden of 3 lines of YAML in a wrapper interview is much simpler than 15 lines of config, especially for things like logo alt text and interview page pre. It's nice that the configs are all in the same place now, but I would 100% need to go look at the actual interview to figure out the difference between "interview page title", "interview page heading", and "interview page pre".

Agreed that the names are not the clearest. The only reason I'm sticking with those names is because they are existing names from the Docassemble global configuration.

See: https://docassemble.org/docs/config.html#customization

[BryceStevenWilley]

The only reason I'm sticking with those names is because they come from the Docassemble global configuration.

Why? It makes the fallback code you have a few lines shorter, but I thought the point of this PR was to move configs around and make it cleaner. You could add some params to the get_config_fallback function so it has both the new name and the old name.

Agreed that the names are not the clearest.

The names could be better, but to be clear even with better names, I still feel like I'd need to look at the actual interview.

[nonprofittechy]

The only reason I'm sticking with those names is because they come from the Docassemble global configuration.

Why? It makes the fallback code you have a few lines shorter, but I thought the point of this PR was to move configs around and make it cleaner. You could add some params to the get_config_fallback function so it has both the new name and the old name.

Agreed that the names are not the clearest.

The names could be better, but to be clear even with better names, I still feel like I'd need to look at the actual interview.

Any suggestions for better names? This is open to @plocket too.

Cost/benefit of renaming the options that mirror Docassemble's existing options for doing the identical task seems low to me. But I haven't thought of names that are a lot better--maybe it will be worth it?

[BryceStevenWilley]

Any suggestions for better names?

If they matched the DA attribute they're used in, that would be nice

• interview_page_title could stay the same
• interview_page_header -> interview_page_question
• interview_page_pre -> interview_page_subquestion

Cost/benefit of renaming the options that mirror Docassemble's existing options for doing the identical task seems low to me

My general take (idk how right it is) is that DA has 1,000 things to keep track of; unless it's something commonly used in writing an interview, most people won't know what they are, would have to look it up, and probably struggle to do so in docassemble's documentation (i.e. my workflow with settings like this).

[plocket]

Bryce's choices make more sense to me on principle. I do wish list could be in the name somewhere, but unless we do list_page_subquestion or something like that, it gets pretty long.