Order TOC by 'toc-order' file
Context
This proposal applies to books that have a manually ordered body section, with or without parts and must be consistent with the current implementation of automatically placing components in the correct book section (front, body, back) based on the <content-type>
in <book-part-meta>
read from the converted file.
When a user creates a manually ordered book for the first time that is large (e.g. 2000 chapters), NCBI expects that it will be a tedious task to create the order of the book. In the meeting on 11 April we discussed reading the order from a "toc-order" file. The format of this file should be decided based on the expected knowledge of the users. We discussed two options: a flat text file, and an excel file (see sample provided by NCBI attached). The excel file is preferred but its exact structure must still be agreed.
Proposal
The user flow and BCMS results:
- User selects "Upload chapters" button (this opens a page) and “select file” to add files from her computer's file system
- The files are listed in the upload page.
- The user uploads the expected
toc-order
file from her computer's file system. The BCMS checks that the file meets the minimum requirements for uploads to progress (See dealing with errors below) - The user selects "upload" and sees the status of each file change to 'uploading' then 'uploaded'. The user can wait on this page until the process is finished or navigate elsewhere in the BCMS where she will see a process indicator showing that the uploads are happening in the background.
- When finished, the files are shown in the body section according to the order provided in the
toc-order
file, including nesting, in the Status “New Upload”. - In subsequent uploads:
- If the
toc-order
file is provided, the order will be followed - If the
toc-order
file is not provided, the new files will be listed at the top of the body section, as currently implemented.
- If the
Additionally, if the toc-order
file has part components:
- With a file associated: The BCMS creates a part component from the uploaded file using the
part-id
specified in thetoc-order
file - Without a file associated: The BCMS creates a part component as a "title container" using the
part-id
specified in thetoc-order
file.
Dealing with errors:
- If the BCMS cannot read the
toc-order
file (for example the file is corrupt) then an error is shown in step 3 of the user flow and "upload" button is inactive. - If there is an error in the
toc-order
file such that the BCMS cannot cannot create a part component, then an error is shown in step 3 of the user flow and "upload" button is inactive. - If there is an error in the
toc-order
file such that the BCMS cannot read the placement of a particular chapter or sub-part component, then show this component at the top of the body or relevant part section section with the "TOC ?" icon.
Once the uploaded files have converted, the BCMS reads the <content-type>
in <book-part-meta>
. If this content type
does not match the expected placement in front/body/back sections (for example the toc-order
file communicated chapter1.docx is a chapter
but the metadata reads preface
), then the component is automatically moved to the correct section.
Design
- Change the upload modal to a page with back button to book manager page and add functionality to expect a
toc-order
file. - Edit current upload instructions to include info on using the
toc-order.xlsl
Conditional: books with manual order setting. - Edit current tooltip text for the "TOC ?" icon to suit all cases.
Implementation (if applicable)
Alternative approaches (if applicable)
Scheduling
Dev estimate:
- parse the toc-order file: 5 days
- deal with errors: 3 days
- frontend changes to upload flow, (excluding changing the modal to a page and out of scope below : 3.5 days)
Out of scope
This behaviour is estimated separately in #1497
The user can wait on this page until the process is finished or navigate elsewhere in the BCMS where she will see a process indicator showing that the uploads are happening in the background.