Table of Contents
Introduction#
In KnowWE the content of an article is managed as a hierarchical structure of the content elements. Every node of that tree contains a particular fragment of the source text of the page. We call such a node a Section. No matter what kind of extension for KnowWE should be implemented, sections will play a fundamental role in any case. Therefore handling, searching, navigation, and modification of sections are hot topics in KnowWE programming.
Finding other sections from a given section#
The class Sections provides numerous static utility methods for working with sections. Often it is necessary to find a section of a particular type, which is an ancestor or successor of a given section. For this purpose, multiple methods in the class Sections are provided starting with findAncestor or findSuccessor respectively. If a single section object is returned, it is the first matching section found. If multiple sections are returned, they are ordered as detected by the traversing algorithm. The search for ancestors ascends straight from the given section towards the root section. The search for successors runs in depth first search manner starting at the given section. If only a search for direct successors is desired, methods starting with findChild are provided.Editing page contents#
Often it is required to modify the source content of a page, in particular if an editor component is implemented. The section model of the article provides a convenient way to replace parts with new contents. However, to keep the KnowWE data-structure and the interaction of all plugins in an consistent state, it is important to do this the right way.Please regard the following notes:
- Never create new section objects directly
- Never modify section objects directly
- Never change the interlinking (parent-child-relations) of section objects directly
Instead do: Use the methods replaceSections provides by the Sections class.
public static Map<String, String> replaceSections(UserActionContext context, Map<String, String> sectionsMap) throws IOException {
%
Beside the context of the user, that is responsible for triggering these changes, a map is passed. This map contains all the change operations that are supposed to be applied on the wiki pages source(s). The keys of this map are section ids of existing sections.
The value for each id is the new content string, the old section should be replaced with. After modifying the content as specified by this map of replacements, this method will take care of all additional organizational issues (e.g., persistence, parsing, compilation, message handling, event handling).
The method return a map containing a mapping from the old section ids to the corresponding new sections id, if structural equivalence is given. Not in every case this information is required by the caller.
