Content

Content models are a layer above data models, with the primary purpose of defining the content management experience presented in a store’s dashboard.

This two-tiered approach makes it easier to separate concerns between the database schema, API functionality, and administrative workflows. See our guide on content models vs data models for more details.

You can create a new content model by adding a configuration to the app's content/ folder, or by using the following CLI command:

swell create content

→ See the CLI reference for more details and options.

Here's an example of a new content model:

{
  "collection": "things",
  "fields": [
    {
      "id": "name",
      "type": "text"
      "required": true
    },
    {
      "id": "description",
      "type": "long_text"
      "hint": "Describe this thing in 2-3 sentences"
    }
  ]
}

Notice the difference between content and data model configurations. Content models prefer UI-oriented field types, which for example can specify short vs long text, and field ordering to display in the admin dashboard, while data models are purely schema-oriented to structure the database and related APIs.

In the above example, the things collection is not standard, therefore a new data model and collection will be established by the app. If it did exist, then the platform would automatically enhance the underlying data model associated with that collection.

Content model collections are private by default, however they can be made to support accessing data from the frontend API in two three ways:

These methods will make some or all collection data readable. In order to make data writable, add public_permissions to the respective data model. See the Data model reference for details.

Here’s an example model with a public field:

{
  "collection": "vendors",
  "label": "Vendors",
  "fields": {
    "name": {
      "type": "string",
      "required": true,
      "public": true
    },
    "active": {
      "type": "bool"
    },
    "description": {
      "type": "string"
    }
  },
  "public_permissions": {
    "query": {
      "active": true
    },
    "expands": {
      "products": {
        "url": "/products",
        "params": {
          "vendor_id": "id"
        },
        "data": {
          "active": true
        }
      }
    }
  }
}

With at least 1 public field declared, all records can be accessed by the frontend API, with only the public fields being returned in a response. In addition, you can limit the range of results to only include active records using public_permissions, and specify how expand parameters should be treated for the collection in a public scope.

Views are an aspect of content models used to provide merchants with different ways of visualizing and editing data, as well as defining app-specific actions for standard and custom models.

Views are configurations that represent fully functional, native pages in the Swell dashboard. There are two primary types of views: List (list) and Record (edit, and new). List views display collections of items, while Record views focus on displaying the details of a single item. Apps can address various use cases to help merchants manage data within the dashboard by adding Tabs and Fields to both standard and app-specific collections.

List views provide an overview of content, displaying multiple items in a structured format, often with filtering and sorting capabilities. Record views, on the other hand, focus on a single content item, allowing for in-depth management and modification of its properties. Both view types can be customized to fit specific use cases and requirements.

Both List and Record views can organize fields into tabs that can be sorted and hidden by a merchant. They can be applied to any standard or app-defined view, giving merchants full control over their dashboard workflows. View fields can refer to standard or app-defined data, and apply UI validation, help descriptions, and more.

Actions can be embedded as a field on the page, or in the Actions menu in the Swell dashboard. The most basic action can be configured to navigate to another page, either in the dashboard or externally. More advanced actions can be configured to call an app function that processes data and applies changes to the current view.

Here's an example of a basic view configuration for the things content model:

{
  "collection": "things",
  "fields": [
    {
      "id": "name",
      "type": "text",
      "required": true
    },
    {
      "id": "description",
      "type": "long_text",
      "hint": "Describe this thing in 2-3 sentences"
    },
    {
      "id": "status",
      "type": "select",
      "options": [
        { "value": "active", "label": "Active" },
        { "value": "inactive", "label": "Inactive" },
      ]
    }
  ],
  "views": [
    {
      "id": "list",
      "type": "list",
      "fields": [
        { "id": "name" },
        { "id": "description" }
      ],
      "filters": [
        {
          "id": "status",
          "type": "select",
          "label": "Status"
        }
      ]
    }
  ]
}

In this example, we've defined a list view for the things content model, specifying the columns to be displayed, the actions available, and a filter for the status field.

You can also modify existing views of a content model by referencing the specific view you want to modify. Here's an example of how to add a tab to the list view of the products content model:

{
  "collection": "products",
  "views": [
    {
      "list": {
        "tabs": [
          {
            "id": "my_app_tab",
            "label": "Product things",
            "query": {
              "$app.my_app.thing_id": { "$ne": null }
            },
            "fields": [
              { "id": "name" },
              { "id": "thing_id" }
            ]
          }
        ]
      }
    }
  ]
}

In this example, we've added a new tab called “Product things” to the list view of the products content model. The tab also specifies which fields should be visible on the tab by default.

Views can be used in combination with Swell's webhooks and serverless functions to create a seamless, personalized experience for merchants. More information about webhooks and functions can be found in later sections of the documentation.