Part components for books published as the component level
Hi @lathrops1
A part component, in terms of a book's structure, sits one level above chapters, for example:
Body content
- Part A
- Chapter 1
- Chapter 2
- Chapter 3
- Part B
- Chapter 4
- Chapter 5
- Chapter 6
etc.
In the Word workflow currently, users don't upload a Word file for a part; instead the NCBI team creates a part.xml file which gets published as its own page on Bookshelf. This part.xml file includes links to the chapter pages on Bookshelf -- in most cases these links are the only content on the part page. You explained that it would be difficult for Word users to create these links in a Word file, and I agree uploading individual files for parts isn't the best approach.
So we discussed two kinds of parts:
- parts that are like a container (only a title)
- parts that are book components (they have metadata and/or body content).
Container-like parts wouldn't need to be versioned and they would not have their own page on Bookshelf (as they currently do, in this example).
Parts that are book components would need to be versioned, as we have currently developed. This allows users to maintain a record of the changes in metadata and content for each published version. In this use case, our system would create a part.xml file, send it to NCBI for load to PMC, errors and/or a preview would be generated, and the file would get published. If it's not necessary to version the metadata of a part, then our system could only create the part file when there is body content, and include the metadata on the toc.xml file.
For this approach to work, both kinds of parts would need to be distinct -- in both the data model and the UI. The user would need to choose between creating a:
- part title
- part with content.
(or some other appropriate wording)
I'm not sure if this distinction will be meaningful to your users. Additionally, if it's possible for one book to have both kinds of parts, I think this would be confusing to users as they would need to publish some parts, but not others; some parts would have version numbers and statuses, while others wouldn't.
Blocking users from creating parts of both kinds in the same book, with a book setting such as 'allow parts with content YES/NO', sounds to me like a decision that only an NCBI system admin would be able to make, but perhaps this could be made clear with explainer text.
The alternative is to treat all parts as book components. I've described this scenario below. @John.kopanas and @yannis please sense check this.
The user can create the part in the UI, by doing something like this:
Select 'Add part' button --> insert title --> 'add' chapters to it --> add metadata (optional) --> add body text (optional) --> select 'Create part' button.
In this scenario, all parts or versionable are publishable like the rest of the book components. There are some decisions to make around previewing.
When a user creates a part, or updates an existing part, there are two development options to choose from:
Either
- Get the latest version of all the part's chapters and use that (and the part's own content) to generate a part.xml file (this handles the scenario when a title changes in a chapter). Send the part.xml file to NCBI so a preview link can be generated and returned.
Or
- Don't send the part.xml file to NCBI or provide a preview link. Users would see the part title and metadata on the TOC preview anyway. However they would not have a way to approve a generated part page with body content in this scenario, if approving the text they added in the UI is sufficient then this isn't a problem.
Status changes of a part for this option would be something like:
- New
- Ready to publish
- Published
For publishing, a part.xml file would need to be send to NCBI in these scenarios: e.g.
- every time one or more chapters within the part is published (the user wouldn't have to explicitly publish the part)
- If the user wants to change the part's content in some way, he would need to create a new version of it first (as already implemented for individual book components), update it, then publish the new version.
There may be other integration that I'm not aware of.
Please also clarify what the use cases are for books published as the component level in the PDF and XML workflows:
- Do these books have parts with metadata and content?
- If so, are the part files separate from the chapter files?