@itwin/presentation-common/lib/esm/presentation-common/content/ContentTraverser.d.ts

Common pieces for iModel.js presentation packages

/** @packageDocumentation
 * @module Content
 */
import { LabelDefinition } from "../LabelDefinition.js";
import { CategoryDescription } from "./Category.js";
import { Content } from "./Content.js";
import { Descriptor } from "./Descriptor.js";
import { Field } from "./Fields.js";
import { Item } from "./Item.js";
import { TypeDescription } from "./TypeDescription.js";
import { DisplayValue, DisplayValuesArray, DisplayValuesMap, Value as PresentationValue, ValuesArray as PresentationValuesArray, ValuesMap as PresentationValuesMap } from "./Value.js";
/**
 * A data structure to define a hierarchy of [[Field]] objects.
 * @public
 */
export interface FieldHierarchy {
    /** Parent field. */
    field: Field;
    /** Nested fields. */
    childFields: FieldHierarchy[];
}
/**
 * Props for the [[IContentVisitor.startContent]] call.
 * @public
 */
export interface StartContentProps {
    /** Descriptor of the visited content. */
    descriptor: Descriptor;
}
/**
 * Props for the [[IContentVisitor.processFieldHierarchies]] call.
 * @public
 */
export interface ProcessFieldHierarchiesProps {
    /**
     * The root list of fields, which may be mutated by the visitor to change order or the fields,
     * add new fields, etc.
     */
    hierarchies: FieldHierarchy[];
}
/**
 * Props for the [[IContentVisitor.startItem]] call.
 * @public
 */
export interface StartItemProps {
    /** The content item that's about to be visited. */
    item: Item;
}
/**
 * Props for the [[IContentVisitor.startCategory]] call.
 * @public
 */
export interface StartCategoryProps {
    /** The content category that's about to be visited. */
    category: CategoryDescription;
}
/**
 * Props for the [[IContentVisitor.startField]] call.
 * @public
 */
export interface StartFieldProps {
    /** The field that's about to be visited. */
    hierarchy: FieldHierarchy;
}
/**
 * Props for the [[IContentVisitor.startStruct]] call.
 * @public
 */
export interface StartStructProps {
    /** Field that describes the struct. */
    hierarchy: FieldHierarchy;
    /** Type of the struct. */
    valueType: TypeDescription;
    /** Name of the parent field (if there is one). */
    parentFieldName?: string;
    /** Member raw values. */
    rawValues: PresentationValuesMap;
    /** Member display values. */
    displayValues: DisplayValuesMap;
    /** Label definition of the ECInstance that the struct represents. */
    label?: LabelDefinition;
}
/**
 * Props for the [[IContentVisitor.startArray]] call.
 * @public
 */
export interface StartArrayProps {
    /** Field that describes the array. */
    hierarchy: FieldHierarchy;
    /** Type of the array. */
    valueType: TypeDescription;
    /** Name of the parent field (if there is one). */
    parentFieldName?: string;
    /** Item raw values. */
    rawValues: PresentationValuesArray;
    /** Item display values. */
    displayValues: DisplayValuesArray;
}
/**
 * Props for the [[IContentVisitor.processMergedValue]] call.
 * @public
 */
export interface ProcessMergedValueProps {
    /** The field whose values are merged. */
    mergedField: Field;
    /**
     * Generally this matches the [[mergedField]], but there are situations when a nested field is propagated
     * up to display it as if it wasn't nested its parent fields. In those cases, if one of the parent fields
     * is merged, the merged parent is going to be represented by [[mergedField]] and the field we wanted to
     * process is going to be represented by [[requestedField]].
     */
    requestedField: Field;
    /** Name of the parent field (if there is one). */
    parentFieldName?: string;
}
/**
 * Props for the [[IContentVisitor.processPrimitiveValue]] call.
 * @public
 */
export interface ProcessPrimitiveValueProps {
    /** Field whose value is being processed. */
    field: Field;
    /** Type of the value. */
    valueType: TypeDescription;
    /** Name of the parent field (if there is one). */
    parentFieldName?: string;
    /** Raw value. */
    rawValue: PresentationValue;
    /** Display value. */
    displayValue: DisplayValue;
}
/**
 * An interface for a visitor that can be passed to the [[traverseContent]] function
 * to be called on each piece of content.
 *
 * The order of calls when using the visitor with [[traverseContent]] or [[traverseContentItem]]:
 *
 * ```
 * startContent
 *   processFieldHierarchies
 *   for each content item:
 *     startItem
 *     for each field in root level:
 *       for each category in field's category stack from root to field's category:
 *         startCategory
 *       startField
 *         valueProcessing:
 *           if item's value for this field is merged:
 *             processMergedValue
 *           else if the field is struct:
 *             startStruct
 *             for each struct member:
 *               recurse into the valueProcessing step
 *             finishStruct
 *           else if the field is array:
 *             startArray
 *             for each array item:
 *               recurse into the valueProcessing step
 *             finishArray
 *           else if the field is primitive:
 *             processPrimitiveValue
 *       finishField
 *     finishItem
 * finishContent
 * ```
 * @public
 */
