@enonic-types/lib-content/content.d.ts

Type definitions for lib-content.

/**
 * Functions and constants to find and manipulate content.
 *
 * @example
 * var contentLib = require('/lib/xp/content');
 *
 * @module content
 */
declare global {
    interface XpLibraries {
        '/lib/xp/content': typeof import('./content');
    }
    interface XpXData {
    }
}
import type { Aggregations, AggregationsResult, AggregationsToAggregationResults, ByteSource, Content, ContentInheritValue, Filter, FormItem, Highlight, HighlightResult, PublishInfo, QueryDsl, SortDsl, Workflow } from '@enonic-types/core';
export type { Aggregation, Aggregations, AggregationsResult, Attachment, BooleanDslExpression, BooleanFilter, Bucket, BucketsAggregationResult, BucketsAggregationsUnion, ByteSource, Component, Content, DateBucket, DateHistogramAggregation, DateRange, DateRangeAggregation, DistanceUnit, DslOperator, DslQueryType, ExistsDslExpression, ExistsFilter, FieldSortDsl, Filter, FormItem, FormItemInlineMixin, FormItemInput, FormItemLayout, FormItemOptionSet, FormItemSet, FulltextDslExpression, GeoDistanceAggregation, GeoDistanceSortDsl, GroupKey, HasValueFilter, Highlight, HighlightResult, HistogramAggregation, IdsFilter, InDslExpression, InputType, LikeDslExpression, MatchAllDslExpression, MaxAggregation, MinAggregation, NgramDslExpression, NotExistsFilter, NumericBucket, NumericRange, NumericRangeAggregation, PathMatchDslExpression, PublishInfo, QueryDsl, RangeDslExpression, Region, RoleKey, ScriptValue, SingleValueMetricAggregationResult, SingleValueMetricAggregationsUnion, SortDirection, SortDsl, StatsAggregation, StatsAggregationResult, StemmedDslExpression, TermDslExpression, TermsAggregation, UserKey, ValueCountAggregation, ValueType, } from '@enonic-types/core';
declare type Attachments = Content['attachments'];
export declare type PageComponentWhenAutomaticTemplate = Record<string, never>;
export interface PageComponentWhenSpecificTemplate {
    path: '/';
    template: string;
    type: 'page';
}
export declare type Schedule = Omit<PublishInfo, 'first'>;
export declare const ARCHIVE_ROOT_PATH: string;
export declare const CONTENT_ROOT_PATH: string;
export interface GetContentParams {
    key: string;
    versionId?: string | null;
}
/**
 * This function fetches a content.
 *
 * @example-ref examples/content/get.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the content.
 * @param {string} [params.versionId] Version Id of the content.
 *
 * @returns {object} The content (as JSON) fetched from the repository.
 */
export declare function get<Hit extends Content<unknown> = Content>(params: GetContentParams): Hit | null;
/**
 * This function returns a content attachments.
 *
 * @example-ref examples/content/getAttachments.js
 *
 * @param {string} key Path or id to the content.
 *
 * @returns {object} An object with all the attachments that belong to the content, where the key is the attachment name. Or null if the content cannot be found.
 */
export declare function getAttachments(key: string): Attachments | null;
export interface GetAttachmentStreamParams {
    key: string;
    name: string;
}
/**
 * This function returns a data-stream for the specified content attachment.
 *
 * @example-ref examples/content/getAttachmentStream.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the content.
 * @param {string} params.name Attachment name.
 *
 * @returns {*} Stream of the attachment data.
 */
export declare function getAttachmentStream(params: GetAttachmentStreamParams): ByteSource | null;
export interface AddAttachmentParam {
    key: string;
    name: string;
    mimeType: string;
    data: ByteSource;
    label?: string;
}
/**
 * Adds an attachment to an existing content.
 *
 * @example-ref examples/content/addAttachment.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the content.
 * @param {string} params.name Attachment name.
 * @param {string} params.mimeType Attachment content type.
 * @param {string} [params.label] Attachment label.
 * @param {object} params.data Stream with the binary data for the attachment.
 */
export declare function addAttachment(params: AddAttachmentParam): void;
export interface RemoveAttachmentParams {
    key: string;
    name: string | string[];
}
/**
 * Removes an attachment from an existing content.
 *
 * @example-ref examples/content/removeAttachment.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the content.
 * @param {string|string[]} params.name Attachment name, or array of names.
 */
