Separate the front/body/back divisions into three tabs
Context / User Story
Table of Contents Building Story: Because of an improvement made to the BCMS data model from the existing Silverlight CMS to support editorial teams to manage their book part contents at the same time themselves, Bookshelf requires the BCMS to have functionality in the UI for users to build their TOC by communicating, through automated settings and/or manual placement, its structural place in the book (front, body, back), what part in the body it belongs if there are parts, and where in the order of contents a book part of any structural attribute falls; the BCMS must then read this communicated information and write valid book Table of Contents (TOC) XML files (see TOC.xml user story). Original acceptance criteria are here: &2
TOC Building issue that needs to be solved for the MVP: Currently, BCMS users cannot manually drag and drop their book parts on the existing chapter-processed Book Manager pages to order their front matter, body contents, part contents, or back matter. This is because lately introduced lazy load scroll bars interfere with the user also being able to see all their contents to be ordered in context of an entire structural unit, and then to drag and drop them where they belong in the context of that entire structural unit. Also, the performance of the page is slow and the drag and drop functionality is not responsive to users’ attempts to move their contents to the right structural place and for those place parts to "stick" in place; that is even after NCBI has removed lazy load to see all parts to validate assumptions.
Impact if this TOC Building issue is not solved: Based on a Bookshelf analysis of all its chapter processed TOCs and discussion with some participants, the results of which were shared with Coko, nearly all these TOCs have some level of required manual curation, according to the participants’ editorial policies that Bookshelf does not have the power to change. These are either the manual ordering of front matter, back matter, or of the placement of content within a part title, and to order those part titles by the historical and professional understanding of those editorial teams. Unless these teams can manage their TOCs in this way, Bookshelf will not be able to display TOC landing pages on its Bookshelf websites per terms of its current participant agreements.
This issue also relates to the proposal Design options for resolving chapter-processed book manager performance issues (#1480 (closed)) and supporting parts with Body content in #1455.
Proposal
NCBI has chosen the table of content building improvements below, along with Design option 1.
The combination of very long lists and managing the books divisions (front/body/back) with multi-nested structures makes it difficult for users of these kinds of books to curate their TOCs because the space to do this work on the page is limited.
Design
Current UI
This is the current UI, an example from this book
Design option 1 (chosen)
- Provide more space for TOC curation by separating the front/body/back divisions into three tabs.
- Tabs are positioned below the 'Upload Chapters' button (left of page) and Search input area and buttons (right of page) because the Tabs UI will be replaced with the search results UI (#1467 (closed)) when users search.
- 'Body' is the default tab when user arrives at the Book manager
Acceptance criteria
-
All chapter-processed book contents on the Book Manager page is split across three divisions: Front, Body, and Back. These three division can be accesses via tabs at the top left of the page. -
The Front|Body|Back pages will load within 20 sec (the Silverlight CMS current baseline) in their native environments (within institutional networks or home systems; benchmark is Bookshelf staff and GeneReviews, LiverTox, LactMed editorial team's environments in which they manage their contents) -
When a supported user navigates to the Book manager page from any other page in the BCMS, the Book Manager page will open with the "Body" tab and its page(s) contents in view. -
If a user changes a Body view to a Front or Back view using the Front or Back tab, the Front or Back view will remain in view until the user navigates away from their current Book Manager page or changes from a Front view to a Body or Back view or from a Back view to a Body or Front view. -
If a user changes a Front view to a Body or Back view using the Front or Back tab, the Body or Back view will remain in view until the user navigates away from their current Book Manager page or changes from a Body view to a Front or Back view or from a Back view to a Front or Body view. -
If a user changes a Back view to a Body or Front view using the Body or Front tab, the Body or Front view will remain in view until the user navigates away from their current Book Manager page or changes from a Body view to a Front or Back view or from a Front view to a Body or Back view. -
A user will see the paginated design in #1480 (closed) when implemented on all Front|Body|Back pages. -
Users will not see a Repeat button on Front|Back pages as this function is not possible in those divisions (Pending in task #1544 (closed)) -
The design will not change the current rules for how the BCMS automatically moves components to the correct book division after conversion. The current functionality remains: Components are placed in 'body' when uploaded, and move to the the corrected division after conversion:
Type of Document You Wish to Create | Value in Word template | Tagging from conversion | Section placement |
---|---|---|---|
appendix | appendix |
<book-part-wrapper content-type="appendix" id=""> ; <book-app book-part-type="appendix"> or <book-part book-part-type="appendix">
|
back |
chapter | chapter |
<book-part-wrapper content-type="chapter" id=""> ; <book-part book-part-type="chapter">
|
body |
dedication page | dedication |
<book-part-wrapper content-type="dedication" id=""> ; <dedication>
|
front |
foreword | foreword |
<book-part-wrapper content-type="foreword" id=""> ; <foreword>
|
front |
frontmatter part | front-matter-part |
<book-part-wrapper content-type="front-matter-part" id=""> ; <front-matter-part>
|
front |
glossary | glossary |
<book-part-wrapper content-type="glossary" id=""> ; <book-part book-part-type="glossary">
|
back |
preface | preface |
<book-part-wrapper content-type="preface" id=""> ; <preface>
|
front |
reference list | ref-list |
<book-part-wrapper content-type="ref-list" id=""> ; <book-part book-part-type="ref-list">
|
back |
section | section |
<book-part-wrapper content-type="section" id=""> ; <book-part book-part-type="section">
|
body |
Definition of ready
-
BCMS User Story / Context has been well defined -
The priority of the user story is specified and agreed -
Digital assets added (design, database scheme, mockups etc if relevant) -
Coko Technical Proposal approved by NCBI -
Testable Acceptance Criteria approved by NCBI -
Estimate of effort to complete (time or points) -
The issue has been broken down into development tasks (if necessary) -
Requirements Clarified -
The product owner and development team agree that the user story is ready for development -
NCBI adds “Dev_Ready”
Definition of done
-
All coding tasks are finished and implemented by Coko -
All end to end tests are finished and implemented by Coko: the tests will make sure the design is implemented correctly by checking the tabs as well the test will check that the components are positioned in the right division, by uploading the converted files to them (so we don't wait for conversion in pipeline). -
QA approved by Coko -
Deployed and tested on “ncbidev” of cloud68 hosted site, by Coko -
Deployed and tested on “ncbi” of cloud68 hosted site, by NCBI team -
Deployed and tested in NCBI-hosted environment by NCBI team and any necessary external editorial teams -
NCBI approves that all Acceptance Criteria have been Met
Implementation
Development broken down in tasks below: #1514 (closed)
Alternative approaches (if applicable)
Alternative approaches (not chosen)
Alternative approaches (not chosen)
NCBI and Coko will agree on one clear development path of least effort to minimally address this issue for MVP that will still meet user stories for a stable data model, performance of the application, and file management, as well as other user stories such as metadata, parts, and complete documents. Possible technical solutions to evaluate least effort for a stable MVP solution include:
Design option 2
- Maintain full TOC divisions in one page in a separate view for TOC building actions only. -- Development estimate 3 days
- This design is compatible with Design option 3 proposed in the Design options for resolving chapter-processed book manager performance issues (#1480 (closed))
- The Order UI is only necessary when manual ordering is required
- The Order UI is placed with exiting TOC Live view and Errors reporting
Approach A
- BCMS displays position number of book part in UI relative to structural division (front | body | back) and any parts, and permits a right click of that book part to provide a reposition modal for the user to reposition that book part. The modal would be pre-filled by the UI with the current position. Note, there is no restriction on how many parts a user can create. Parts (and how many levels of Parts) dropdown would only appear if those Parts already exist. See proposed mockup from @deniskar: BCMS will not permit loading of TOC if any published book part does not have a position or has a duplicate position. This would be in addition to automated ordering, including all labels, and all publication and publication history dates. NCBI and Coko will provide a clear technical proposal for the estimates of this work to successfully meet these user stories and issues before a full development agreement can commence, so its deliverables are understood by all parties , OR
Development estimate 5 days
Note: this approach does not account for moving items in bulk.
Approach B
- Bookshelf and PMC developers support the provision by a submitter in source files, sorting information within front matter, book body, a book part, or back matter that is passed in a consistent BITS element and attribute to the converted BITS XML stored in the BCMS, and which the BCMS can read to build a TOC or communicate submitter errors to fix if this needed information is missing or problematic. These errors will block publication of a TOC. Coko will read ALL supported BITS elements, not only explicit ordering information, but also other metadata for automated ordering, including all labels, and all publication and publication history dates. NCBI and Coko will provide a clear technical proposal for the estimates of this work to successfully meet these user stories and issues before a full development agreement can commence, so its deliverables are understood by all parties , OR
Development estimate 3 days
Note: Coko does not recommend this approach because it will place a lot of burden on users.
Approach C (This is estimated in Design Option 2 above)
- Separate out ALL or PARTS of the TOC Building from the chapter-processed Book Dashboard for Files Management and Processing Integration. Possible design:
OR
Approach D
- Coko will add functionality for Bookshelf staff to download from the BCMS TOC.XML to adjust the order of contents in the XML and upload the file and reload it to PMC Books successfully. Note, it would be important for user to have BCMS create a TOC, download it, and just update it and reupload it with some modifications if too difficult using UI. User story will not support all users supplying a TOC from scratch. Possible design:
If this last option is chosen and this could be extended with least effort to resolve TOC.xml issues, THEN add functionality for Bookshelf staff to download from the BCMS TOC.XML written by BCMS with loading errors to fix those errors in the XML and upload the file and reload it to PMC Books successfully
Development estimate 7 days
Note:
- This design is compatible with Design option 3 proposed in the Design options for resolving chapter-processed book manager performance issues (#1480 (closed))
- if this approach is taken our assumption is that uploading a TOC replaces the need for any manual ordering, but we continue to support automatic ordering and building TOC.xml for the auto-ordered cases. Therefore all toc.xml writing issues must be addressed.
Scheduling
- Milestone: linked
- Iteration: linked
- Dependencies: no
- Development estimate (hours): added to time tracking