Python Developer Guide
Other documentationsDemoCommunityGitHub
  • Forest Admin
  • Getting started
    • How it works
    • Quick start
      • Flask
      • Django
    • Create your agent
    • Troubleshooting
    • Migrating legacy agents
      • Pre-requisites
      • Recommendations
      • Migration steps
      • Code transformations
        • API Charts
        • Live Queries
        • Smart Charts
        • Route overrides
        • Smart Actions
        • Smart Fields
        • Smart Relationships
        • Smart Segments
  • Data Sources
    • Getting Started
      • Collection selection
      • Naming conflicts
      • Query interface and Native Queries
        • Fields and projections
        • Filters
        • Aggregations
    • Provided data sources
      • SQLAlchemy
      • Django
        • Polymorphic relationships
    • Write your own
      • Translation strategy
        • Structure declaration
        • Capabilities declaration
        • Read implementation
        • Write implementation
        • Intra-data source Relationships
      • Contribute
  • Agent customization
    • Getting Started
    • Actions
      • Scope and context
      • Result builder
      • Static Forms
      • Widgets in Forms
      • Dynamic Forms
      • Form layout customization
      • Related data invalidation
    • Charts
      • Value
      • Objective
      • Percentage
      • Distribution
      • Leaderboard
      • Time-based
    • Fields
      • Add fields
      • Move, rename and remove fields
      • Override binary field mode
      • Override writing behavior
      • Override filtering behavior
      • Override sorting behavior
      • Validation
    • Hooks
      • Collection hook
      • Collection override
    • Pagination
    • Plugins
      • Write your own
    • Relationships
      • To a single record
      • To multiple records
      • Computed foreign keys
      • Under the hood
    • Search
    • Segments
  • Frontend customization
    • Smart Charts
      • Create a table chart
      • Create a bar chart
      • Create a cohort chart
      • Create a density map
    • Smart Views
      • Create a Map view
      • Create a Calendar view
      • Create a Shipping view
      • Create a Gallery view
      • Create a custom tinder-like validation view
      • Create a custom moderation view
  • Deploying to production
    • Environments
      • Deploy on AWS
      • Deploy on Heroku
      • Deploy on GCP
      • Deploy on Ubuntu
    • Development workflow
    • Using branches
    • Deploying your changes
    • Forest Admin CLI commands
      • init
      • login
      • branch
      • switch
      • set-origin
      • push
      • environments:create
      • environments:reset
      • deploy
  • Under the hood
    • .forestadmin-schema.json
    • Data Model
      • Typing
      • Relationships
    • Security & Privacy
Powered by GitBook
On this page
  • The context object
  • Example 1: Getting data from the selected records
  • Example 2: Updating a field of the selected record
  • Example 3: Coding any business logic

Was this helpful?

  1. Agent customization
  2. Actions

Scope and context

PreviousActionsNextResult builder

Last updated 7 months ago

Was this helpful?

This is the official documentation of the forestadmin-agent-django and forestadmin-agent-flask Python agents.

Actions can have 3 different scopes: Single, Bulk, and Global.

The scope of an action defines how it can be triggered and which records it will target.

-
Single
Bulk
Global

Targeted records

One at a time

All selected and matching the current segment / search

Your choice among all matching the current segment / search

Can be triggered from the List View

When a single record is selected

When one or more records are selected

✅

Can be triggered from the Details View or Summary View

✅

✅

🚫

The context object

The context object is central to writing Actions controllers in Forest Admin.

It is the bridge between all the data that your agent has access to and the action's execution. It is passed to the execute function as the first argument and provides access to the following properties:

  • get_record(field_names) (or get_records(field_names) for Bulk and Global Actions)

  • get_record_id() (or get_record_ids() for Bulk and Global Actions)

  • collection the collection on which the action is declared, which can be queried using the .

  • datasource the composite data source who contains all your collections, which can be queried using the

  • filter a filter that can be used to query the collection, and which is based on action scope and the list of selected records.

  • caller an object containing information about the user who is performing the action (including email, username, timezone, team, role …)

  • has_field_changed(field_name) the name of the field who has changed in the UI.

changed_field was deprecated in favor of has_field_changed(field_name) starting from forestadmin-datasource-toolkit==1.0.0-beta14.

Example 1: Getting data from the selected records

We can simply use the get_record(field_names) method to get any column from the selected record or a relation.

from typing import Union
from forestadmin.datasource_toolkit.decorators.action.result_builder import ResultBuilder
from forestadmin.datasource_toolkit.decorators.action.context.single import ActionContextSingle
from forestadmin.datasource_toolkit.interfaces.actions import ActionResult

async def execute(
    context: ActionContextSingle, result_builder: ResultBuilder
) -> Union[None, ActionResult]:
  record = await context.get_record(['name'])
  if record['name'] === 'John':
      print("hi John")
  else
      print("You are not John!")

agent.customize_collection("User").add_action("Call me John in the server logs", {
    "scope": "Single",
    "execute": execute,
})

Example 2: Updating a field of the selected record

For simple queries, use context.collection and context.filter to query the collection.

from typing import Union
from forestadmin.datasource_toolkit.decorators.action.result_builder import ResultBuilder
from forestadmin.datasource_toolkit.decorators.action.context.single import ActionContextSingle
from forestadmin.datasource_toolkit.interfaces.actions import ActionResult

async def execute(
    context: ActionContextSingle, result_builder: ResultBuilder
) -> Union[None, ActionResult]:
    await context.collection.update(context.filter, {"name": "foo"})

agent.customize_collection("User").add_action("Mark as live", {
    "scope": "Single",
    "execute": execute,
})

Example 3: Coding any business logic

Forest Admin does not impose any restriction on the handler: you are free to write the execute handler to fit your use case.

You are free to call external APIs, query your database, or perform any work in action handlers.

from typing import Union
from forestadmin.datasource_toolkit.decorators.action.result_builder import ResultBuilder
from forestadmin.datasource_toolkit.decorators.action.context.single import ActionContextSingle

import requests

async def execute(
    context: ActionContextSingle, result_builder: ResultBuilder
) -> Union[None, ActionResult]:
    res = requests.get("http://my-api.com/mark-as-live")

agent.customize_collection("User").add_action("Mark as live", {
    "scope": "Single",
    "execute": execute,
})

Those are instances of objects from the .

Forest Admin Query Interface
Forest Admin Query Interface
Forest Admin Query Interface
See an example of usage