export declare function removeAttachment(params: RemoveAttachmentParams): void;
export interface SiteConfig<Config> {
    applicationKey: string;
    config: Config;
}
export declare type Site<Config> = Content<{
    description?: string;
    siteConfig: SiteConfig<Config> | SiteConfig<Config>[];
}, 'portal:site'>;
export interface GetSiteParams {
    key?: string | null;
}
/**
 * This function returns the parent site of a content.
 *
 * @example-ref examples/content/getSite.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the content.
 *
 * @returns {object} The current site as JSON.
 */
export declare function getSite<Config = Record<string, unknown>>(params: GetSiteParams): Site<Config> | null;
export interface GetSiteConfigParams {
    key: string;
    applicationKey: string;
}
/**
 * This function returns the site configuration for this app in the parent site of a content.
 *
 * @example-ref examples/content/getSiteConfig.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the content.
 * @param {string} params.applicationKey Application key.
 *
 * @returns {object} The site configuration for current application as JSON.
 */
export declare function getSiteConfig<Config = Record<string, unknown>>(params: GetSiteConfigParams): Config | null;
export interface DeleteContentParams {
    key: string;
}
/**
 * This function deletes a content.
 *
 * @example-ref examples/content/delete.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the content.
 *
 * @returns {boolean} True if deleted, false otherwise.
 */
declare function _delete(params: DeleteContentParams): boolean;
export { _delete as delete, };
export interface ContentsResult<Hit extends Content<unknown>, AggregationOutput extends Record<string, AggregationsResult> | undefined = undefined> {
    total: number;
    count: number;
    hits: Hit[];
    aggregations: AggregationOutput;
    highlight?: Record<string, HighlightResult>;
}
export interface GetChildContentParams {
    key: string;
    start?: number;
    count?: number;
    sort?: string;
}
/**
 * This function fetches children of a content.
 *
 * @example-ref examples/content/getChildren.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the parent content.
 * @param {number} [params.start=0] Start index (used for paging).
 * @param {number} [params.count=10] Number of contents to fetch.
 * @param {string} [params.sort] Sorting expression.
 *
 * @returns {Object} Result (of content) fetched from the repository.
 */
export declare function getChildren<Hit extends Content<unknown> = Content, AggregationOutput extends Record<string, AggregationsResult> = never>(params: GetChildContentParams): ContentsResult<Hit, AggregationOutput>;
export declare type IdGeneratorSupplier = (value: string) => string;
export interface CreateContentParams<Data, Type extends string> {
    name?: string;
    parentPath: string;
    displayName?: string;
    requireValid?: boolean;
    refresh?: boolean;
    contentType: Type;
    language?: string;
    childOrder?: string;
    data: Data;
    x?: XpXData;
    idGenerator?: IdGeneratorSupplier;
    workflow?: Workflow;
}
/**
 * This function creates a content.
 *
 * The parameter `name` is optional, but if it is not set then `displayName` must be specified. When name is not set, the
 * system will auto-generate a `name` based on the `displayName`, by lower-casing and replacing certain characters. If there
 * is already a content with the auto-generated name, a suffix will be added to the `name` in order to make it unique.
 *
 * To create a content where the name is not important and there could be multiple instances under the same parent content,
 * skip the `name` parameter and specify a `displayName`.
 *
 * @example-ref examples/content/create.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} [params.name] Name of content.
 * @param {string} params.parentPath Path to place content under.
 * @param {string} [params.displayName] Display name. Default is same as `name`.
 * @param {boolean} [params.requireValid=true] The content has to be valid, according to the content type, to be created. If requireValid=true and the content is not strictly valid, an error will be thrown.
 * @param {boolean} [params.refresh=true] If refresh is true, the created content will to be searchable through queries immediately, else within 1 second. Since there is a performance penalty doing this refresh, refresh should be set to false for bulk operations.
 * @param {string} params.contentType Content type to use.
 * @param {string} [params.language] The language tag representing the content’s locale.
 * @param {string} [params.childOrder] Default ordering of children when doing getChildren if no order is given in query
 * @param {object} params.data Actual content data.
 * @param {object} [params.x] eXtra data to use.
 * @param {object} [params.workflow] Workflow information to use. Default has state READY and empty check list.
 *
 * @returns {object} Content created as JSON.
 */
