Change Details

The current DOM representation of citations is fairly complex for clients to handle, and makes it difficult to efficiently retrieve all metadata (`data-mw`) needed to edit a specific section of a page. One of the biggest issues is the handling of named citations. The metadata is associated with the rendering of the citation (typically in the references list), and is not directly available within the metadata for a specific section. When using inline data-mw, this had the advantage of avoiding duplication of citation data. However, it also places the full burden of handling citation groups on the client. ## Possible simplification: Provide full citation metadata for each citation, at point of definition - Provide full data-mw for each citation, at the point where the citation is defined. If the reference is to a citation group, still provide full metadata, plus an attribute indicating the group name. - Editing: - For plain citations (not grouped), the inline data-mw is updated. - For grouped citations, the editor can ask the user whether the citation should be disassociated from the group, or whether the group should be updated. - Disassociation: Remove group name reference from data-mw. - Update group: Keep the group reference. The other references to the same group are updated server-side. - Citation removal: Parsoid will handle the re-assignment of primary group definitions in case the primary definition was removed in HTML. ### Pros - Supports efficient section retrieval / editing. - Moves some complex update logic to Parsoid, simplifies clients. ### Cons - Accurate rerendering of the full references list still requires data-mw for full page.

Citations depend on global page state (specifically the <references /> tag and named citations). This interferes with visual editing of individual sections that don't have the global state for the entire page. Specifically: * a named citation in one section might refer to a citation defined elsewhere on the page. * if a section being edited has the <references /> tag and the group attribute is edited on the tag, the visual rendering of the page cannot be updated without having access to the references information on the page (editing from no-group => group is feasible by inspecting the DOM, but going from group => no-group still requires page-global state). * Parsoid's DOM representation for <ref>s have cross-references to the section containing <references /> tags since the data-mw attribute for a <ref> points to the DOM tree id of the ref-body in the rendering of the references section. While this was done to reduce the size of the DOM that VE has to fetch, this also is a barrier for section editing. ## Possible simplification: Provide full citation metadata for each citation, at point of definition - Provide full data-mw for each citation, at the point where the citation is defined. If the reference is to a citation group, still provide full metadata, plus an attribute indicating the group name. - Editing: - For plain citations (not grouped), the inline data-mw is updated. - For grouped citations, the editor can ask the user whether the citation should be disassociated from the group, or whether the group should be updated. - Disassociation: Remove group name reference from data-mw. - Update group: Keep the group reference. The other references to the same group are updated server-side. - Citation removal: Parsoid will handle the re-assignment of primary group definitions in case the primary definition was removed in HTML. ### Pros - Supports efficient section retrieval / editing. - Moves some complex update logic to Parsoid, simplifies clients. ### Cons - Accurate rerendering of the full references list still requires data-mw for full page.

The current DOM representation of citations is fairly complex for clients to handle,Citations depend on global page state (specifically the <references /> tag and named citations). and makes it difficult to efficiently retrieve all metadata (`data-mw`) needed to edit a specific section of aThis interferes with visual editing of individual sections that don't have the global state for the entire page. One of the biggest issues is the handling of named citations. The metadata is associated with the rendering of the citation (typically in the references list)Specifically: * a named citation in one section might refer to a citation defined elsewhere on the page. * if a section being edited has the <references /> tag and the group attribute is edited on the tag, and is not directly available within the metadata for a specific section. When using inline data-mw, this had the advantage of avoiding duplication of citation datathe visual rendering of the page cannot be updated without having access to the references information on the page (editing from no-group => group is feasible by inspecting the DOM, but going from group => no-group still requires page-global state). * Parsoid's DOM representation for <ref>s have cross-references to the section containing <references /> tags since the data-mw attribute for a <ref> points to the DOM tree id of the ref-body in the rendering of the references section. HoweverWhile this was done to reduce the size of the DOM that VE has to fetch, itthis also places the full burden of handling citation groups on the clientis a barrier for section editing. ## Possible simplification: Provide full citation metadata for each citation, at point of definition - Provide full data-mw for each citation, at the point where the citation is defined. If the reference is to a citation group, still provide full metadata, plus an attribute indicating the group name. - Editing: - For plain citations (not grouped), the inline data-mw is updated. - For grouped citations, the editor can ask the user whether the citation should be disassociated from the group, or whether the group should be updated. - Disassociation: Remove group name reference from data-mw. - Update group: Keep the group reference. The other references to the same group are updated server-side. - Citation removal: Parsoid will handle the re-assignment of primary group definitions in case the primary definition was removed in HTML. ### Pros - Supports efficient section retrieval / editing. - Moves some complex update logic to Parsoid, simplifies clients. ### Cons - Accurate rerendering of the full references list still requires data-mw for full page.