Interface

Action

Action

Interface representing an Action in AdminBro. Look at 05-actions to see where you can use this interface.

Example Action

const action = {
  actionType: 'record',
  icon: 'View',
  isVisible: true,
  handler: async () => {...},
  component: AdminBro.bundle('./my-action-component'),
}

There are 3 kinds of actions:

  1. Resource action, which is performed for an entire resource.
  2. Record action, invoked for an record in a resource
  3. Bulk action, invoked for an set of records in a resource

...and there are 7 actions predefined in AdminBro

  1. new (resource action) - create new records in a resource
  2. list (resource action) - list all records within a resource
  3. search (resource action) - search by query string
  4. edit (record action) - update records in a resource
  5. show (record action) - show details of given record
  6. delete (record action) - delete given record
  7. bulkDelete (bulk action) - delete given records

Users can also create their own actions or override those already existing by using ResourceOptions

const AdminBroOptions = {
  resources: [{
    resource: User,
    options: {
      actions: {
        // example of overriding existing 'new' action for
        // User resource.
        new: {
          icon: 'Add'
        },
        // Example of creating a new 'myNewAction' which will be
        // a resource action available for User model
        myNewAction: {
          actionType: 'resource',
          handler: async (request, response, context) => {...}
        }
      }
    }
  }]
}

const { ACTIONS } = require('admin-bro')
// example of adding after filter for 'show' action for all resources
ACTIONS.show.after = async () => {...}

Members

'resource' | 'record' | 'bulk'

# actionType

Type of an action - could be either resource, record or bulk.

When you define a new action - it is required.

View Source admin-bro/src/backend/actions/action.interface.ts, line 286

After.<T>

# after Optional

After action hook. When it is given - it is performed on the returned, by handler function response.

You can use it to (just an idea)

  • create log of changes done in the app
  • prefetch additional data after original Handler is being performed

Creating a changelog example:

// example mongoose model
const ChangeLog = mongoose.model('ChangeLog', mongoose.Schema({
  // what action
  action: { type: String },
  // who
  userId: { type: mongoose.Types.ObjectId, ref: 'User' },
  // on which resource
  resource: { type: String },
  // was record involved (resource and recordId creates to polymorphic relation)
  recordId: { type: mongoose.Types.ObjectId },
}, { timestamps: true }))

// actual after function
const createLog = async (originalResponse, request, context) => {
  // checking if object doesn't have any errors or is a delete action
  if ((request.method === 'post'
       && originalResponse.record
       && !Object.keys(originalResponse.record.errors).length)
       || context.action.name === 'delete') {
    await ChangeLog.create({
      action: context.action.name,
      // assuming in the session we store _id of the current admin
      userId: context.currentAdmin && context.currentAdmin._id,
      resource: context.resource.id(),
      recordId: context.record && context.record.id(),
    })
  }
  return originalResponse
}

// and attaching this function to actions for all resources
const { ACTIONS } = require('admin-bro')

ACTIONS.edit.after = createLog
ACTIONS.delete.after = createLog
ACTIONS.new.after = createLog

View Source admin-bro/src/backend/actions/action.interface.ts, line 399

Before

# before Optional

Before action hook. When it is given - it is performed before the Action#handler method.

Example of hashing password before creating it:

actions: {
  new: {
    before: async (request) => {
      if(request.payload.password) {
        request.payload = {
          ...request.payload,
          encryptedPassword: await bcrypt.hash(request.payload.password, 10),
          password: undefined,
        }
      }
      return request
    },
  }
}

View Source admin-bro/src/backend/actions/action.interface.ts, line 373

string | false

# component Optional

Component which will be used to render the action. To pass the component use AdminBro.bundle method.

Action components accepts ActionProps and are rendered by the BaseActionComponent

When component is set to false then action doesn't have it's own view. Instead after clicking button it is immediately performed. Example of an action without a view is module:DeleteAction.

View Source admin-bro/src/backend/actions/action.interface.ts, line 330

