Estimated read time: 5 minutes
Writer now has a set of new automation commands and APIs that allow clients to build user interface for citation handling that's more advanced than the default in-Writer bibliography support.
This work is primarily for Collabora Online, see the CODE release notes for one possible way to use this.
Motivation¶
Users frequently using scientific citations are probably familiar with the limits of Writer's built-in bibliography support, and solutions like Zotero appeared (with a LibreOffice extension included) to improve that situation.
This means that instead of storing all your scientific notes and data locally, you can store them on a Zotero server, then work with that from anywhere, once you provide your credentials.
The trouble comes when you want to combine this with collaborative editing, which is provided by Online, but you can't use the extension made for the desktop.
The above CODE release notes explains how an end user can use this feature, this post is meant to document what new UNO commands and LOK APIs I added that serve as a backend for this. Especially the UNO commands are also useful in other contexts, like in macros or other extensions.
Results so far¶
Zotero can store citations using 3 markups in documents: fields (DOCX only), bookmarks (DOCX and ODT) and finally reference marks / sections (ODT only). The added plumbing allows several operations for all 3 cases, to work with existing documents using any of these markups.
The citation and the bibliography is handled the same way for fields (Writer's fieldmarks) and bookmarks. The last case uses reference marks for citations, but sections for the bibliography.
The following operations are supported:
-
create the citation / bibliography
-
read the object under the cursor
-
read all objects of a given type in the document
-
update the object under the cursor
-
update all objects of a given type in the document
-
delete all objects of a given type in the document
Reading is only available to LOK clients, you need to call the getCommandValues() API. The rest is normal UNO commands that you can invoke from document macros or extensions as well.
The added plumbing is the following:
| Operation | Fieldmark | Bookmark | Refmark | Section |
|---|---|---|---|---|
| Create | .uno:TextFormField | .uno:InsertBookmark | .uno:InsertField | .uno:InsertSection |
| Read | getCommandValues(".uno:TextFormField") | getCommandValues(".uno:Bookmark") | getCommandValues(".uno:Field") | None |
| Read all | getCommandValues(".uno:TextFormFields") | getCommandValues(".uno:Bookmarks") | getCommandValues(".uno:Fields") | getCommandValues(".uno:Sections") |
| Update | .uno:UpdateTextFormField | .uno:UpdateBookmark | .uno:UpdateField | None |
| Update all | .uno:TextFormFields | .uno:UpdateBookmarks | .uno:UpdateFields | .uno:UpdateSections |
| Delete all | .uno:DeleteTextFormFields | .uno:DeleteBookmarks | .uno:DeleteFields | .uno:DeleteSections |
How is this implemented?¶
If you would like to know a bit more about how this works, continue reading... :-)
As usual, the high-level problem was addressed by a series of small changes:
- sw: add new FieldType parameter for the .uno:TextFormField command
- sw: add new FieldCode parameter for the .uno:TextFormField command
- sw, .uno:TextFormField command: accept HTML in the FieldResult parameter
- sw lok, .uno:TextFormFields: expose field code of fieldmarks
- comphelper: support property values arrays in JsonToPropertyValues()
- sw: add a new .uno:TextFormFields UNO command
- sw: hide TextFormFields from the customization dialog like
- sw lok, .uno:SetDocumentProperties: expose value of custom document properties
- libreofficekit: add a way to invoke getCommandValues()
- sfx2: extend .uno:SetDocumentProperties to update custom doc props
- sw, .uno:InsertBookmark: add a new BookmarkText parameter and accept HTML there
- sw: split out some of the LOK parts of SwXTextDocument into a separate file
- sw, lok: implement a getCommandValues(Bookmarks)
- sw: add a new .uno:UpdateBookmarks UNO command
- sw, field insert: handle the Content param for refmarks and accept HTML there
- sw UI: fix crash on inserting a fieldmark inside a fieldmark
- sw, lok: implement a getCommandValues(Fields)
- sw, UpdateFields: add new TypeName, NamePrefix and Fields parameters
- sw lok: expose field type & command of fieldmark under cursor
- sw update of refmarks: fix handling of ignored refmarks
- sw: UpdateFieldContents: fix typos
- sw: add a new .uno:UpdateTextFormField UNO command
- sw lok: get all refmarks: sort the refmarks array
- sw, .uno:InsertSection: add a new Content parameter and accept HTML there
- sw: document FN_UPDATE_TEXT_FORMFIELD and FN_UPDATE_TEXT_FORMFIELDS
- sw, lok: implement a getCommandValues(Sections)
- vcl ITiledRenderable: rename supportsCommandValues() to supportsCommand()
- sw, UpdateBookmarks: support renaming bookmarks
- sw: add a new .uno:UpdateSections command
- sw: add a new .uno:DeleteTextFormFields UNO command
- sw: fix FN_UPDATE_TEXT_FORMFIELD typo
- sw lok: expose name of bookmark under cursor
- sw: add a new .uno:UpdateBookmark UNO command
- sw, UpdateSections: remove not needed StateMethod
- sw lok: expose name of refmark under cursor
- sw, FN_DELETE_TEXT_FORMFIELDS: allow deleting all fieldmarks
- sw: rename getBookmarkFor() to getInnerBookmarkFor()
- sw: add a new .uno:UpdateField UNO command
- sw: add a new .uno:DeleteBookmarks UNO command
- sw: add a new .uno:DeleteFields UNO command
- sw, UpdateBookmark: address some minor performance nits
- sw, UpdateFieldContent: address a minor performance nit
- sw: disable AutoUpdate for many new recent field/book/refmark UNO commands
- sw: .uno:TextFormField: add new Wrapper parameter
- sw: .uno:TextFormField: handle Endnote as a value for the Wrapper parameter
- sw: rename getBookmarkFor() further to getOneInnermostBookmarkFor()
- sw, .uno:InsertField: add a new Wrapper parameter
- sw, .uno:InsertField: handle Endnote as a value for the Wrapper parameter
- sw: add a new .uno:DeleteSections UNO command
Want to start using this?¶
You can get a snapshot / demo of Collabora Office 22.05 and try it out yourself right now: try the unstable snapshot. Collabora intends to continue supporting and contributing to LibreOffice, the code is merged so we expect all of this work will be available in TDF's next release too (7.6).