{"pageProps":{"error":null,"preview":false,"file":{"fileRelativePath":"content/docs/events.md","data":{"frontmatter":{"title":"Events","prev":"/docs/plugins","next":"/docs/media"},"excerpt":" The Events feature allows decoupled parts of the CMS to: Notify the rest of the system that something has happened, and React to things that happen elsewhere in the system. Interface Usage…","markdownBody":"\nThe **Events** feature allows decoupled parts of the CMS to:\n\n1. Notify the rest of the system that something has happened, and\n2. React to things that happen elsewhere in the system.\n\n## Interface\n\n```ts\ninterface Events {\n  dispatch(event: Event): void\n  subscribe(eventType: string, listener: Listener): Unsubscribe\n}\n\ninterface Event {\n  type: string\n  // Any other data may be added to the event.\n  [key: string]: any\n}\n\ntype Listener = (event: Event) => void\n\ntype Unsubscribe = () => void\n```\n\n## Usage\n\n### Dispatching Events\n\n```ts\ncms.events.dispatch({\n  type: 'something-happened',\n})\n```\n\n### Subscribing to Events\n\nThe `cms.events.subscribe` function can be used to start listening for certain events.\n\n```ts\ncms.events.subscribe(EVENT_NAME, event => {\n  // ...\n})\n```\n\nThe `EVENT_NAME` is a string that matches a pattern for the event name.\n\n[Checkout the tests for specific examples of how the matching happens.](https://github.com/tinacms/tinacms/blob/master/packages/@tinacms/core/src/events.test.ts)\n\n#### Log all Events\n\n```ts\ncms.events.subscribe('*', event => {\n  console.log(event)\n})\n```\n\n### Log when a Form Plugin is added\n\n```ts\ncms.events.subscribe(\"plugins:add:form\", (event) => {\n  console.log(`Added a Form called \"${event.plugin.name}\"`\n})\n```\n\n#### Log all Form Events\n\n```ts\ncms.events.subscribe('plugins:*:form', event => {\n  console.log(`Something happened to the form plugins`)\n})\n```\n\n#### Log all Plugin Events\n\n```ts\ncms.events.subscribe('plugins', event => {\n  console.log(`Something happened to the plugins`)\n})\n```\n\nNote that the string `plugins`is equivalent to `plugins:*` or `plugins:*:*`.\n\n## Existing Events\n\n### _tinacms_\n\n| Type                     | Description                                    |\n| ------------------------ | ---------------------------------------------- |\n| `cms:enabled`            | The CMS has been enabled.                      |\n| `cms:disabled`           | The CMS has been disabled                      |\n| `sidebar:opened`         | The Sidebar has been opened                    |\n| `sidebar:closed`         | The Sidebar has been closed.                   |\n| `plugin:add:{__type}`    | A Plugin of a given `__type` has been added.   |\n| `plugin:remove:{__type}` | A Plugin of a given `__type` has been removed. |\n\n### _react-tinacms-github_\n\n| Event Name               | Decription                                                    |\n| ------------------------ | ------------------------------------------------------------- |\n| `github:error`           | An error has occurred when making requests to the GitHub API. |\n| `github:branch:checkout` | The current branch has been switched.                         |\n| `github:branch:create`   | A new branch has been created.                                |\n\n### _@tinacms/git-client_\n\n| Event Name   | Decription                   |\n| ------------ | ---------------------------- |\n| `git:commit` | A commit has been attempted. |\n\nBelow is an example of how you might subscribe to the `git:commit` event in your App. The event passed to the callback function is a [Fetch Response](https://developer.mozilla.org/en-US/docs/Web/API/Response 'Fetch Response'); you can parse the status of the commit from this to trigger various alerts or functions.\n\n**Example**\n\n    React.useEffect(() => {\n      cms.events.subscribe(\"git:commit\", function handleCommitAlerts(event) {\n        if (!event.response.ok) {\n          cms.alerts.error(\"Something went wrong! Changes weren't saved\")\n        } else {\n          cms.alerts.info(\"Content saved successfully!\")\n        }\n       })\n    }, [])\n"}},"tocItems":"- [Interface](#interface)\n- [Usage](#usage)\n  * [Dispatching Events](#dispatching-events)\n  * [Subscribing to Events](#subscribing-to-events)\n    + [Log all Events](#log-all-events)\n  * [Log when a Form Plugin is added](#log-when-a-form-plugin-is-added)\n    + [Log all Form Events](#log-all-form-events)\n    + [Log all Plugin Events](#log-all-plugin-events)\n- [Existing Events](#existing-events)\n  * [_tinacms_](#tinacms)\n  * [_react-tinacms-github_](#react-tinacms-github)\n  * [_@tinacms/git-client_](#tinacmsgit-client)","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/media","title":"Media"},"prevPage":{"slug":"/docs/plugins","title":"Plugins"}},"__N_SSG":true}