export declare function create<Data = Record<string, unknown>, Type extends string = string>(params: CreateContentParams<Data, Type>): Content<Data, Type>;
export interface QueryContentParams<AggregationInput extends Aggregations = never> {
    start?: number;
    count?: number;
    query?: QueryDsl | string;
    sort?: string | SortDsl | SortDsl[];
    filters?: Filter | Filter[];
    aggregations?: AggregationInput;
    contentTypes?: string[];
    highlight?: Highlight;
}
/**
 * This command queries content.
 *
 * @example-ref examples/content/query.js
 *
 * @param {object} params JSON with the parameters.
 * @param {number} [params.start=0] Start index (used for paging).
 * @param {number} [params.count=10] Number of contents to fetch.
 * @param {string|object} params.query Query expression.
 * @param {object|object[]} [params.filters] Filters to apply to query result
 * @param {string|object|object[]} [params.sort] Sorting expression.
 * @param {object} [params.aggregations] Aggregations expression.
 * @param {string[]} [params.contentTypes] Content types to filter on.
 *
 * @returns {object} Result of query.
 */
export declare function query<Hit extends Content<unknown> = Content, AggregationInput extends Aggregations = never>(params: QueryContentParams<AggregationInput>): ContentsResult<Hit, AggregationsToAggregationResults<AggregationInput>>;
export interface ModifyContentParams<Data, Type extends string> {
    key: string;
    editor: (v: Content<Data, Type>) => Content<Data, Type>;
    requireValid?: boolean;
}
/**
 * This function modifies a content.
 *
 * @example-ref examples/content/modify.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the content.
 * @param {function} params.editor Editor callback function.
 * @param {boolean} [params.requireValid=true] The content has to be valid, according to the content type, to be updated. If requireValid=true and the content is not strictly valid, an error will be thrown.
 *
 * @returns {object} Modified content as JSON.
 */
export declare function modify<Data = Record<string, unknown>, Type extends string = string>(params: ModifyContentParams<Data, Type>): Content<Data, Type> | null;
export interface PublishContentParams {
    keys: string[];
    schedule?: Schedule;
    includeChildren?: boolean;
    excludeChildrenIds?: string[];
    includeDependencies?: boolean;
    message?: string;
}
export interface PublishContentResult {
    pushedContents: string[];
    deletedContents: string[];
    failedContents: string[];
}
/**
 * This function publishes content from the draft branch to the master branch.
 *
 * @example-ref examples/content/publish.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string[]} params.keys List of all content keys(path or id) that should be published.
 * to another, and publishing user content from master to draft is therefore also valid usage of this function, which may be practical if user input to a web-page is stored on master.
 * @param {object} [params.schedule] Schedule the publish.
 * @param {string} [params.schedule.from] Time from which the content is considered published. Defaults to the time of the publish
 * @param {string} [params.schedule.to] Time until which the content is considered published.
 * @param {string[]} [params.excludeChildrenIds] List of all content keys which children should be excluded from publishing content.
 * @param {boolean} [params.includeDependencies=true] Whether all related content should be included when publishing content.
 * @param {string} [params.message] Publish message.
 *
 * @returns {object} Status of the publish operation in JSON.
 */
export declare function publish(params: PublishContentParams): PublishContentResult;
export interface UnpublishContentParams {
    keys: string[];
}
/**
 * This function unpublishes content that had been published to the master branch.
 *
 * @example-ref examples/content/unpublish.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string[]} params.keys List of all content keys(path or id) that should be unpublished.
 *
 * @returns {string[]} List with ids of the content that were unpublished.
 */
export declare function unpublish(params: UnpublishContentParams): string[];
export interface ContentExistsParams {
    key: string;
}
/**
 * Check if content exists.
 *
 * @example-ref examples/content/exists.js
 *
 * @param {string} params.key content id.
 *
 * @returns {boolean} True if exist, false otherwise.
 */
export declare function exists(params: ContentExistsParams): boolean;
export interface CreateMediaParams {
    name: string;
    parentPath?: string;
    mimeType?: string;
    focalX?: number;
    focalY?: number;
    data: ByteSource;
    idGenerator?: (v: string) => string;
}
/**
 * Creates a media content.
 *
 * @example-ref examples/content/createMedia.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.name Name of content.
 * @param {string} [params.parentPath=/] Path to place content under.
 * @param {string} [params.mimeType] Mime-type of the data.
 * @param {number} [params.focalX=0.5] Focal point for X axis (if it's an image).
 * @param {number} [params.focalY=0.5] Focal point for Y axis (if it's an image).
 * @param  params.data Data (as stream) to use.
 *
 * @returns {object} Returns the created media content.
 */
