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!
A project that uses Tina will start by setting up an instance of the CMS.
import { TinaCMS } from 'tinacms'
const cms = new TinaCMS()
The TinaCMS
constructor receives an object that can be used to configure CMS behavior. See CMS Configuration for details.
The <TinaProvider>
component should wrap your entire site. It provides the following:
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())
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,
})
The CMS object can be retrieved from context via the useCMS
hook.
import * as React from 'react'
import { useCMS } from 'tinacms'
// <SomeComponent /> is assumed to be nested inside of a <Tina> component
export default function SomeComponent() {
const cms = useCMS()
//...
}
The CMS can be enabled or disabled via methods or configuration on the CMS object.
import * as React from 'react'
import { useCMS } from 'tinacms'
// <ExitButton /> is assumed to be nested inside of a <Tina> component
export default function ExitButton() {
const cms = useCMS()
return (
<button onClick={() => cms.toggle()}>
{cms.enabled ? `Exit Tina` : `Edit with Tina`}
</button>
)
}
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
}
}
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 true |
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 |
sidebar.position | 'displace' (Default): sidebar pushes content to the side when open; 'overlay': sidebar overlaps content when open |
sidebar.placeholder | Provides a placeholder component to render in the sidebar when there are no registered forms |
sidebar.buttons | Deprecated — Configure on the form instead: Configures the text on 'Save' and 'Reset' buttons |
toolbar | Configures behavior of the toolbar |
toolbar.buttons | Deprecated — Configure on the form instead: Configures the text on 'Save' and 'Reset' buttons |
media.store | Configures the media store. |
Learn more about sidebar & toolbar options.
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,
})
It is now recommended to configure button text on the form intead of in the CMS object. Please read further on configuring custom buttons in the form documentation.
There are a number of core properties that can be helpful in working with the CMS.
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.