Models

The Models API in Codex helps you define the structure for your content entries. Models are templates that specify the fields and configurations for various content types, allowing you to create consistent and organized content.

Schema

Each model in Codex is defined by a unique configuration of fields that determine the type, format, and validation for content entries. Additionally, models in Codex contain a few predefined fields for metadata and system tracking. Below is the structure of a model in Codex:

{
  "id": "id",
  "alias": "modela",
  "name": "model a",
  "iconId": "iconId",
  "externalId": "externalId",
  "description": "text",
  "versionId": "versionId",
  "deletedBlocks": [
        {
        // nested model block structure
        }
    ],
  "blocks": [
        {
        // nested model block structure
        }
    ],
  "featuredMediaAlias": "",
  "fields": [
        {
        //model field structure
        }
    ],
  "configurations": {},
  "defaultFolderId": "folderId",
  "deletedFields": [
        {
        //model field structure
        }
    ],
  "titleAlias": "title",
  "slugAlias": null,
  "status": 1,
  "revisionId": "revisionId",
  "restrictions": {},
  "siteConfigurations": [
        {
            //site model structure
        }
    ]
}

Model Fields

API only dynamic entry metadata placeholder. Can be used for different cusotm purposes on cases when you don't have to save these data on the content field.

id Unique identifier for the model.

alias The model's alias, formatted in lowercase with underscores. This alias is often used for URL generation.

name The display name of the model.

iconId Identifier of the icon associated with this model.

externalId An external ID of the model. This field is optional and is not generated by Codex.

description A description providing additional information about the model.

versionId The version ID of the model. This field is auto generated for each update of the model.

status Status of the entry. Values are:

1. PUBLISHED
2. DELETED
3. DRAFT

createdAt The date and time when the model was first created (in UTC).

updatedAt The date and time when the model was updated for the last time (in UTC).

createdBy The ID of the user who created the model.

updatedBy The ID of the user who updated the model for the last time.

revisionId The revision ID of the model. Is used for updating and conflict prevention.

blocks Array of active blocks within the model, following the ModelBlock structure.

deletedBlocks Array of blocks that were deleted from the model. Each entry follows the ModelBlock structure.

configurations Configuration settings for the model, defined by the Configurations object.

defaultFolderId Identifier of the default folder where the assets in model entries are stored.

fields Collection of fields that define the model's data. Each entry follows the Field structure.

deletedFields Collection of fields that have been deleted from the model. Each entry follows the Field structure.

titleAlias Field alias specifying the source field for the entry model's title, to be used as the entry's display title.

slugAlias Alias slugified. Can be null if no slug is defined.

restrictions Restrictions and permissions associated with the model, defined by the Restrictions object.

siteConfigurations Configuration settings unique to each site, with each entry following the model structure outlined in the site's model configuration schema

ModelBlock Structure

Each ModelBlock entry in blocks or deletedBlocks represents a block within the model, which can contain nested fields and configurations. Example structure:

{
  "id": "blockId",
  "type": "text",
  "isField": true,
  "attrs": {
    "key": "value",
    "otherAttribute": 123
  },
  "content": [
    {
      // Nested ModelBlock structure
    }
  ]
}

Field Structure

Each Field in fields or deletedFields describes a field in the model, such as text, media, date, or other types. Fields are represented by various types in Codex CMS and include validation logic. Example structure:

{
  "type": "TextField",
  "name": "Title",
  "alias": "title",
  "description": "The title of the content",
  "valueType": "string",
  "index": 1,
  "configuration": {
    // Field-specific configuration settings
  }
}

Supported Field Types include:

• RichTextField
• DecimalField
• IntegerField
• MediaField
• DateTimeField
• BooleanField
• LocationField
• TextField
• JsonField
• ReferenceField
• RichContentField
• AuthorField
• TagField
• SectionField
• UrlField

Configurations Structure

The Configurations object contains settings for customizing the model’s interface, access, and display options.

{
  "sidebar": {
    "customSidebarOption": "value"
  },
  "labels": {
    // Label configurations
  },
  "accessStrategy": "Unrestricted",
  "lockDurationInSeconds": 300,
  "hideInCreateButton": true,
  "hideInCloneButton": false
}

Restrictions Structure

The Restrictions object defines any restrictions associated with the model, including site access permissions.

{
  "sites": {
    "allowAll": false,
    "allowed": ["site1", "site2"]
  }
}

Model Update

To update a model in Codex CMS, follow these structured steps to ensure data consistency, prevent unintended overwrites, and minimize conflicts with concurrent changes. This process ensures that the latest model structure is preserved and modified as needed.

Steps for Updating a Model

1. Retrieve the Current Model State:

• Before making any updates, fetch the latest version of the model, including its revisionId. The revisionId is a unique identifier for each saved state of the model, enabling precise tracking of changes.

• This step ensures you are working with the most recent version, minimizing the chance of updating outdated or altered data.

2. Make the Necessary Changes:

• Modify the model as needed, which may include adding, updating, or removing blocks, fields, configurations, or restrictions.
• Ensure that any nested objects, such as Configurations, Fields, Blocks, and SiteConfigurations, are updated in line with the current model requirements.

3. Send the Entire Model Object in the Update Request:

• Codex requires that the entire updated model object be sent in the request, rather than partial updates. This includes:
  • All blocks (blocks and deletedBlocks), fields (fields and deletedFields), and other nested configurations.
  • The latest revisionId that was retrieved initially.
• This approach ensures that all fields, settings, and metadata are synchronized and prevents accidentally omitting fields that haven’t changed.

4. Validate and Confirm the Revision:

• The revisionId serves as a version control check. When the model update request is processed, Codex compares the submitted revisionId with the current model’s revisionId.
• If they match, Codex proceeds with the update, ensuring that no concurrent changes have been applied to the model since the initial retrieval.
• If the revisionId differs (indicating another update has occurred), Codex will reject the update and return an error, prompting the user to fetch the latest model version and reapply their changes to avoid conflicts.

5. Apply the Update:

• Once the revisionId is validated, Codex updates the model and assigns a new revisionId to reflect the latest saved state.
• This new revisionId is returned in the response, allowing subsequent changes to reference this updated state and maintain consistency.

Site-Specific Models

Codex CMS supports models that are specific to certain sites. By including the siteId in the update request body, the model adjustments will apply only to that specific site. This feature allows for tailored content structures based on site requirements without affecting other sites.

By following this structured approach, users can confidently update models in Codex CMS while maintaining data integrity, consistency, and tailored site-specific configurations.

Delete Model

In Codex CMS, a model can be deleted under certain conditions to ensure data integrity. The process can be performed either from the main list of models or directly within the model editor interface.

Conditions for Deleting a Model

1. Entries Must Be Deleted: A model can only be deleted if all of its entries have already been removed. This prevents data conflicts and maintains referential integrity across the CMS.
2. Permissions and Access: The user must have the necessary permissions to delete a model. Without proper authorization, deletion will not be permitted.

Steps for Deleting a Model

To delete a model, a DELETE request can be sent with the model's unique ID.

Important Notes

• Deletion Confirmation: Deleting a model is irreversible. Once a model is deleted, all associated configurations, fields, and settings will be permanently removed from the CMS.
• Error Handling: If any entries are still linked to the model, Codex CMS will prevent deletion and display an error message, prompting the user to delete all entries first.

By following these guidelines, users can delete models in Codex CMS while ensuring data integrity and preventing unintentional conflicts.