string | number | Array.<(string|number)>

# containerWidth Optional

The max width of action HTML container. You can put here an actual size in px or an array wf widths, where different values will be responsible for different breakpoints. It is directly passed to action's wrapping Box component, to its width property.

Examples


// passing regular string
containerWidth: '800px'

// passing number for 100% width
containerWidth: 1

// passing values for different breakpoints
containerWidth: [1, 1/2, 1/3]

View Source admin-bro/src/backend/actions/action.interface.ts, line 468

string

# guard Optional

guard message - user will have to confirm it before executing an action.

new AdminBro({ resources: [{
  resource: Car,
  options: { actions: {
    delete: {
      guard: 'doYouReallyWantToDoThis',
    }
  }}
}]})

What you enter there goes to TranslateFunctions#translateMessage function, so in order to define the actual message you will have to specify its translation in AdminBroOptions.Locale

View Source admin-bro/src/backend/actions/action.interface.ts, line 309

ActionHandler.<T>

# handler

handler function which will be invoked by either:

If you are defining this action for a record it has to return:

// Handler of a 'record' action
handler: async (request, response, context) {
  const user = context.record
  const Cars = context._admin.findResource('Car')
  const userCar = Car.findOne(context.record.param('carId'))
  return {
    record: user.toJSON(context.currentAdmin),
  }
}

Required for new actions. For modifying already defined actions like new and edit we suggest using Action#before and Action#after hooks.

View Source admin-bro/src/backend/actions/action.interface.ts, line 344

boolean

# hideActionHeader Optional

Indicates if Action Header should be hidden. Action header consist of:

  • breadcrumbs
  • action buttons
  • action title

View Source admin-bro/src/backend/actions/action.interface.ts, line 458

string

# icon Optional

icon name for the action. Take a look Icon component, because what you put here is passed down to it.

new AdminBro({ resources: [{
  resource: Car,
  options: { actions: { edit: { icon: 'Add' } } },
}]})

View Source admin-bro/src/backend/actions/action.interface.ts, line 295

boolean | IsFunction

# isAccessible Optional

Indicates if the action can be invoked for given invocation context. You can pass a boolean or function of type IsFunction, which takes ActionContext as an argument.

You can use it as a carrier between the hooks.

Example for isVisible function which allows the user to edit cars which belongs only to her:

const canEditCars = ({ currentAdmin, record }) => {
  return currentAdmin && (
    currentAdmin.role === 'admin'
    || currentAdmin._id === record.param('ownerId')
  )
}

new AdminBro({ resources: [{
  resource: Car,
  options: { actions: { edit: { isAccessible: canEditCars } } }
}]})
See:

View Source admin-bro/src/backend/actions/action.interface.ts, line 236

boolean | IsFunction

# isVisible Optional

indicates if action should be visible for given invocation context. It also can be a simple boolean value. True by default. The most common example of usage is to hide resources from the UI. So let say we have 2 resources User and Cars:

