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:

content/things.json
{
  "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.

See the Content model reference for more information.

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

  • Specify public: true at the top-level.
  • Specify the collection in the content namespace, for example: collection: content/testimonials.
  • Specify public: true on individual content fields, in which case only those fields which are made public will be available via the frontend API.

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.

Fields can also be displayed or locked dynamically based on record data: a field's conditions determine when it is shown, and readonly accepts either a boolean or a conditions object, making the field read-only when the criteria match the current record.

A field with type: "action" is a button that runs an app function, and stores no value. See Actions.

A field with type: "component" renders one of the app's own UI components in place of a standard input, and stores the value the component sets. In a view, refer to a component field by its id.

A field with type: "secret" is a short_text field for API keys and other credentials. The dashboard masks its value in the field input, with a button to show it. The value is stored as plain text and returned by the API like any other field, so a secret field must not be made public. Secret fields are not localized.

A content field with admin_zone: "sidebar" is shown in the side column of record pages in the new Swell dashboard, on orders, subscriptions, invoices, customers (accounts) and products. The dashboard shows one card for each app with sidebar fields, titled with the app's name and icon, and lists the app's sidebar fields in the order they're defined. Fields in the card that aren't readonly can be edited, and are saved with the app's other fields on the page. The classic dashboard doesn't show sidebar fields.

swell app push rejects admin_zone: "sidebar" on other standard collections, such as carts and coupons.

A component field with readonly: true turns the card into a live view of the app's data. The component receives the record in context.record, and can call the app's functions that have a route with its fetch prop. See UI components.

{
  "collection": "orders",
  "fields": [
    {
      "id": "warehouse_status",
      "type": "component",
      "component": "WarehouseStatus",
      "label": "Warehouse status",
      "admin_zone": "sidebar",
      "readonly": true
    },
    {
      "id": "warehouse_synced",
      "type": "short_text",
      "label": "Last synced",
      "admin_zone": "sidebar",
      "readonly": true
    }
  ]
}
import { useEffect, useState } from 'preact/hooks';
import type { ComponentProps } from '@swell/apps-sdk/components';

export const config = {
  description: 'Warehouse status of an order',
};

export default function WarehouseStatus({
  context,
  fetch,
}: ComponentProps<string | null, { record?: { id?: string } }>) {
  const orderId = context?.record?.id;
  const [status, setStatus] = useState('Loading...');

  useEffect(() => {
    fetch(`/functions/warehouse/order-status?id=${orderId}`)
      .then((res) => res.json())
      .then((data) => setStatus(data.status))
      .catch(() => setStatus('Unavailable'));
  }, [orderId]);

  return <div style={{ font: '13px/18px sans-serif' }}>{status}</div>;
}

In this example, order pages show a card titled with the app's name. It holds the order's status from the app's order-status function, and the warehouse_synced value the app's functions write.

Actions are buttons displayed on list and record views, either in the page header or in the Actions menu in the Swell dashboard. An action can navigate to another page, either in the dashboard or externally, or to a page of the app's own frontend displayed within the dashboard. An action can also run an app function or workflow. A view's actions appear in its header, its extra_actions in its Actions menu, and a list view's bulk_actions in the bulk bar when records are selected. See Actions for actions that run functions.

Record view actions support the following properties:

  • id: Identifier of the action. The built-in ids new, save, and delete apply standard behaviors: save submits the record form, delete deletes the record, and new opens the record creation page.
  • label: Label displayed on the action button. Defaults to a formatted version of the id.
  • link: URL the action navigates to. Supports {field} placeholders that are replaced with values from the current record, for example frontend://reviews/{id}.
  • external: Indicates whether the link opens as an external URL instead of being routed within the dashboard.
  • submit: Indicates whether the action submits the record form, saving any pending changes.
  • icon: Icon identifier displayed on the action button.
  • type: Button style of a header button: default, primary, secondary, or danger.
  • conditions: Criteria evaluated against the current record. The action is only displayed while its conditions match.
  • function: Name of an app function or workflow to run when the action is clicked. Cannot be combined with link.
  • modal: Dialog shown before the function runs, to confirm the action or collect input.
  • hint: Tooltip shown after hovering over the action for 2 seconds.
  • loading_label: Text shown while the function runs.
  • hidden: Hides the action.
  • target: Where a link opens, usually blank or self.

List view actions support the same properties. In list views, conditions are evaluated against an empty record for link actions, and ignored for function actions.

When a view does not define actions, list views include a New action, and record views include a Save action in the header and a Delete action in the Actions menu. Actions and extra_actions you define are added after these defaults. To replace the defaults, include the built-in ids you want to keep, such as "save"; an array that names a built-in id is the complete list. Record view actions defined on standard collections such as products are also added to the Actions menu of the corresponding dashboard pages.

A record view action can also define conditions evaluated against the current record, so the action is only displayed when the criteria match. Conditions support the same query operators as view and field conditions, such as $ne, $gt, and $in, and can reference fields defined by other apps using $app.<app_id>.<field> keys. For example:

{
  "actions": [
    {
      "id": "view-orders",
      "label": "View orders",
      "link": "/orders",
      "conditions": {
        "status": "active"
      }
    }
  ]
}

An action's link can also point to the app's own frontend using the frontend:// scheme. The path after the scheme resolves to a route in your app frontend, which is displayed embedded within the Swell dashboard. For example:

{
  "actions": [
    {
      "id": "view-report",
      "label": "View report",
      "link": "frontend://reports/sales"
    }
  ]
}

An action can also run an app function. Set function to the name of a function or workflow that declares action: true:

{
  "actions": [
    {
      "id": "send_to_warehouse",
      "label": "Send to warehouse",
      "function": "send-product"
    }
  ]
}

→ See Actions for dialogs, bulk actions, action fields, and what the function receives.

A list view's filters are displayed in the Filter menu of the collection page. Each filter matches records by the value of one field. On standard collections such as products, an app's filters are added to the page's own filters.

PropertyDescription
idID of the content field to filter by. Required.
labelLabel of the filter in the Filter menu.
typeInput used to enter the filter value. Required. Filters with any other type are not displayed.
optionsFor select only. Options to choose from, each with a value and a label. A filter does not use the options of the field it filters, so a select filter must define its own.
collectionFor lookup only. Collection to look up records in.

Filters support the following types:

  • short_text: Text input.
  • long_text: Text input.
  • number: Number input.
  • select: Choice of the filter's options.
  • boolean: Choice of yes or no.
  • date: Date input.
  • tags: Tags input.
  • color: Color value input.
  • lookup: Record picker for the collection set in collection.
  • product_lookup: Product picker.
  • variant_lookup: Product variant picker.
  • category_lookup: Category picker.
  • customer_lookup: Customer picker.

Field type aliases such as text and toggle are not supported as filter types.

A list view's nav adds a link to the collection page in the dashboard's sidebar.

PropertyDescription
labelText of the sidebar link. Defaults to the view's label.
parentSidebar section the link is added to. If not set, the link is added at the top level.
iconIcon of a top-level link. One of home, orders, subscriptions, customers, products, discounts, apps, reporting, storefront, integrations, developer, or settings.
linkURL the sidebar link opens instead of the collection page. A frontend:// link opens a page of the app's frontend, displayed within the dashboard.
targetWhere the link opens: blank for a new tab, or self. Defaults to self.

The following parent sections are supported:

  • orders: Orders section.
  • products: Products section.
  • discounts: Discounts section.
  • content: Content section.
  • reporting: Reporting section.

An edit view's nav.link is opened when a record is clicked in the collection list. The link can include {field} placeholders, which are replaced with values of the clicked record, for example frontend://reviews/{id}.

In the new Swell dashboard, a list view field with badge shows its value as a badge. Set badge to true to show neutral badges, or to an object that maps values to tones. Values the object doesn't map show as neutral badges. For a select field, the badge shows the option's label and is matched by its value. For a field with a template, the badge is matched by the rendered text. The classic dashboard shows the value as text.

Badges support the following tones:

  • ok: Green.
  • warn: Amber.
  • danger: Red.
  • info: Teal.
  • accent: Blue.
  • neutral: Gray.

In the new Swell dashboard, a list view tab with alert adds an alert to the notifications menu while the tab has records. The alert shows its label, the number of records and the app's name, and opens the list on that tab. The dashboard updates the counts every 2 minutes. On standard collections such as orders, only tabs in the app's list view with id list add alerts. The classic dashboard doesn't show tab alerts.

PropertyDescription
labelText of the alert, such as Open tickets. Required.
toneColor of the alert: info, warn or danger. Defaults to warn.
{
  "collection": "tickets",
  "fields": [
    {
      "id": "status",
      "type": "select",
      "label": "Status",
      "options": [
        { "value": "open", "label": "Open" },
        { "value": "waiting", "label": "Waiting" },
        { "value": "closed", "label": "Closed" }
      ]
    }
  ],
  "views": [
    {
      "id": "list",
      "fields": [
        {
          "id": "status",
          "badge": { "open": "danger", "waiting": "warn", "closed": "ok" }
        }
      ],
      "tabs": [
        {
          "id": "open",
          "label": "Open",
          "query": { "status": "open" },
          "alert": { "label": "Open tickets", "tone": "danger" }
        }
      ]
    }
  ]
}

In this example, the Status column shows Open, Waiting and Closed as red, amber and green badges. While any ticket is open, the notifications menu shows Open tickets with their count.

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

content/things.json
{
  "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",
          "options": [
            { "value": "active", "label": "Active" },
            { "value": "inactive", "label": "Inactive" }
          ]
        }
      ]
    }
  ]
}

In this example, we've defined a list view for the things content model, specifying the columns to be displayed 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:

content/products.json
{
  "collection": "products",
  "views": [
    {
      "id": "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.