Documentation for support of <part>.xml file when user has parts with body content
This should be discussed in a NCBI-Coko review call before approved for development as I'm not sure if the proposals are possible - I also don't know what is the easiest technical approach for both teams. I offer a second proposal as I thought through the entire flow of the content and saw issues to think through. We will need support for this content to migrate some of our Word books. In terms of priority, I think we could delay the entire migration of these books (as we can not partially migrate them as you pointed out), but not for more than 4-6 weeks after deployment.
User Story
US25: As an Author or Editor of books with parts, I should to be able to add body content to my part so that this information can be included in the archive.
Bookshelf has actively updated Word books that have parts with body content that cannot be authored in another way given the requirements of those editorial teams for their downstream uses. To migrate these books, BCMS needs to support the ability for a system admin or editor user to add and update this content in the UI with the same book part id retained, and for it to be ingested in the PMCBook database for consistent display on the Bookshelf site via the same URL.
Scoping outcomes
Miro ref: session 5
Time estimate: 10 developer days
Agreed approach
- Allow users to add body content in the UI with existing BCMS-supported stying. Write this as xml in the element.
- Create a part.xml file and send to "chapter" conversion and loading
- Extend frontend to use the relevant tabs (Preview, Errors) and user actions from 'chapter' UI
This approach is preferable to option 2 discussed in the issue because it fits in with the current BCMS structure and allows user story in #1431 (closed).
xml file structure
<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE book-part-wrapper
PUBLIC "-//NLM//DTD BITS Book Interchange DTD v2.0 20151225//EN" "BITS-book2.dtd">
<book-part-wrapper content-type="part" id="part_a">
<book-meta>
<book-id book-id-type="pmcid">bcms10000004</book-id><book-title-group><book-title>book title</book-title></book-title-group><publisher><publisher-name>publisher</publisher-name><publisher-loc>pub place</publisher-loc></publisher></book-meta>
<book-part book-part-type="chapter"><?word-to-xml processor="extyles"?>
<book-part-meta><title-group><title>Part A</title></title-group></book-part-meta>
<body><p>This is where the content added via the UI goes.</p></body>
</book-part>
</book-part-wrapper>
Use the same <book-part-wrapper>
structure as chapter files, except content-type="part"
.
Styling (if option 1 is selected)
See #737 (closed) which applies to all stying for metadata
Issue history
Technical Proposals
(1) Coko creates a part.xml file
- parts are created in the UI (as opposed to uploading a file)
- most parts will be a title only, which gets added to the toc.xml file (already implemented)
- if a part has contributors or dates, this node should also be added to the toc.xml file (see #702 (closed))
- when the setting 'Add body content to Parts' is ON, create a part.xml file:
- lists the children nodes as related objects so they link on Bookshelf site (chapter titles only, not sections)
- Adds book part id as provided by the user (to support legacy migrated content without redirects)
- Add book metadata including (as already done for toc.xml)
- Create part.xml when
- one or more associated chapters are published
- when the part content itself is updated
- when book title and associated metadata is updated
- package and send at load to PMC step as a chapter ingest per XML integration specifications in overnight cron job (each part file should be its own package)
- error notifications / preview should be tracked and displayed in UI - how?
(2) User is able to upload and link a part.docx source file
- Coko permits upload by System Admin / Editor user of a source Word doc with a Document Type of "part" with the same integration specifications as Word conversion and chapter ingest handoffs
- Coko permits System Admin / Editor to link the Part Word doc to the Part title with a content type tag
- NCBI provides extyles2bxml support to handle Document Type "part" to minimally display the content and not linked chapters unless a user provides them as part of the authoring
- Coko provides in the UI preview, file, errors tabs and support for this processed Word document same as chapters
- Coko when building the TOC.XML links the Part title to the .xml filename with that matching title per TOC XML specifications
- A notification icon is provided by the BCMS for any "part" document that cannot be accurately placed in the TOC because it does not have a title that matches a created part unit or does not have a part content type tag