Events


The Events feature allows decoupled parts of the CMS to:

  1. Notify the rest of the system that something has happened, and
  2. React to things that happen elsewhere in the system.

Interface

interface Events {
  dispatch(event: Event): void
  subscribe(eventType: string, listener: Listener): Unsubscribe
}

interface Event {
  type: string
  // Any other data may be added to the event.
  [key: string]: any
}

type Listener = (event: Event) => void

type Unsubscribe = () => void

Usage

Dispatching Events

cms.events.dispatch({
  type: 'something-happened',
})

Subscribing to Events

The cms.events.subscribe function can be used to start listening for certain events.

cms.events.subscribe(EVENT_NAME, event => {
  // ...
})

The EVENT_NAME is a string that matches a pattern for the event name.

Checkout the tests for specific examples of how the matching happens.

Log all Events

cms.events.subscribe('*', event => {
  console.log(event)
})

Log when a Form Plugin is added

cms.events.subscribe("plugins:add:form", (event) => {
  console.log(`Added a Form called "${event.plugin.name}"`
})

Log all Form Events

cms.events.subscribe('plugins:*:form', event => {
  console.log(`Something happened to the form plugins`)
})

Log all Plugin Events

cms.events.subscribe('plugins', event => {
  console.log(`Something happened to the plugins`)
})

Note that the string pluginsis equivalent to plugins:* or plugins:*:*.

Existing Events

tinacms

TypeDescription
cms:enableThe CMS has been enabled.
cms:disableThe CMS has been disabled
sidebar:openedThe Sidebar has been opened
sidebar:closedThe Sidebar has been closed.
plugin:add:{__type}A Plugin of a given __type has been added.
plugin:remove:{__type}A Plugin of a given __type has been removed.
media:upload:startA media file upload has begun.
media:upload:successA media file was successfully uploaded.
media:upload:failureA media file upload failed.
media:list:startA call to list available media items has been made.
media:list:successThe call to list media items was successful.
media:list:failureThe call to list media items failed.
media:delete:startA media file is attempting to be deleted.
media:delete:successA media file was successfully deleted.
media:delete:failureThe attempt to delete a media file failed.
media:previewSrc:startA previewSrc is being generated for a media file.
media:previewSrc:successThe call to previewSrc successfully returned a url.
media:previewSrc:failureA previewSrc failed to be generated.

react-tinacms-github

Event NameDecription
github:errorAn error has occurred when making requests to the GitHub API.
github:branch:checkoutThe current branch has been switched.
github:branch:createA new branch has been created.

@tinacms/git-client

Event NameDecription
git:commitA commit has been attempted.

Below 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; you can parse the status of the commit from this to trigger various alerts or functions.

Example

React.useEffect(() => {
  cms.events.subscribe('git:commit', function handleCommitAlerts(event) {
    if (!event.response.ok) {
      cms.alerts.error("Something went wrong! Changes weren't saved")
    } else {
      cms.alerts.info('Content saved successfully!')
    }
  })
}, [])