export interface IContentVisitor {
    /**
     * Called before starting [[Content]] processing. This is a good place to initialize various caches and prepare
     * for parsing content.
     *
     * Processing is skipped if the function returns `false` and [[finishContent]] is not called in that case.
     */
    startContent(props: StartContentProps): boolean;
    /** Called after processing of [[Content]] is complete. */
    finishContent(): void;
    /** Called to post-process field hierarchies after they're extracted from [[Descriptor]] in processed [[Content]]. */
    processFieldHierarchies(props: ProcessFieldHierarchiesProps): void;
    /**
     * Called before starting each [[Item]] processing. This is a good place to initialize for a new content item, e.g.
     * set up a new row in table.
     *
     * Processing is skipped if the function returns `false` and [[finishItem]] is not called in that case.
     */
    startItem(props: StartItemProps): boolean;
    /**
     * Called after processing of [[Item]] is complete. May be used to do any kind of post-processing after all
     * values for one content item have been processed.
     */
    finishItem(): void;
    /**
     * Called before processing a content item field ([[startField]] call) for each category in the field's
     * category stack, starting from the root and finishing with the field's category.
     *
     * Processing is skipped if the function returns `false` and [[finishCategory]] is not called in that case.
     */
    startCategory(props: StartCategoryProps): boolean;
    /** Called after processing of field is complete for every category in the field's category stack. */
    finishCategory(): void;
    /**
     * Called before starting [[Field]] processing for each individual [[Item]]. This is a good callback
     * to skip a field if it doesn't need to be handled.
     *
     * Processing is skipped if the function returns `false` and [[finishField]] is not called in that case.
     */
    startField(props: StartFieldProps): boolean;
    /** Called after processing of [[Field]] for individual [[Item]] is complete. */
    finishField(): void;
    /**
     * Called before processing a struct value. This is a good callback to skip handling the value or set up
     * for struct member values handling.
     *
     * Processing is skipped if the function returns `false` and [[finishStruct]] is not called in that case.
     */
    startStruct(props: StartStructProps): boolean;
    /** Called after processing of struct value is complete. */
    finishStruct(): void;
    /**
     * Called before processing an array value. This is a good callback to skip handling the value or set up
     * for array items handling.
     *
     * Processing is skipped if the function returns `false` and [[finishArray]] is not called in that case.
     */
    startArray(props: StartArrayProps): boolean;
    /** Called after processing of array value is complete. */
    finishArray(): void;
    /** Called to process a [merged value]($docs/presentation/content/Terminology.md#value-merging). */
    processMergedValue(props: ProcessMergedValueProps): void;
    /** Called to process a primitive value. */
    processPrimitiveValue(props: ProcessPrimitiveValueProps): void;
}
/**
 * An utility for traversing field hierarchy. Stops traversal as soon as `cb` returns `false`.
 * @public
 */
export declare function traverseFieldHierarchy(hierarchy: FieldHierarchy, cb: (h: FieldHierarchy) => boolean): void;
/**
 * An utility to traverse content using provided visitor. Provides means to parse content into different formats,
 * for different components.
 * @public
 */
export declare function traverseContent(visitor: IContentVisitor, content: Content): void;
/**
 * An utility for calling [[traverseContent]] when there's only one content item.
 * @public
 */
export declare function traverseContentItem(visitor: IContentVisitor, descriptor: Descriptor, item: Item): void;
/**
 * Parses a list of [[Field]] objects into a list of [[FieldHierarchy]].
 *
 * @param ignoreCategories Enables adding all of the `nestedFields` to parent field's `childFields`
 * without considering categories.
 *
 * @public
 */
export declare function createFieldHierarchies(fields: Field[], ignoreCategories?: boolean): FieldHierarchy[];
/**
 * Adds a field hierarchy into root field hierarchies list.
 * @public
 */
export declare function addFieldHierarchy(rootHierarchies: FieldHierarchy[], hierarchy: FieldHierarchy): void;
/** @internal */
export declare const FIELD_NAMES_SEPARATOR = "$";
/**
 * Combines given field names in a way that allows them to be parsed back into a list of individual names using the [[parseCombinedFieldNames]] function.
 * @public
 */
export declare function combineFieldNames(fieldName: string, parentFieldName?: string): string;
/**
 * Parses given combined field names string, constructed using [[combineFieldNames]], into a list of individual field names.
 * @public
 */
export declare function parseCombinedFieldNames(combinedName: string): string[];
//# sourceMappingURL=ContentTraverser.d.ts.map