This is an internal documentation. There is a good chance you’re looking for something else. See Disclaimer.

Custom Actions

Custom actions are independent applications, tocco-apps, that can be executed in a modal window, as fullscreen actions or standalone (e.g. old client). The API should be consistent and is explained here.

Action package

Create a new package for your action in the actions folder:

yarn plop Package

The src/main.js is the entry point of the action.

Input / PropTypes

Define the input prop types for the action.

Note

The appContext prop type, which has been added automatically, can be removed for actions.

Example:

src/main.js
import PropTypes from 'prop-types'
import {selection} from 'tocco-app-extensions'
import {navigationStrategy} from 'tocco-util'

const EXTERNAL_EVENTS = ['onError', 'onCancel', 'onSuccess', 'emitAction']


const initApp = (...) => {
  ...
}

...

const ExampleActionApp = props => {
  ...
}

ExampleActionApp.propTypes = {
    selection: selection.propType.isRequired,
    actionProperties: PropTypes.shape({
        someProperty: PropTypes.string.isRequired
    }),
    context: PropTypes.shape({}),
    navigationStrategy: navigationStrategy.propTypes.isRequired,
    ...EXTERNAL_EVENTS.reduce((propTypes, event) => {
      propTypes[event] = PropTypes.func
      return propTypes
    }, {}),
}

Name

Description

Example

selection

Selected entities. Can either be an array of keys (type = id) or a query.

The selection object will be passed automatically to the action.

keys

{
  "count": 2,
  "entityName": "User",
  "ids": [
    "11081",
    "11092"
  ],
  "length": 2,
  "type": "ID"
}

query

{
  "count": 77,
  "entityName": "User",
  "query": {
    "filter": ["user_active"],
    "where": "(fulltext(\"Tocco\") or fulltext(\"Tocco*\"))",
    "hasUserChanges": true
    },
  "type": "QUERY"
}

actionProperties

Can be passed from the form definition to the action.

actionProperties

{
  "widgetKey": "12",
  "eventKey": "2"
}

context

Can be passed by the app calling the action to provide some context information.

As of now the viewName and formName are passed. But this object can be extended as needed.

entity-list

{
  "viewName": "list",
  "formName": "UserSearch"
}

entity-detail

{
  "viewName": "detail",
  "formName": "UserSearch"
}

navigationStrategy

An object containing utils to add navigation functionality. See Navigation Strategy on Gitlab for more details.

app-extensions

If you need to communicate to the outside app, the packages actionEmitter, externalEvents and notification from app-extensions will probably be useful to you.

See “addToStore” section for a list of all pluggable app-extensions.

Add all the needed extensions to your store in main.js.

Example:

src/main.js
import {appFactory, actionEmitter, externalEvents, notification} from 'tocco-app-extensions'

const packageName = 'example-action'
const EXTERNAL_EVENTS = ['onSuccess', 'emitAction']

const initApp = (...) => {
  const content = <div />

  const store = appFactory.createStore(reducers, sagas, input, packageName)
  actionEmitter.addToStore(store, state => state.input.emitAction)
  notification.addToStore(store, false)
  externalEvents.addToStore(store, state => appFactory.getEvents(EXTERNAL_EVENTS, state.input))

  return appFactory.createApp(packageName, content, store, {
    input,
    events,
    actions: [],
    publicPath,
    textResourceModules: ['component', 'common', packageName]
  })
}

Warning

Notifications will not be visible when starting the action itself. They are only visible inside the admin.

Callback Events

The action get invoked with callback functions:

Name

Params object

onSuccess

message {string} optional string that is shown in an successful info box. remoteEvents {array} List of remote events Remote Events

onError

message {string} optional string that is shown in an error info box.

onCancel

Remote Events

Indicates what changed within the execution of an action. This helps the executing app to e.g. refresh or redirect. At the moment a remote event consists of one of three types and the affected entities.

Types: ‘entity-create-event’, ‘entity-delete-event’, ‘entity-update-event’

{
 "type": "entity-update-event",
 "payload": {
  "entities": [
     {"entityName": "User", "key": "1"}
    ]
  }
}