export declare function createMedia<Data = Record<string, unknown>, Type extends string = string>(params: CreateMediaParams): Content<Data, Type>;
export interface MoveContentParams {
    source: string;
    target: string;
}
/**
 * Rename a content or move it to a new path.
 *
 * @example-ref examples/content/move.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.source Path or id of the content to be moved or renamed.
 * @param {string} params.target New path or name for the content. If the target ends in slash '/', it specifies the parent path where to be moved. Otherwise it means the new desired path or name for the content.
 *
 * @returns {object} The content that was moved or renamed.
 */
export declare function move<Data = Record<string, unknown>, Type extends string = string>(params: MoveContentParams): Content<Data, Type>;
export interface ArchiveContentParams {
    content: string;
}
/**
 * Archive a content.
 *
 * @example-ref examples/content/archive.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.content Path or id of the content to be archived.
 *
 * @returns {string[]} List with ids of the contents that were archived.
 */
export declare function archive(params: ArchiveContentParams): string[];
export interface RestoreContentParams {
    content: string;
    path: string;
}
/**
 * Restore a content from the archive.
 *
 * @example-ref examples/content/restore.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.content Path or id of the content to be restored.
 * @param {string} params.path Path of parent for restored content.
 *
 * @returns {string[]} List with ids of the contents that were restored.
 */
export declare function restore(params: RestoreContentParams): string[];
export declare type Permission = 'READ' | 'CREATE' | 'MODIFY' | 'DELETE' | 'PUBLISH' | 'READ_PERMISSIONS' | 'WRITE_PERMISSIONS';
export interface AccessControlEntry {
    principal: string;
    allow?: Permission[];
    deny?: Permission[];
}
export interface SetPermissionsParams {
    key: string;
    inheritPermissions?: boolean;
    overwriteChildPermissions?: boolean;
    permissions?: AccessControlEntry[];
}
export interface Permissions {
    inheritsPermissions: boolean;
    permissions?: AccessControlEntry[];
}
/**
 * Sets permissions on a content.
 *
 * @example-ref examples/content/setPermissions.js
 *
 * @param {object} params JSON parameters.
 * @param {string} params.key Path or id of the content.
 * @param {boolean} [params.inheritPermissions] Set to true if the content must inherit permissions. Default to false.
 * @param {boolean} [params.overwriteChildPermissions] Set to true to overwrite child permissions. Default to false.
 * @param {array} [params.permissions] Array of permissions.
 * @param {string} params.permissions.principal Principal key.
 * @param {array} params.permissions.allow Allowed permissions.
 * @param {array} params.permissions.deny Denied permissions.
 * @returns {boolean} True if successful, false otherwise.
 */
export declare function setPermissions(params: SetPermissionsParams): boolean;
export interface GetPermissionsParams {
    key: string;
}
/**
 * Gets permissions on a content.
 *
 * @example-ref examples/content/getPermissions.js
 *
 * @param {object} params JSON parameters.
 * @param {string} params.key Path or id of the content.
 * @returns {object} Content permissions.
 */
export declare function getPermissions(params: GetPermissionsParams): Permissions | null;
export interface Icon {
    data: ByteSource;
    mimeType: string;
    modifiedTime: string;
}
/**
 * @typedef ContentType
 * @type Object
 * @property {string} name Name of the content type.
 * @property {string} displayName Display name of the content type.
 * @property {string} description Description of the content type.
 * @property {string} superType Name of the super type, or null if it has no super type.
 * @property {boolean} abstract Whether or not content of this type may be instantiated.
 * @property {boolean} final Whether or not it may be used as super type of other content types.
 * @property {boolean} allowChildContent Whether or not allow creating child items on content of this type.
 * @property {string} displayNameExpression ES6 string template for generating the content name based on values in the content form.
 * @property {object} [icon] Icon of the content type.
 * @property {object} [icon.data] Stream with the binary data for the icon.
 * @property {string} [icon.mimeType] Mime type of the icon image.
 * @property {string} [icon.modifiedTime] Modified time of the icon. May be used for caching.
 * @property {object[]} form Form schema represented as an array of form items: Input, ItemSet, Layout, OptionSet.
 */
