Define data and query needs for phase 1 pages

[briri]

We implemented the initial phase 1 pages using the entire large DMP json and relied on React to manage the entire structure even when the page was only referencing a small portion of it.

Lets go back and review those pages in https://dmptool-stg.cdlib.org along with the new wireframes for creating a plan, and define the exact data elements each page needs, and the queries/mutations that will need to be run on the Apollo server side.

[briri]

Initial Template creation page.

Workflow:

• Enter name
• Choose creation method
  • Start new
  • set any necessary defaults (to be defined)
  • load Template creation page
  • Start with previous (pick a template)
  • load template selection page (filters default to current user's Org)
  • copy contents of latest published version of selected template
    • Always use the latest published version if the template belongs to a different org/funder
    • Use the latest version of template if it belongs to the current org/funder (do we want to provide a UI option to the user to specify which version?)
  • use name entered on prior screen
  • load Template creation page
  • Start with Best Practice (pick a template / filtered)
  • load template selection page (filters default to DMPTool best practice)
  • copy contents of latest published version of selected template
  • use name entered on prior screen
  • load Template creation page

[jupiter007]

@andrewebdev @fraserclark @briri Here is some info I put together on what data and queries/mutations we might need for the initial Template Builder phase:

Page: Initial page

We will plan on passing the selected option of "previous template", "best practice template", or "new" template to the next page via a query param, instead of POSTing to the backend at this point.

Questions:

• What is the “Save” button for on this page? Is it to save the “Title” and “option”? Currently, the wireframe takes user to next page once they select a radio button option.

Answer: Fraser said that the “Save” button will probably be changed to “Next” or “Continue"

Page: Select an Existing Template

Queries:

query getAllTemplates($term: String!) {
    templates($name: $term) {
        publishedTemplates {
            id
            title
            owner
            description
            modified
        }
        bestPracticesTemplates {
            id
            owner
            title
            description
            modified
        }
    }

Mutations: When user selects an existing template, update our DB

mutation UpdateTemplate($id: ID!, $sourceTemplateId: Int) {
    updateTemplate(id: $id, sourceTemplateId: $sourceTemplateId)
}

Page: Template page

Enum:

enum TemplateOption {
    DRAFT
    PUBLISH
}

Queries:

query GetTemplate($id: ID!) {
     template(id: $id) {
        id
        name
        visibility
        owner
        currentVersion
        sections {
            id
            displayOrder
            name
                questions {}
        }
    }

Questions:

• Do we need to pass something in the mutation letting the backend know if this is saving as “draft” or “publish”?
• Where will the "comment" field be saved?

Mutations:

mutation SaveTemplate($id: ID!, $comment: String, $type: String) {
    updateTemplate(id: $id, comment: $comment, type: $type)
}

Page: Create a Template from Scratch

Queries:

query GetTemplate($id: ID!) {
    template(id: $id) {
    id
    name
    owner
       }
}

Mutations: Do we need to pass something in the mutation letting the backend know if this is saving as “draft” or “publish”?

mutation SaveTemplate($id: ID!, $comment: String, $type: String) {
    updateTemplate(id: $id, comment: $comment, type: $type)
}

Page: Add a New Section From Existing

Queries:

query GetAllSections($ownerID: String!) {
    sections(owner: $ownerID) {
        sections {
            id
            name
            displayOrder
            questions {}
        }
        bestPracticesSections {
            id
            name
            displayOrder
            questions{}
        }
    }

Page: Add a New Section from Scratch

Queries: To get Best Practices info to the right of the page

query GetBestPracticeSections {
    bestPracticeSections {
        requirements
        guidance
        tags
}

Mutations: To save the new section

mutation AddSection($templateId: ID!, $name: String!, $introduction: String, $requirements: String, $guidance: String) {
    addSection(templateId: $templateId, name: $name, introduction: $introduction, requirements: $requirements, guidance: $guidance) 
}

Page: Save and Publish

Mutations: Do we need to pass something in the mutation letting the backend know if this is saving as “draft” or “publish”?

mutation SaveTemplate($id: ID!, $comment: String, $type: String) {
    updateTemplate(id: $id, comment: $comment, type: $type)
}

[briri]

Use the latest version of template if it belongs to the current org/funder (do we want to provide a UI option to the user to specify which version?)

Great question. I think that would be a nice option. Maybe default to the latest version but have a link to 'prior versions' or something like that

[fraserclark]

I don't think you should allow the user to pick anything other than the latest version.

It should be seen as a "starter kit" so you jump-start the creation process, and not have to be stuck staring at a blank canvas.

I think its a bit of rabbit hole, As now you need a new screen or modal, showing the user the previous 5 versions. Next you need to communicate to the user the "differences" between versions - is the date enough, is it the optional changelog that people don't fill in accurately, is it the number of questions, the specific questions changes, the guidance text being changed... etc etc

[cazinc]

I would be a bit leery of trying to build a "version picker" in this stage too

There's already a lot of complexity in creating a template, and getting the UI right for picking from previous versions as a subchoice to picking from various previous templates of the user's own and DMP Tool's - and potential other related functionality this implies like version management elsewhere - could add a lot of time. Actually having said that, I think it would be a natural fit for a later phase where version management is more the focus (upgrading from the simple "log style" history we're building in this phase).

[briri]

👍🏻 yes all good points. I agree, it would be too much complexity especially at this point. I also suspect that 90% of use cases would want the current published version

[briri]

Initial page For the initial page of the template builder, When the user enters a name and then clicks one of the options about how they want to start (Copy a Best Practice, copy a prior, or start fresh), do we need to make a call to the backend? Can the name not just be retained in the front end? Then, when the user selects a template or clicks the button to start from scratch we make the call to the backend: createTemplate(name: string, fromTemplateId: number = null)

Template selection page I've added bestPractice as a boolean flag on the template. This means that the getAllTemplates query will return templates in a single array. They can then be filtered out/organized using that flag.

[jupiter007]

@briri I think that's a good idea. We could possibly pass the "from previous templates" or "best practice templates" or "new" option to the next page via a query param so that we can use that to know which queries to use for the keyword search.

[briri]

Question for you @jupiter007, After you make a call to create a resource like:

mutation UpdateTemplate($id: ID!, $sourceTemplateId: Int) {
    updateTemplate(id: $id, sourceTemplateId: $sourceTemplateId)
}

What would be the most useful return type for the front end? Is it enough to just send the new id of the newly created object?

[jupiter007]

@briri , can the frontend request what data they want back when they use the mutation? I could see needing other template fields other than the template id to populate some info on the page.

[briri]

we will return the entire object. the frontend can tell graphql what it needs