Reference

Parser

ModelReferenceParser

/**
 * @since 18.0.0RC1
 */
interface ModelReferenceParser {
  /**
   * @param reference - an entity reference
   * @param options - (since 0.22) an optional configuration object
   */
  parse(
    reference: string,
    options?: ModelReferenceParserOptions,
  ): EntityReference;

  /**
   * Parse a reference with additional analysis that can only be performed asynchronously
   * @param reference - an entity reference
   * @param options - an optional configuration object
   * @since 18.0.0RC1
   */
  parseAsync(
    reference: string,
    options?: ModelReferenceParserOptions,
  ): Promise<EntityReference>;
}

ModelReferenceParserOptions

/**
 * @since 18.0.0RC1
 */
type ModelReferenceParserOptions = {
  /**
   * an optional type, helping to remove ambiguity when parsing the reference
   */
  type?: EntityType;
  /**
   * When false, the model reference is parsed as an absolute reference.
   * When true, the model reference is parsed relatively to the current document.
   * The default value is true.
   */
  relative?: boolean;
};

ModelReferenceParserProvider

/**
 * @since 18.0.0RC1
 */
interface ModelReferenceParserProvider {
  get(type?: string): ModelReferenceParser | undefined;
}

Serializer

ModelReferenceSerializer

/**
 * @since 18.0.0RC1
 */
interface ModelReferenceSerializer {
  serialize(reference?: EntityReference): string | undefined;
}

ModelReferenceSerializerProvider

/**
 * @since 18.0.0RC1
 */
interface ModelReferenceSerializerProvider {
  get(type?: string): ModelReferenceSerializer | undefined;
}

Handler

ModelReferenceHandler

/**
 * A ModelReferenceHandler can do backend-specific operations involving
 * {@link @xwiki/platform-model-api#EntityReference | EntityReferences}.
 *
 * @since 18.0.0RC1
 */
interface ModelReferenceHandler {
  /**
   * Returns a {@link DocumentReference} with a specific name and a parent
   * {@link SpaceReference}.
   *
   * @param name - the name of the document reference
   * @param space - the parent space of the document reference
   * @returns the document reference
   */
  createDocumentReference(
    name: string,
    space: SpaceReference,
  ): DocumentReference;

  /**
   * Return the title of a reference
   */
  getTitle(reference: EntityReference): string;

  /**
   * Returns the {@link DocumentReference} considered as the direct parent of
   * the given document reference.
   * @param reference - the reference for which we want the parent
   * @returns the parent for the given reference, undefined if there is none
   *
   * @since 18.4.0RC1
   */
  getParentDocumentReference(
    reference: DocumentReference,
  ): DocumentReference | undefined;

  /**
   * Returns the {@link SpaceReference} considered as the direct parent of
   * the given space reference.
   * @param reference - the reference for which we want the parent
   * @returns the parent for the given reference, undefined if there is none
   *
   * @since 18.4.0RC1
   */
  getParentSpaceReference(
    reference: SpaceReference,
  ): SpaceReference | undefined;
}

ModelReferenceHandlerProvider

/**
 * A ModelReferenceHandlerProvider returns the expected instance of
 * {@link ModelReferenceHandler}.
 *
 * @since 18.0.0RC1
 */
interface ModelReferenceHandlerProvider {
  /**
   * Returns the instance of {@link ModelReferenceHandler} matching the
   * requested wiki configuration type, or the current one if empty.
   *
   * @param type - the wiki configuration type
   * @returns the instance of model reference handler
   */
  get(type?: string): ModelReferenceHandler | undefined;
}