Defining Lenses

Learn how to define lenses in Djing.

While similar to filters, Djing lenses allow you to fully customize the underlying resource Django query. For example, you may want to list of all your application’s users sorted by their total lifetime revenue:

Creating such a list may require you to join to additional tables and perform aggregate functions within the query. If it sounds complicated, don’t worry - this is exactly the type of situation lenses are designed to solve.

Overview

To create a lens, you may use the djing:lens CLI command. By default, Djing will place newly generated lenses in the djing_admin/app/Djing/Lenses directory:

commander djing:lens MostValuableUsers

Each lens generated by Djing contains several methods. However, the two methods we are currently concerned with are the query and fields methods. The query method is responsible for building the Eloquent query that is needed to retrieve the desired data, while the fields method returns an array of fields that should be displayed when viewing the lens.

To learn more, let’s take a look at a complete lens definition that displays users and their lifetime revenue. As you can see in the example below, the query method will take advantage of the methods offered by the LensRequest in order to instruct Djing to also apply any selected filters and ordering constraints to the query:

djing_admin/app/Djing/Lenses/MostValuableUsers.py

from djing.core.Fields.ID import ID
from djing.core.Fields.Text import Text
from djing.core.Http.Requests.DjingRequest import DjingRequest
from djing.core.Http.Requests.LensRequest import LensRequest
from djing.core.Lenses.Lens import Lens
from django.db.models import QuerySet

from djing_admin.app.Djing.Actions.UpgradeUserAction import UpgradeUserAction
from djing_admin.app.Djing.Filters.UsernameFilter import UsernameFilter
from djing_admin.app.Djing.Metrics.ValueMetric import ValueMetric


class MostValuableUsers(Lens):
    search = [
        "id",
    ]

    @classmethod
    def query(cls, request: LensRequest, query: QuerySet):
        # you can filter users by custom query
        return query.filter(is_active=True).order_by('-username')

    def fields(self, request: DjingRequest):
        return [
            ID.make("ID").sortable(),
            Text.make("Username", "username").sortable(),
            Text.make("Email Address", "email_address").sortable(),
        ]

    def cards(self, request: DjingRequest):
        return []

    def filters(self, request: DjingRequest):
        return []

    def actions(self, request: DjingRequest):
        return super().actions()

    def uri_key(self):
        return "most-valuable-users-lens"

As you can see in the example above, the query method has full control of the Django query used to retrieve the lens data. The fields method may leverage any of Djing’s fields in order to appropriately display the data retrieved by the query.

Lens Filters

Each Djing lens also contains a filters method. This method allows you to attach any of your existing filters to the lens:

djing_admin/app/Djing/Lenses/MostValuableUsers.py

from djing.core.Http.Requests.DjingRequest import DjingRequest
from djing.core.Lenses.Lens import Lens
from djing_admin.app.Djing.Filters.UserType import UserType

class MostValuableUsers(Lens):
    # ...

    def filters(self, request: DjingRequest):
        return [
            UserType(),
        ]

Lens Actions

Each Djing lens also contains an actions method. This method allows you to attach any of your existing actions to the lens:

djing_admin/app/Djing/Lenses/MostValuableUsers.py

from djing.core.Http.Requests.DjingRequest import DjingRequest
from djing.core.Lenses.Lens import Lens
from djing_admin.app.Djing.Filters.UserType import UserType
from djing_admin.app.Djing.Actions.UpgradeUserAction import UpgradeUserAction

class MostValuableUsers(Lens):
    # ...

    def actions(self, request: DjingRequest):
        return [
            *super().actions(request),
            UpgradeUserAction(),
        ]

Lens Metrics

Each Djing lens also contains a cards method. This method allows you to attach any of your existing metrics to the lens:

djing_admin/app/Djing/Lenses/MostValuableUsers.py

from djing.core.Http.Requests.DjingRequest import DjingRequest
from djing.core.Lenses.Lens import Lens
from djing_admin.app.Djing.Filters.UserType import UserType
from djing_admin.app.Djing.Actions.ValueMetric import ValueMetric

class MostValuableUsers(Lens):
    # ...

    def cards(self, request: DjingRequest):
        return [
            ValueMetric(),
        ]