Content Commands

Content commands modify the document content tree (the livingdoc). They operate on components and directives within the document structure.

To find the component IDs and directive names needed for these commands, retrieve the document's Latest Draft.

insertComponent

Inserts a new component into the document content. The component must be allowed by the document's content type configuration.

Parameters

Position object:

When inserting into a non-empty container, you must provide either previousComponentId or nextComponentId to specify the position.

Example

{
  "operation": "insertComponent",
  "componentId": "doc-custom-123456",
  "componentName": "paragraph",
  "content": {
    "text": "Some text"
  },
  "position": {
    "parentComponentId": "doc-4a2b3g4d5",
    "parentContainerName": "children",
    "previousComponentId": "doc-1a2b3c4d5"
  }
}

Validation

• The componentName must be allowed by the document's content type configuration.
• If componentId is provided, it must not already exist in the document.
• parentComponentId and parentContainerName must be provided together. If one is set, the other is required.
• When inserting into a non-empty container, either previousComponentId or nextComponentId is required.
• Referenced component IDs (parentComponentId, previousComponentId, nextComponentId) must exist in the document.

removeComponent

Removes a component from the document content.

Parameters

Example

{
  "operation": "removeComponent",
  "componentId": "doc-4a2b3g4d5"
}

Validation

• The component must exist in the document.
• The component cannot be removed if it or its parent component has position: 'fixed' in the design configuration.

setEditableDirective

Sets the text content of an editable directive on a component.

Parameters

Example

{
  "operation": "setEditableDirective",
  "componentId": "doc-1a2b3c4d5",
  "directiveName": "headline",
  "value": "Updated headline"
}

Validation

• The component must exist in the document.
• The directive must exist on the component and be of type editable.
• The value must be a string or null.

setIncludeDirective

Updates the params and overrides of an include directive. These properties depend on each other: if only params are provided, any existing overrides are removed. Specifying overrides without params is invalid. To update overrides, both params and overrides must be provided.

Include params are a list of metadata properties, similar to the properties set via setMetadataProperty. Each param is backed by a metadata plugin type, and the expected value schema depends on the plugin. See Metadata Plugins (include context) for the storage schema of each plugin type available in include params.

Parameters

Value object:

Example

{
  "operation": "setIncludeDirective",
  "componentId": "doc-123",
  "directiveName": "related-article",
  "value": {
    "params": {
      "teaser": {
        "$ref": "document",
        "reference": {"id": "3"}
      }
    },
    "overrides": [
      {
        "id": "teaser-normal-3",
        "content": {
          "link": {"href": "https://example.com"},
          "title": "Changed title"
        },
        "originalSnapshot": {},
        "contentProperties": []
      }
    ]
  },
  "oldValue": null
}

Teaser Container Propagation

When the targeted include directive is inside a teaser container (isTeaserContainer: true) and all sibling teasers have compatible li-teaser param schemas, the algorithm and curatedList settings from the command are automatically applied to all sibling teasers in the same container. This mirrors the editor's bulk-editing behavior — updating one teaser's algorithmic settings updates the entire group.

The propagation only affects Level 2 (curated list) and Level 3 (algorithm) settings. Level 1 (direct reference) and overrides remain individual per teaser.

Validation

• The component must exist in the document.
• The directive must exist on the component and be of type include.
• If overrides are set, params must also be provided (as an object, not null).
• The include service referenced by the directive must exist in the project configuration.
• The params are validated against the include service's parameter schema.

setLinkDirective

Updates a link directive on a component.

Parameters

Value object:

Example

{
  "operation": "setLinkDirective",
  "componentId": "doc-123",
  "directiveName": "link",
  "value": {
    "href": "https://example.com/article/123",
    "target": "_blank",
    "$ref": "document",
    "reference": {"id": "123"}
  },
  "oldValue": {
    "href": "https://example.com/"
  }
}

Validation

• The component must exist in the document.
• The directive must exist on the component and be of type link.
• The href property is required when setting a value.

setStyleDirective

Sets a style property on a style directive. Supports style, option, and select style types.

Parameters

Example

{
  "operation": "setStyleDirective",
  "componentId": "doc-123",
  "directiveName": "appearance",
  "propertyName": "background",
  "value": "#1fc47a",
  "oldValue": "#000"
}

Validation

• The component must exist in the document.
• The directive must exist on the component and be of type style.
• The propertyName must exist in the directive's style configuration.
• For style type: value must be a CSS value string (no semicolons allowed).
• For option type: value must match the configured option value exactly.
• For select type: value must match one of the configured option values.

setComponentStyle

Sets a style property directly on a component (as opposed to on a style directive). Supports style, option, and select style types.

Parameters

Example

{
  "operation": "setComponentStyle",
  "componentId": "doc-123",
  "propertyName": "background",
  "value": "#1fc47a",
  "oldValue": "#000"
}

Validation

• The component must exist in the document.
• The propertyName must exist in the component's style configuration.
• For style type: value must be a CSS value string (no semicolons allowed).
• For option type: value must match the configured option value exactly.
• For select type: value must match one of the configured option values.

setComponentCondition

Sets a conditional display condition on a component. Conditions control when a component is visible based on criteria like date/time ranges or brand targeting.

Parameters

DateTime value object:

Brands value: An array of brand handle strings (minimum 1 item), or null to clear.

Examples

DateTime condition:

{
  "operation": "setComponentCondition",
  "componentId": "doc-123",
  "conditionName": "dateTime",
  "value": {
    "gte": "2025-01-01T10:30:00.000Z",
    "lt": "2025-02-02T14:30:00.000Z"
  }
}

Brands condition:

{
  "operation": "setComponentCondition",
  "componentId": "doc-123",
  "conditionName": "brands",
  "value": ["brand-a", "brand-b"]
}

Validation

• The component must exist in the document.
• The conditionName must be configured on the component in the content type configuration.
• For brands: every brand handle must exist in the project's brands configuration.

Related

• Latest Draft -- Retrieve the draft to get component IDs and directive names
• Design Settings -- Style and option configuration for components
• Include Services -- Include service configuration and parameter schemas
• Metadata Plugins (include context) -- Storage schemas for each metadata plugin type available in include params
• Brands -- Brand configuration for component conditions