export interface ContentType {
    name: string;
    displayName: string;
    description: string;
    superType: string;
    abstract: boolean;
    final: boolean;
    allowChildContent: boolean;
    displayNameExpression: string;
    modifiedTime: string;
    icon?: Icon;
    form: FormItem[];
}
/**
 * Returns the properties and icon of the specified content type.
 *
 * @example-ref examples/content/getType.js
 *
 * @param name Name of the content type, as 'app:name' (e.g. 'com.enonic.myapp:article').
 * @returns {ContentType} The content type object if found, or null otherwise. See ContentType type definition below.
 */
export declare function getType(name: string): ContentType | null;
/**
 * Returns the list of all the content types currently registered in the system.
 *
 * @example-ref examples/content/getTypes.js
 *
 * @returns {ContentType[]} Array with all the content types found. See ContentType type definition below.
 */
export declare function getTypes(): ContentType[];
export interface GetOutboundDependenciesParams {
    key: string;
}
/**
 * Returns outbound dependencies on a content.
 *
 * @param {object} params JSON parameters.
 * @param {string} params.key Path or id of the content.
 * @returns {object} Content Ids.
 */
export declare function getOutboundDependencies(params: GetOutboundDependenciesParams): string[];
export interface ResetInheritanceParams {
    key: string;
    projectName: string;
    inherit: ContentInheritValue[];
}
export interface ResetInheritanceHandler {
    setKey(value: string): void;
    setProjectName(value: string): void;
    setInherit(value: ContentInheritValue[]): void;
    execute(): void;
}
/** Resets dropped inherit flags back.
 *
 * @param {object} params JSON parameters.
 * @param {string} params.key Path or id of the content.
 * @param {string} params.projectName name of project with content.
 * @param {string[]} params.inherit flags to be reset.
 */
export declare function resetInheritance(params: ResetInheritanceParams): void;
export interface ModifyMediaParams {
    key: string;
    name: string;
    data: ByteSource;
    artist?: string | string[];
    caption?: string;
    copyright?: string;
    focalX?: number;
    focalY?: number;
    mimeType?: string;
    tags?: string | string[];
    workflow?: Workflow;
}
/** This function modifies a media content.
 *
 * @example-ref examples/content/modifyMedia.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.key Path or id to the content.
 * @param {string} params.name Name to the content.
 * @param {function} params.data Data (as stream) to use.
 * @param {string} [params.mimeType] Mime-type of the data.
 * @param {string|string[]} [params.artist] Artist to the content.
 * @param {string} [params.caption] Caption to the content.
 * @param {string} [params.copyright] Copyright to the content.
 * @param {string|string[]} [params.tags] Tags to the content.
 * @param {object} [params.workflow] Workflow information to use. Default has state READY and empty check list.
 * @param {number} [params.focalX=0.5] Focal point for X axis (if it's an image).
 * @param {number} [params.focalY=0.5] Focal point for Y axis (if it's an image).
 *
 * @returns {object} Modified content as JSON.
 */
export declare function modifyMedia<Data = Record<string, unknown>, Type extends string = string>(params: ModifyMediaParams): Content<Data, Type> | null;
export interface DuplicateContentParams {
    contentId: string;
    workflow?: Workflow;
    includeChildren?: boolean;
    variant?: boolean;
    parent?: string;
    name?: string;
}
export interface DuplicateContentsResult {
    contentName: string;
    sourceContentPath: string;
    duplicatedContents: string[];
}
/** This function duplicates a content.
 *
 * @example-ref examples/content/duplicate.js
 *
 * @param {object} params JSON with the parameters.
 * @param {string} params.contentId Id to the content.
 * @param {object} [params.workflow] Workflow information to use. Default has state READY and empty check list.
 * @param {boolean} [params.includeChildren=true] Indicates that children contents must be duplicated, too. Default value `true`. Ignored if `variant=true`.
 * @param {boolean} [params.variant=false] Indicates that duplicated content is a variant. Default value `false`.
 * @param {string} [params.parent] Destination parent path. By default, a duplicated content will be added as a sibling of the source content.
 * @param {string} [params.name] New content name.
 *
 * @returns {object} summary about duplicated content.
 */
export declare function duplicate(params: DuplicateContentParams): DuplicateContentsResult;