GraphQL (Construction Process of Mutation)

How the data flows through a GraphQL Mutation back-to-front

1. Write the mutation query in SQL. This goes in /types/queries. This particular one updates the document table in the database.

2. This gets used in /src/database_sql.rs as a DataLoader. DocumentMetadataUpdate is a GraphQL InputObject defined elsewhere in a rust file (/src/document.rs) and will match with what we give it in the front end.

3. This is the InputObject. All fields under it also need to be InputObjects as well or it will not compile. Here, written_at has a custom DateInput type that will allow it to be used as a field here, since the Date type based off the built-in Date type from the chrono library is not one.

4. This is the DateInput type created for this mutation. Notice the function on line 57. It allows us to convert DateInput into Date. And if you look back to the image on point 2 line 408, we map that conversion in order to send the date values into the query as a Date type. The front-end DatePicker generates a Date type, we convert it into a DateInput and use that down until database_sql.rs where we change it back into the Date type.

5. This part in /graphql/src/query.rs connects the back-end to the GraphQL front-end. We can give it a UserGroup guard as done here if needed. It calls the DataLoader from database_sql.rs and runs it.

6. This part in /graphql/src/queries.graphql connects directly to that function in queries.rs shown in point 5. In line 327, it needs to take in the InputObject being used for the mutation. The name (in yellow can be anything). In line 328, updateDocumentMetadata is what it needs to be named. It is the camelCase version of the function in queries.rs. If you put something like, updateDocumentMetadata2, it won’t link to the function in query.rs and won’t work.

7. To use the mutation in the TypeScript front-end, we need to create a form context to send our user-inputted values into the GraphQL mutation (which connects further down to change the SQL database). In line 19, declare document as the fragment in queries.graphql. This provides a structure for how we send data into the form. You can see it is based off the fields existing in the AnnotatedDoc type in index.ts. It is called again line 32 downwards (values: { document },) See the runUpdate on line 44. document is of type DocumentMetadataUpdate InputObject defined in document.rs. For id, title, and writtenAt, we pass in the values collected from the fragment. Right hand side values need to be convertible into left hand side values. In the case of writtenAt, (if a value is inputted) we send it in as a typescript object {date, month year}. In point 4 the DateInput object can be created in that way. So it can be passed in like that.

8. The last step is the part that is actually visible by the user on the website. This EditDocPanel component has the document prop, since that is where we extract the document id to be sent into the mutation. Line 68 calls useForm() which is imported from the form context at the bottom of point 7's image.

In this case, the data is being sent into the from using 2 methods. The first method is using a `FormInput`, which is used for the `title` field. We use `FormInput` whenever we want the user to input a text field. Lines 111 to 122 handle the labelling and input field of the title value. Lines 124 to 136 handle the labelling and picking (not input) of the date value. It is using an external library to select a date (no longer being used in current DAILP website deploy. We had to change it).

9. This part of the EditDocPanel component handles the input of the id and writtenAt values. Whenever a change is made to the DatePickerComponent, the state changes to reflect that. In useEffect, we manually push the id and date values to be used in the form. This is how to send predetermined values into the form. This function is found on unstable_FormState<V> in the node module /website/node_modules/reakit/ts/Form/FormState.d.ts file

In Summary...

edit-doc-data-panel.tsx collects user input and sends it to form defined in edit-doc-data-form-context.tsx. With those values, it calls runUpdate which uses the GraphQL UpdateDocumentMetadata mutation.

Line 328 updateDocumentMetadata is the camelCase of update_document_metadata in queries.rs and links this GraphQL mutation to it. Then, it calls the DataLoader in database_sql.rs which calls the SQL file mutation which updates the database.