The CMS

Table of Contents

Setting up the CMS Object
- The <TinaProvider> Component
Accessing the CMS Object
Disabling / Enabling the CMS
CMS Configuration
Reference
- TinaCMS Interface

The CMS object in Tina is a container for attaching and accessing Plugins, APIs, and the Event Bus. On its own, the CMS does very little; however, since it's the central integration point for everything that Tina does, it's extremely important!

Reference Step 1 of the Introductory Tutorial for an example on setting up the CMS.

Setting up the CMS Object

A project that uses Tina will start by setting up an instance of the CMS.

import { TinaCMS } from 'tinacms'

const cms = new TinaCMS({ enabled: true })

The TinaCMS constructor receives an object that can be used to configure CMS behavior. See CMS Configuration for details.

The Component

The <TinaProvider> component should wrap your entire site. It provides the following:

The user interface for interacting with Tina.
A Context for accessing the CMS object via the useCMS hook.

After instantiating the CMS object, pass it to the <TinaProvider> component via its cms prop.

import * as React from 'react'
import { TinaProvider, TinaCMS } from 'tinacms'
import MyApp from './my-app'

export default function App() {
  const cms = React.useMemo(() => new TinaCMS({ enabled: true }))
  return (
    <TinaProvider cms={cms}>
      <MyApp />
    </TinaProvider>
  )
}

Learn more about conditionally loading Tina Styles.

Alternatively, you can use the withTina higher-order component to wrap your site with the <TinaProvider> component. withTina will automatically instantiate the CMS object.

import { withTina } from 'tinacms'
import MyApp from './my-app'

export default withTina(MyApp)

withTina accepts a configuration object as a second argument that is passed to the TinaCMS constructor.

import { withTina } from 'tinacms'
import MyApp from './my-app'

export default withTina(MyApp, {
  enabled: process.env.NODE_ENV !== 'production',
  sidebar: true,
})

Accessing the CMS Object

The CMS object can be retrieved from context via the useCMS hook. Reference the available core properties to work with.

import * as React from 'react'
import { useCMS } from 'tinacms'

// <SomeComponent /> is assumed to be nested inside of the <TinaProvider> context
export default function SomeComponent() {
  const cms = useCMS()
  //...
}

Disabling / Enabling the CMS

The CMS can be enabled or disabled via methods or configuration on the CMS object. Disabling the CMS prevents the editing UI from rendering and forms from registering.

import * as React from 'react'
import { useCMS } from 'tinacms'

// <ExitButton /> is assumed to be nested inside of the <TinaProvider> context
export default function ExitButton() {
  const cms = useCMS()

  return (
    <button onClick={() => cms.toggle()}>
      {cms.enabled ? `Exit Tina` : `Edit with Tina`}
    </button>
  )
}

CMS Configuration

When instantiating the TinaCMS object, you can pass in a configuration object. This allows you to configure some options for the sidebar, toolbar, and also allows you to configure Plugins and APIs declaratively.

interface TinaCMSConfig {
  enabled?: boolean
  plugins?: Plugin[]
  apis?: { [key: string]: any }
  sidebar?: SidebarConfig | boolean
  toolbar?: ToolbarConfig | boolean
  media?: {
    store: MediaStore
  }
  mediaOptions?: {
    pageSize?: number
  }
}

interface SidebarConfig {
  position?: SidebarPosition
  placeholder?: React.FC
  buttons?: {
    save: string
    reset: string
  }
}

interface ToolbarConfig {
  buttons?: {
    save: string
    reset: string
  }
}

key	usage
enabled	Controls whether the CMS is enabled or disabled. Defaults to `false`
plugins	Array of plugins to be added to the CMS object.
apis	Object containing APIs to be registered to the CMS
sidebar	Enables and configures behavior of the sidebar
toolbar	Configures behavior of the toolbar
media	Configures media.
pageSize	Sets how many media objects are displayed at a time in the media manager.

Learn more about sidebar & toolbar options.

Example

import { TinaCMS } from 'tinacms'

const cms = new TinaCMS({
  enabled: process.env.NODE_ENV !== 'production',
  plugins: [
    {
      __type: 'hello',
      name: 'hello-dj',
      user: 'DJ',
    },
  ],
  apis: {
    hello: {
      sayHello: () => alert('Hello, world!'),
    },
  },
  sidebar: {
    position: 'displace',
  },
  toolbar: false,
})

Reference

There are a number of core properties that can be helpful in working with the CMS.

TinaCMS Interface

interface TinaCMS {
  enabled: boolean
  disabled: boolean
  registerApi(name: string, api: any): void
  enable(): void
  disable(): void
  toggle(): void
}

property	description
`enabled`	Returns the enabled state. When `true`, content can be edited.
`disabled`	Returns the disabled state. When `true`, content cannot be edited.
`registerApi`	Registers a new external API with the CMS.
`enable`	Enables the CMS so content can be edited.
`disable`	Disables the CMS so content can no longer be edited.
`toggle`	Toggles the enabled/disabled state of the CMS .

Use the useCMS hook to access the CMS and execute these methods as needed.

Last Edited: June 22, 2021

Docs