{"pageProps":{"error":null,"preview":false,"file":{"fileRelativePath":"content/docs/cms.md","data":{"frontmatter":{"title":"The CMS","next":"/docs/ui","consumes":[{"file":"/packages/tinacms/src/tina-cms.ts","description":"Creates TinaCMS instance and describes config"},{"file":"/packages/tinacms/src/react-tinacms/with-tina.tsx","description":"Shows how to use withTina HOC"},{"file":"/packages/tinacms/src/use-cms.ts","description":"Demonstrates useCMS hook"},{"file":"/packages/react-sidebar/sidebar.ts","description":"Shows sidebar state interface"},{"file":"/packages/react-toolbar/toolbar.ts","description":"Shows Toolbar state interface"}]},"excerpt":" 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&hellip;","markdownBody":"\nThe CMS object in Tina is a container for attaching and accessing [Plugins](/docs/plugins), [APIs](/docs/apis), and the [Event Bus](/docs/events). 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!\n\n## Setting up the CMS Object\n\nA project that uses Tina will start by setting up an instance of the CMS.\n\n```javascript\nimport { TinaCMS } from 'tinacms'\n\nconst cms = new TinaCMS()\n```\n\nThe `TinaCMS` constructor receives an object that can be used to configure CMS behavior. See [CMS Configuration](#cms-configuration) for details.\n\n### The <TinaProvider> Component\n\nThe `<TinaProvider>` component should wrap your entire site. It provides the following:\n\n1. The user interface for interacting with Tina.\n2. A [Context](https://reactjs.org/docs/context.html) for accessing the CMS object via the [useCMS](#accessing-the-cms-object) hook.\n\nAfter instantiating the CMS object, pass it to the `<TinaProvider>` component via its `cms` prop.\n\n```jsx\nimport * as React from 'react'\nimport { TinaProvider, TinaCMS } from 'tinacms'\nimport MyApp from './my-app'\n\nexport default function App() {\n  const cms = React.useMemo(() => new TinaCMS())\n  return (\n    <TinaProvider cms={cms}>\n      <MyApp />\n    </TinaProvider>\n  )\n}\n```\n\n> Learn more about [conditionally loading Tina Styles](/docs/ui/styles#dynamically-loading-tina-styles).\n\nAlternatively, you can use the `withTina` higher-order component to wrap your site with the `<TinaProvider>` component. `withTina` will automatically instantiate the CMS object.\n\n```javascript\nimport { withTina } from 'tinacms'\nimport MyApp from './my-app'\n\nexport default withTina(MyApp)\n```\n\n`withTina` accepts a [configuration object](#cms-configuration) as a second argument that is passed to the `TinaCMS` constructor.\n\n```javascript\nimport { withTina } from 'tinacms'\nimport MyApp from './my-app'\n\nexport default withTina(MyApp, {\n  enabled: process.env.NODE_ENV !== 'production',\n  sidebar: true,\n})\n```\n\n## Accessing the CMS Object\n\nThe CMS object can be retrieved from context via the `useCMS` hook.\n\n```javascript\nimport * as React from 'react'\nimport { useCMS } from 'tinacms'\n\n// <SomeComponent /> is assumed to be nested inside of a <Tina> component\nexport default function SomeComponent() {\n  const cms = useCMS()\n  //...\n}\n```\n\n## Disabling / Enabling the CMS\n\nThe CMS can be enabled or disabled via methods or configuration on the CMS object.\n\n```js\nimport * as React from 'react'\nimport { useCMS } from 'tinacms'\n\n// <ExitButton /> is assumed to be nested inside of a <Tina> component\nexport default function ExitButton() {\n  const cms = useCMS()\n\n  return (\n    <button onClick={() => cms.toggle()}>\n      {cms.enabled ? `Exit Tina` : `Edit with Tina`}\n    </button>\n  )\n}\n```\n\n## CMS Configuration\n\nWhen 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](/docs/plugins) and [APIs](/docs/apis) declaratively.\n\n```typescript\ninterface TinaCMSConfig {\n  enabled?: boolean\n  plugins?: Plugin[]\n  apis?: { [key: string]: any }\n  sidebar?: SidebarConfig | boolean\n  toolbar?: ToolbarConfig | boolean\n  media?: {\n    store: MediaStore\n  }\n}\n\ninterface SidebarConfig {\n  position?: SidebarPosition\n  placeholder?: React.FC\n  buttons?: {\n    save: string\n    reset: string\n  }\n}\n\ninterface ToolbarConfig {\n  buttons?: {\n    save: string\n    reset: string\n  }\n}\n```\n\n---\n\n| key                     | usage                                                                                                                                   |\n| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |\n| **enabled**             | Controls whether the CMS is enabled or disabled. _Defaults to true_                                                                     |\n| **plugins**             | Array of plugins to be added to the CMS object.                                                                                         |\n| **apis**                | Object containing APIs to be registered to the CMS                                                                                      |\n| **sidebar**             | Enables and configures behavior of the sidebar                                                                                          |\n| **sidebar.position**    | 'displace' _(Default)_: sidebar pushes content to the side when open; 'overlay': sidebar overlaps content when open                     |\n| **sidebar.placeholder** | Provides a placeholder component to render in the sidebar when there are no registered forms                                            |\n| **sidebar.buttons**     | _Deprecated — [Configure on the form instead](/docs/forms#customizing-form-buttons)_: Configures the text on 'Save' and 'Reset' buttons |\n| **toolbar**             | Configures behavior of the toolbar                                                                                                      |\n| **toolbar.buttons**     | _Deprecated — [Configure on the form instead](/docs/forms#customizing-form-buttons)_: Configures the text on 'Save' and 'Reset' buttons |\n| **media.store**         | Configures the [media store](/docs/media).                                                                                              |\n\n---\n\n> Learn more about [sidebar & toolbar options](/docs/cms/ui).\n\n```javascript\nimport { TinaCMS } from 'tinacms'\n\nconst cms = new TinaCMS({\n  enabled: process.env.NODE_ENV !== 'production',\n  plugins: [\n    {\n      __type: 'hello',\n      name: 'hello-dj',\n      user: 'DJ',\n    },\n  ],\n  apis: {\n    hello: {\n      sayHello: () => alert('Hello, world!'),\n    },\n  },\n  sidebar: {\n    position: 'displace',\n  },\n  toolbar: false,\n})\n```\n\n### Customize 'Save' & 'Reset' button text\n\nIt is now recommended to configure button text on the form intead of in the CMS object. Please read further on [configuring custom buttons](/docs/forms#customizing-form-buttons) in the form documentation.\n\n## Reference\n\nThere are a number of [core properties](https://github.com/tinacms/tinacms/blob/master/packages/%40tinacms/core/src/cms.ts) that can be helpful in working with the CMS.\n\n### TinaCMS Interface\n\n```ts\ninterface TinaCMS {\n  enabled: boolean\n  disabled: boolean\n  registerApi(name: string, api: any): void\n  enable(): void\n  disable(): void\n  toggle(): void\n}\n```\n\n| property      | description                                                                                   |\n| ------------- | --------------------------------------------------------------------------------------------- |\n| `enabled`     | Returns the enabled state. When `true`, content _can_ be edited.                              |\n| `disabled`    | Returns the disabled state. When `true`, content _cannot_ be edited.                          |\n| `registerApi` | Registers a new [external API](/docs/apis#adding-an-api) with the CMS.                        |\n| `enable`      | [Enables](/docs/cms#disabling--enabling-the-cms) the CMS so content can be edited.            |\n| `disable`     | [Disables](/docs/cms#disabling--enabling-the-cms) the CMS so content can no longer be edited. |\n| `toggle`      | [Toggles](/docs/cms#disabling--enabling-the-cms) the enabled/disabled state of the CMS .      |\n\n> Use the `useCMS` hook to [access the CMS](/docs/cms#accessing-the-cms-object) and execute these methods as needed.\n"}},"tocItems":"- [Setting up the CMS Object](#setting-up-the-cms-object)\n  * [The Component](#the--component)\n- [Accessing the CMS Object](#accessing-the-cms-object)\n- [Disabling / Enabling the CMS](#disabling--enabling-the-cms)\n- [CMS Configuration](#cms-configuration)\n  * [Customize 'Save' & 'Reset' button text](#customize-save--reset-button-text)\n- [Reference](#reference)\n  * [TinaCMS Interface](#tinacms-interface)","docsNav":[{"title":"Getting Started","id":"getting-started","items":[{"id":"/docs/getting-started/introduction","slug":"/docs/getting-started/introduction","title":"Introduction"}]},{"title":"CMS","id":"the-cms","items":[{"id":"/docs/cms","slug":"/docs/cms","title":"Overview"}]},{"title":"User Interface","id":"user-interface","items":[{"id":"/docs/ui","title":"Sidebar & Toolbar","slug":"/docs/ui"},{"title":"Inline Editing","id":"inline-editing","slug":"/docs/ui/inline-editing","items":[{"id":"/docs/ui/inline-editing/inline-text","title":"Inline Text","slug":"/docs/ui/inline-editing/inline-text"},{"id":"/docs/ui/inline-editing/inline-textarea","title":"Inline Textarea","slug":"/docs/ui/inline-editing/inline-textarea"},{"id":"/docs/ui/inline-editing/inline-wysiwyg","title":"Inline Wysiwyg","slug":"/docs/ui/inline-editing/inline-wysiwyg"},{"id":"/docs/ui/inline-editing/inline-image","title":"Inline Image","slug":"/docs/ui/inline-editing/inline-image"},{"id":"/docs/ui/inline-editing/inline-group","title":"Inline Group","slug":"/docs/ui/inline-editing/inline-group"},{"id":"/docs/ui/inline-editing/inline-blocks","title":"Inline Blocks","slug":"/docs/ui/inline-editing/inline-blocks"}]},{"id":"/docs/ui/alerts","title":"Alerts","slug":"/docs/ui/alerts"},{"id":"/docs/ui/styles","title":"Custom Styles","slug":"/docs/ui/styles"}]},{"id":"plugins","title":"Plugins","items":[{"title":"About Plugins","id":"forms","slug":"/docs/plugins"},{"title":"Forms","id":"forms","slug":"/docs/plugins/forms"},{"title":"Fields","id":"fields","slug":"/docs/plugins/fields","items":[{"id":"/docs/plugins/fields/text","slug":"/docs/plugins/fields/text","title":"Text"},{"id":"/docs/plugins/fields/textarea","slug":"/docs/plugins/fields/textarea","title":"Text Area"},{"id":"/docs/plugins/fields/number","slug":"/docs/plugins/fields/number","title":"Number"},{"id":"/docs/plugins/fields/image","slug":"/docs/plugins/fields/image","title":"Image"},{"id":"/docs/plugins/fields/color","slug":"/docs/plugins/fields/color","title":"Color"},{"id":"/docs/plugins/fields/toggle","slug":"/docs/plugins/fields/toggle","title":"Toggle"},{"id":"/docs/plugins/fields/select","slug":"/docs/plugins/fields/select","title":"Select"},{"id":"/docs/plugins/fields/tags","slug":"/docs/plugins/fields/tags","title":"Tags"},{"id":"/docs/plugins/fields/list","slug":"/docs/plugins/fields/list","title":"List"},{"id":"/docs/plugins/fields/group","slug":"/docs/plugins/fields/group","title":"Group"},{"id":"/docs/plugins/fields/group-list","slug":"/docs/plugins/fields/group-list","title":"Group List"},{"id":"/docs/plugins/fields/blocks","slug":"/docs/plugins/fields/blocks","title":"Blocks"},{"id":"/docs/plugins/fields/date","slug":"/docs/plugins/fields/date","title":"Date & Time"},{"id":"/docs/plugins/fields/markdown","slug":"/docs/plugins/fields/markdown","title":"Markdown"},{"id":"/docs/plugins/fields/html","slug":"/docs/plugins/fields/html","title":"HTML"},{"id":"/docs/plugins/fields/custom-fields","slug":"/docs/plugins/fields/custom-fields","title":"Custom Fields"}]},{"title":"Content Creators","id":"content-creator","slug":"/docs/plugins/content-creators"},{"title":"Screens","id":"screens","slug":"/docs/plugins/screens"},{"title":"Toolbar Widgets","id":"toolbar:widget","slug":"/docs/plugins/toolbar-widgets"}]},{"id":"events","title":"Events","items":[{"id":"/docs/events","slug":"/docs/events","title":"About Events"}]},{"title":"Media","id":"media","items":[{"id":"/docs/media","slug":"/docs/media","title":"About Media"}]},{"id":"apis","title":"External APIs","items":[{"id":"/docs/api","slug":"/docs/apis","title":"About APIs"}]},{"title":"Integrations","id":"nextjs","items":[{"id":"/docs/integrations/nextjs","slug":"/docs/integrations/nextjs","title":"Next.js"},{"id":"/docs/integrations/gatsby","slug":"/docs/integrations/gatsby","title":"Gatsby"}]},{"title":"Release Notes","id":"releases","items":[{"id":"/docs/releases","href":"/docs/releases","title":"All Releases"}]},{"title":"Packages","id":"packages","items":[{"id":"/packages/react-tinacms-date","slug":"/packages/react-tinacms-date","title":"react-tinacms-date"},{"id":"/packages/react-tinacms-editor","slug":"/packages/react-tinacms-editor","title":"react-tinacms-editor"},{"id":"/packages/react-tinacms-github","slug":"/packages/react-tinacms-github","title":"react-tinacms-github"},{"id":"/packages/react-tinacms-inline","slug":"/packages/react-tinacms-inline","title":"react-tinacms-inline"},{"id":"/packages/react-tinacms-strapi","slug":"/packages/react-tinacms-strapi","title":"react-tinacms-strapi"},{"id":"/packages/next-tinacms-github","slug":"/packages/next-tinacms-github","title":"next-tinacms-github"},{"id":"/packages/next-tinacms-json","slug":"/packages/next-tinacms-json","title":"next-tinacms-json"},{"id":"/packages/next-tinacms-markdown","slug":"/packages/next-tinacms-markdown","title":"next-tinacms-markdown"},{"id":"/packages/gatsby-plugin-tinacms","slug":"/packages/gatsby-plugin-tinacms","title":"gatsby-plugin-tinacms"},{"id":"/packages/gatsby-tinacms-git","slug":"/packages/gatsby-tinacms-git","title":"gatsby-tinacms-git"},{"id":"/packages/gatsby-tinacms-json","slug":"/packages/gatsby-tinacms-json","title":"gatsby-tinacms-json"},{"id":"/packages/gatsby-tinacms-remark","slug":"/packages/gatsby-tinacms-remark","title":"gatsby-tinacms-remark"}]}],"nextPage":{"slug":"/docs/ui","title":"Configure the User Interface"},"prevPage":{"slug":null,"title":null}},"__N_SSG":true}