Tree

Adds metadata to the input documents that describes the position of each one in a tree structure.

By default, this module is configured to generate a tree that mimics the directory structure of each document's input path by looking at it's RelativeFilePath metadata value. Any documents with a file name of "index.*" are automatically promoted to the node that represents the parent folder level. For any folder that does not contain an "index.*" file, an empty placeholder tree node is used to represent the folder.

Note that if you clone documents from the tree, the relationships of the cloned document (parent, child, etc.) will not be updated to the new clones. In other words, your new document will still be pointing to the old versions of it's parent, children, etc. To update the tree after cloning documents you will need to recreate it by rerunning this module on all the newly created documents again.

Usage

  • Tree()

    Creates a new tree module.

Fluent Methods

Chain these methods together after the constructor to modify behavior.

  • WithMetadataNames(string parentKey = "Parent", string childrenKey = "Children", string previousSiblingKey = "PreviousSibling", string nextSiblingKey = "NextSibling", string previousKey = "Previous", string nextKey = "Next", string treePathKey = "TreePath")

    Changes the default metadata keys.

    • parentKey

      The metadata key where parent documents should be stored.

    • childrenKey

      The metadata key where child documents should be stored.

    • previousSiblingKey

      The metadata key where the previous sibling document should be stored.

    • nextSiblingKey

      The metadata key where the next sibling document should be stored.

    • previousKey

      The metadata key where the previous document should be stored.

    • nextKey

      The metadata key where the next document should be stored.

    • treePathKey

      The metadata key where the tree path should be stored.

  • WithNesting(bool nesting = true, bool collapseRoot = false)

    Indicates that the module should only output root nodes (instead of all nodes which is the default behavior).

    • nesting

      true to enable nesting and only output the root nodes.

    • collapseRoot

      Indicates that the root of the tree should be collapsed and the module should output first-level documents as if they were root documents. This setting has no effect if not nesting.

  • WithPlaceholderFactory(Func<Object[], MetadataItems, IExecutionContext, IDocument> factory)

    Allows you to specify a factory function for the creation of placeholder documents which get created to represent nodes in the tree for which there was no input document. The factory gets passed the current tree path, the set of tree metadata that should be set in the document, and the execution context which can be used to create a new document. If the factory function returns null, a new document with the tree metadata is created.

    • factory

      The factory function.

  • WithRoots(DocumentConfig isRoot)

    Specifies for each document if it is a root of a tree. This results in splitting the generated tree into multiple smaller ones, removing the root node from the set of children of it's parent and setting it's parent to null.

    • isRoot

      A predicate (must return bool) that specifies if the current document is treated as the root of a new tree.

  • WithSort(Comparison<IDocument> sort)

    This specifies how the children of a given tree node should be sorted. The default behavior is to sort based on the string value of the last component of the child node's tree path (I.e., the folder or file name). The output document for each tree node is used as the input to the sort delegate.

    • sort

      A comparison delegate.

  • WithTreePath(DocumentConfig treePath)

    Defines the structure of the tree. If the delegate returns null the document is excluded from the tree.

    • treePath

      A delegate that must return a sequence of objects.

Input Metadata

The metadata values listed below apply to individual documents and are typically set from front matter (with just the name of the key) and used as inputs to the module to control behavior.

  • Keys.RelativeFilePath: Wyam.Common.IO.FilePath

    Used to calculate the segments of the document in the tree.

Output Metadata

The metadata values listed below apply to individual documents and are created and set by the module as indicated in their descriptions.

  • Keys.Children: System.Collections.Generic.IReadOnlyCollection`1

    All the children of this node.

  • Keys.Next: Wyam.Common.Documents.IDocument

    The next node in the tree using a depth-first search or null if this was the last node.

  • Keys.NextSibling: Wyam.Common.Documents.IDocument

    The next sibling, that is the next node in the children collection of the parent or null if this is the last node in the collection or the parent is null.

  • Keys.Parent: Wyam.Common.Documents.IDocument

    The parent of this node or null if it is a root.

  • Keys.Previous: Wyam.Common.Documents.IDocument

    The previous node in the tree using a depth-first search or null if this was the first node.

  • Keys.PreviousSibling: Wyam.Common.Documents.IDocument

    The previous sibling, that is the previous node in the children collection of the parent or null if this is the first node in the collection or the parent is null.

  • Keys.TreePath: System.Array

    The path that represents this node in the tree.

GitHub