Smart Fields

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

In legacy agents declaring a smart field was done in one big step.

In the new agent, the process was split into multiple steps, depending on the capabilities of the field (writing, filtering, sorting, etc.).

This was done to reduce the complexity of the code and to make it easier to understand, but also because it allows customers to reuse the same API when customizing the behavior of normal fields, and thus reduce the API surface that you need to learn.

You can find the full documentation of field customization here.

Code cheatsheet

Legacy agent	New agent
get: (record) => { ... }	"get_values": lambda records : ...
set: (record, value) => { ... }	.replace_field_writing(...)
filter: ({ condition, where }) => { ... }	.replace_field_operator(...) .emulate_field_operator(...) .emulate_field_filtering(...)
type: 'String'	columnType: 'String'
enums: ['foo', 'bar']	"column_type": "Enum", "enum_values": ['foo', 'bar']
reference: 'otherCollection.id'	Use a smart relationship

Do you still need a computed field?

Smart fields were a powerful tool, but they were also a performance bottleneck.

In the new agent, we have introduced two new concepts that can replace many of the use cases of smart fields:

If you were using a smart field to move a field from one collection to another or to create a link to another record in the UI, you can likely use one of these much simpler solutions.

• Moving fields

• Relationships

Steps

Step 1: Implement a read-only version of the field

Computed fields in the new agent are declared by calling the add_field function on the appropriate collection.

Many changes have been made to the API.

Dependencies are explicit

You will notice that a new dependencies property is required when declaring a computed field.

It is an array of field names that tells Forest Admin which fields the get_values() function depends on. Unlike the legacy agent, the new agent will not automatically fetch the whole record.

You can fetch data from relations and fetch data from other computed fields.

Fields now work in batches

Even if it adds some complexity, exposing a batch API to our customers is a much better solution for performance.

The get function is now called get_values: it no longer takes a single record as its first argument, but an array of records, and must return an array of values, one for each record, in the same order.

Other changes

There are other minor changes to the API:

• the type property was renamed to column_type.

• The field property no longer exists. The field name is now the first argument of the add_field function.

• The reference property no longer exists: use the smart relationships guide.

• The enums property was renamed to enum_values.

Example

In the following example, we will port a field that fetches the full address of a user from a third-party service.

Note that when displaying a list of records, the new agent will only make one call to your handler, and then display the results for all records, instead of making one call per record.

Before

from django_forest.utils.collection import Collection

class UsersForest(Collection):
    def load(self):
        self.fields = [
            {
                "field": "full_address",
                "type": "String",
                "get": self.get_full_address,
            }
        ]

    def get_full_address(self, obj):
        return "\n".join([
            obj.address_line_1,
            obj.address_line_2,
            obj.address_city,
            obj.address_country
        ])

After

from typing import List

from forestadmin.datasource_toolkit.context.collection_context import CollectionCustomizationContext
from forestadmin.datasource_toolkit.interfaces.records import RecordsDataAlias

def get_customer_full_address(
    records: List[RecordsDataAlias], context: CollectionCustomizationContext
):
    return [
        "\n".join(
            [
              rec["address_line_1"],
              rec["address_line_2"],
              rec["address_city"],
              rec["address_country"],
            ]
        ) for rec in records
    ]

agent.customize_collection("customer").add_field("full_address", {
    "column_type": "String",
    "dependencies": [
        "address_line_1", "address_line_2", "address_city", "address_country"
    ],
    "get_values": get_customer_full_address,
})

Step 2: Implement write handler

If you want your computed field to be writable, you will need to call the .replace_field_writing() function.

This part is very similar to the legacy agent. The API change is because this function can be used to make any field writable, not just computed fields, or to change the default writing behavior of a normal field.

Before

from django_forest.utils.collection import Collection

class UsersForest(Collection):
    def load(self):
        self.fields = [
            {
                "field": "full_address",
                "type": "String",
                "get": self.get_full_address,
                "set": self.set_full_address,
            }
        ]

    def set_full_name(self, obj, value):
        obj.address_line_1 = value.split('\n')[0]
        obj.address_line_2 = value.split('\n')[1]
        obj.address_city = value.split('\n')[2]
        obj.address_country = value.split('\n')[3]
        return obj

    def get_full_address(self, obj):
        # ...

After

from typing import Any, List

from forestadmin.datasource_toolkit.decorators.write.write_replace.write_customization_context import (
    WriteCustomizationContext,
)

def set_customer_full_address(value: Any, context: WriteCustomizationContext):
    return {
        "address_line_1": value.split('\n')[0],
        "address_line_2": value.split('\n')[1],
        "address_city": value.split('\n')[2],
        "address_country": value.split('\n')[3],
    }

agent.customize_collection("customer").add_field("full_address", {
    # ... same as before
}).replace_field_writing(
    "full_address", set_customer_full_address
)

Step 3: Implement the filters you use

Structure

Implementing filters in the new agent is done operator by operator, instead of using a single function.

This allows more fine-grained control over the behavior of each operator and makes it possible to implement only the operators you need.

Also note that unlike in the legacy agent, automatic operator replacement will be performed by the agent, so the number of operators that you need to implement to unlock all filtering is much lower.

Return value

Because the new Forest Admin agent is designed to work with multiple databases, the return value of the filter function is not a Sequelize or Mongoose condition anymore.

Instead, you'll be building a condition tree that will be translated to the appropriate database syntax by the agent.

Emulation

At the cost of performance, you can tell the agent to emulate the behavior of a given operator by calling the .emulate_field_operator() function.

Example

Before

from django.db.models import Q
from django_forest.utils.collection import Collection

class UsersForest(Collection):
    def load(self):
        self.fields = [
            {
                "field": "full_address",
                "type": "String",
                "get": self.get_full_address,
                "set": self.set_full_address,
                "filter": self.filter_full_name,
            }
        ]

    def filter_full_name(self, operator, value):
        if operator == "equal":
            return Q(...)
        elif operator == "less_than":
            return Q(...)
        # [...] all other operators

    def set_full_name(self, obj, value):
        # ...

    def get_full_address(self, obj):
        # ...

After

from typing import Any, List

from forestadmin.datasource_toolkit.context.collection_context import CollectionCustomizationContext

def full_address_operator_equal(value, context: CollectionCustomizationContext):
    pass

agent.customize_collection("customer").add_field("full_address", {
    # ... same as before
}).replace_field_writing(
    # ... same as before
).replace_field_operator(
    "full_address", "equal", full_address_operator_equal
).replace_field_operator(
    "full_address", "less_than", lambda value, context: ...

# Emulate other operators.
).emulate_field_operator(
    "full_address", "greater_than"
).emulate_field_operator(
    "full_address", "not_equal"

# [Or] Emulate all operators which are not already defined in one call.
).emulate_field_filtering("full_address")