Handle reference document edits

[mingard]

Overview

When selecting, editing or removing a referenced document we need to present the user with:

1. An interface to create or edit a document
2. An interface to select one or many referenced documents

Proposal for selection

As per the media interface selection interface, a user will be taken to the collection list view where they'll have similar functionality to the standard list view. Allowing them to select documents. The only action will be ability to add the selected referenced documents.

Proposal for creation

Creation would take you through to the edit view for the document in it's appropriate collection, except the save button will have two options: (Perhaps post MVP)
Create now - Create now and return to parent document
Create on Save - Created when parent document is saved

URL

Current: {group?}/{collection}/document/edit/{_id}/{section}
Proposed for selection: {group?}/{collection}/document/edit/{_id}/{section}/{field?}/{page?}
Proposed for create/edit: {group?}/{collection}/document/edit/{_id}/{section}/{field?}/{_id}

Example selection: /magazine/articles/document/edit/xxxxxxx/meta/publication

[eduardoboucas]

Couple of questions/thoughts:

I take it what we're moving away from the selectize-style approach used in the previous incarnation of the app — do we think that didn't work well? Wouldn't this be an easier way to select a referenced document without ever leaving the editor? Perhaps not great for media...

By launching both the document list and document edit views in a "nested mode", won't that be confusing to users? Will we be able to maintain a smooth editing workflow without users losing track of where they are in the process?

[mingard]

By launching both the document list and document edit views in a "nested mode", won't that be confusing to users?

That's already part of the design for media, I'm just thinking we extend this to selection of sub documents to avoid effectively recreating the document list view (search, filtering, display) in a selectize style list.

[mingard]

Will we be able to maintain a smooth editing workflow without users losing track of where they are in the process?

I see that as a UX challenge. We face this regardless, as this is how media is presented

[mingard]

See page 28 in Redux

[eduardoboucas]

I'm happy with this and your URL structure makes perfect sense. We'll need some logic to detect a document ID versus a page number so we can distinguish between the Proposed for selection and Proposed for create/edit URLs, which we could potentially avoid by adding another keyword to the URL. I assume the reasoning to not do it this way is to prevent the URL from getting even longer. I'm happy either way.

I've been thinking about how the stores would adapt to this, since at the moment we only store the state of the document currently being edited and now we'll need to keep the state of the parent when editing a nested document. I don't think we should rely on local storage for this, because we should see local storage as an enhancement and not the central source of truth (users may disable access to local storage altogether at browser-level).

Instead, I propose we add a parents array to the store, which we'd use as a stack. This would remain empty for as long as we're editing top-level documents, but if you start editing a nested document, we'd push the state of the parent document (local, remote, validationErrors) to the stack and load the nested document onto the main fields of the store. It'd look something like:

Editing a top-level document:

{
  local: {_id: 1234567, ...},
  parents: [],
  remote: {_id: 1234567, ...},
  remoteStatus: Constants.STATUS_IDLE,
  validationErrors: {}
}

Editing a nested document:

{
  local: {_id: 7654321, ...},
  parents: [{_id: 1234567, ...}],
  remote: {_id: 7654321, ...},
  remoteStatus: Constants.STATUS_IDLE,
  validationErrors: {}
}

This has the following advantages:

1. Maintains the structure of the store as fas as its consumers are concerned. We keep the premise that document.local, document.validationErrors etc. always contain the representation of the document being edited. This would mean that we'd have to change very little in the DocumentEdit and DocumentList containers;

2. It's really easy to navigate up and down in the nesting relationship. If we want to go one level deeper, we push the current document to the stack and load the new one to the store. If we want to do the opposite, we just pop the document from the top of the stack to the store.

3. I know that we're probably not supporting multiple levels of nesting for MVP, but when/if we do, this approach doesn't need any refactoring. We can just keep pushing documents onto the stack to navigate further in the tree and popping them to get back to the surface.

If we're happy with this approach, I'm more than happy to start implementing it.

Thanks!

[mingard]

Updated spec after call:

• Store all document data in single object (as current)
• local to start as {} and only be appended when there's a change
• field onChange event to diff local and remote values. If no change, remove previously appended values from local
• Field change method will be able to detect which field based on the existence of a field param in url
• Diff to be handled in reducer. Support for all field types required
• Save method will eventually use API nested reference field save, but for now will cycle through reference fields (to one level for now) and check for a) ObjectIDs, b) Objects with ObjectIDs (requires a new POST request which can be async?) c) Object with no ObjectID (Will require a POST request to save new document, observing the response ObjectID)

@eduardoboucas have I missed anything?

[eduardoboucas]

No, I think it covers everything.

[eduardoboucas]

Do we have any designs/ideas for how a referenced field that is not an image would look like? For example, if I'm referencing a collection of users from the articles collection, what would we display on the document edit view?

Do we want to define some sort of "primary field" (e.g. user name) that would represent the document within the document edit view?

On a side note, and I know we have discussed this before and I'm happy with the way we'll reuse the document list view for selecting nested documents, but if we're thinking of a simple use case where we're selecting the author of an article, a selectize-like approach would allow me to type the name of the person and click to select the author, which would take a couple of seconds and I wouldn't need to leave the editor. With the other approach, I need to:

1. Click on "Select document" (or whatever we call it);
2. Land on the document edit view;
3. Change the sorting criteria and/or add a filter to be able to find the record I'm looking for;
4. Click a button to select and go back to the document edit view.

Couldn't we have both options available, and let engineers decide how documents for a particular collection are selected? Maybe this is post-MVP, but I think it's worth having the discussion to make sure we get this right.

[eduardoboucas]

(Pinging @abovebored as he may have some thoughts on this)

[mingard]

Post-MVP we will look at other ways of displaying referenced docs but for now just focus on the document list view approach.

I will create a separate ticket.

[eduardoboucas]

Sure. That doesn't answer my question as to how the referenced document is displayed on the document edit view, though.

[mingard]

Use the first field, as we do for list view navigation anchor.

[eduardoboucas]

Thanks.

[abovedave]

The concept of a primary field has come up a lot, right? I think it has merit because it follows the age-old database paradigm of primary & foreign keys, but are more human readable for our interface.

Is the plan for the media library referenced above still happening? The way that was envisioned is you can't edit a document, just select an existing then it would embed in the document like this.

So I imagine for a text only referenced document there would be no thumbnail (but maybe we should link the text to the original document for editing?).

Also, agree we should be thinking about how referencing content in general will evolve in general overtime. Some random examples I can think of:

• Document taxonomy
• Referencing a person inline of a content block (maybe with a thumbnail)
• Embedding a video, image or collection of images
• A venue location for an event

Which I think broadly gives us a reference where the child content is visual and one where it is text based (and a situation of both as above). Also for each we need to know - is it a field (e.g., asset field) or is it within a field (e.g., an inline image).

I can see a scenario where the selectize model is much preferred for speed (taxonomy in particular), but we should just start with one which can cover us for now, even if it's a one-size fits all solution for now.

[abovedave]

There's also this much referenced shelved bastard child of selectize and the full page route:

[mingard]

@abovebored yes the media Reference is going ahead as planned, with a few tweaks to storage.

As per Redux:

• Adding a new image is simple drag-and-drop or select to upload
• Selecting existing media takes the user to the media collection list view (as per Redux, with minor changes)

The main issue we're trying to tackle is how to create and select other Referenced documents.

For MVP we'll just replicate the media selection, taking the user to the list view for said collection. When creating a new document, the user will be taken to the document editor as if they were creating a new document directly, but on completion, will return to the parent document.

I don't believe that we're going to want to present the user with a select box + search even post MVP as using the document list view for selection has no drawbacks.

Please take this conversation to #164

[mingard]

@eduardoboucas can this be closed?

[eduardoboucas]

@mingard We don't have the create reference document bit for MVP, which is part of the ticket. But happy to close it if you want to create a separate ticket for that.

[mingard]

@eduardoboucas I'll leave it open for now