const User = mongoose.model('User', mongoose.Schema({
  email: String,
  encryptedPassword: String,
}))
const Car = mongoose.model('Car', mongoose.Schema({
  name: String,
  ownerId: { type: mongoose.Types.ObjectId, ref: 'User' },
})

so if we want to hide Users collection, but allow people to pick user when creating cars. We can do this like this:

new AdminBro({ resources: [{
  resource: User,
  options: { actions: { list: { isVisible: false } } }
}]})

In contrast - when we use Action#isAccessible instead - user wont be able to pick car owner.

See:

View Source admin-bro/src/backend/actions/action.interface.ts, line 200

string

# name

Name of an action which is its uniq key. If you use one of list, search, edit, new, show, delete or bulkDelete you override existing actions. For all other keys you create a new action.

View Source admin-bro/src/backend/actions/action.interface.ts, line 192

boolean

# showFilter Optional

if filter should be visible on the sidebar. Only for resource actions

Example of creating new resource action with filter

new AdminBro({ resources: [{
  resource: Car,
  options: { actions: {
    newAction: {
      type: 'resource',
      showFilter: true,
    }
  }}
}]})

View Source admin-bro/src/backend/actions/action.interface.ts, line 266

boolean

# showInDrawer Optional

Indicates if given action should be seen in a drawer or in a full screen. Default to false

View Source admin-bro/src/backend/actions/action.interface.ts, line 452

Type Definitions

object

# ActionContext

Execution context for an action. It is passed to the Action#handler, Action#before and Action#after functions.

Apart from the properties defined below it also extends TranslateFunctions. So you can use i.e. context.translateMessage(...) and others...

Properties:
Name Type Attributes Description
{...} TranslateFunction

all functions from TranslateFunctions interface.

_admin AdminBro

current instance of AdminBro. You may use it to fetch other Resources by their names:

resource BaseResource

Resource on which action has been invoked. Null for dashboard handler.

record BaseRecord <optional>

Record on which action has been invoked (only for actionType === 'record')

records Array.<BaseRecord> <optional>

Records on which action has been invoked (only for actionType === 'bulk')

h ViewHelpers

view helpers

action ActionDecorator

Object of currently invoked function. Not present for dashboard action

currentAdmin CurrentAdmin <optional>

Currently logged in admin

{...} any

Any custom property which you can add to context

View Source admin-bro/src/backend/actions/action.interface.ts, line 12

# async ActionHandler(request, response, context) → {Promise.<T>}

Type of a handler function. It has to return response compatible with ActionResponse, BulkActionResponse or RecordActionResponse

Parameters:
Name Type Description
request ActionRequest
response any
context ActionContext

View Source admin-bro/src/backend/actions/action.interface.ts, line 93

Promise.<T>
object

# ActionRequest

ActionRequest

Properties:
Name Type Attributes Description
params object

parameters passed in an URL

resourceId string

Id of current resource

recordId string <optional>

Id of current record (in case of record action)

recordIds string <optional>

Id of selected records (in case of bulk action) divided by commas

action string

Name of an action

query string <optional>

an optional search query string (for search resource action)

{...} any
payload Record.<string, any> <optional>

POST data passed to the backend

query Record.<string, any> <optional>

Elements of query string

method 'post' | 'get'

HTTP method

View Source admin-bro/src/backend/actions/action.interface.ts, line 44

object

# ActionResponse

Base response for all actions

Properties:
Name Type Attributes Description
notice NoticeMessage <optional>

Notice message which should be presented to the end user after showing the action

redirectUrl string <optional>

redirect path

{...} any

Any other custom parameter

View Source admin-bro/src/backend/actions/action.interface.ts, line 60

# async After(response, request, context)

Type of an after hook action.

Parameters:
Name Type Description
response T

Response returned by the default ActionHandler

request ActionRequest

Original request which has been sent to ActionHandler

context ActionContext

Invocation context

View Source admin-bro/src/backend/actions/action.interface.ts, line 117

# async Before(request, context) → {Promise.<ActionRequest>}

Before action hook. When it is given - it is performed before the ActionHandler method.

Parameters:
Name Type Description
request ActionRequest

Request object

context ActionContext

Invocation context

View Source admin-bro/src/backend/actions/action.interface.ts, line 106

Promise.<ActionRequest>
object

# BulkActionResponse

Required response of a Record action. Extends ActionResponse

Properties:
Name Type Description
records Array.<RecordJSON>

Array of RecordJSON objects.

View Source admin-bro/src/backend/actions/action.interface.ts, line 85

# IsFunction(context)

Defines the type of Action#isAccessible and Action#isVisible functions

Parameters:
Name Type Description
context ActionContext

View Source admin-bro/src/backend/actions/action.interface.ts, line 69

object

# RecordActionResponse

Required response of a Record action. Extends ActionResponse

Properties:
Name Type Description
record RecordJSON

Record object.

View Source admin-bro/src/backend/actions/action.interface.ts, line 77