Ribbon & Action Menus

Developer guide for the Enezaframework. Part of the Developer documentation. For a step-by-step recipe, see Adding Ribbon Tabs, Groups & Menus.

The record ribbon is driven by a ribbon profile. A profile is defined by the list view, passed to the detail page as a short profile key, and resolved on the server into tabs, groups, buttons, dropdowns, related-record workspaces and inline panels.

This guide covers:

1. What Changed
2. Quick Start
3. Tabs, Groups and Menu Items
4. Menu Kinds
5. Related Record Menus
6. Business Actions
7. List-Context Menus
8. Permissions and Entity Overrides
9. Database Overlay
10. Backward Compatibility
11. Troubleshooting

What Changed

Every generic record page now supports:

Additional tabs (for example Manage or Reports) are added by the profile. The existing detail action bar remains in place, including the workflow dropdown. Report screens in enezareporting are not changed.

The important rule is:

Define the profile once on the list view. The list sends ?ribbon_profile=<key> to detail URLs; code and optional database overlays are resolved by the framework.

Quick Start

from enezaframework.ribbon import (
    RibbonMenuItemSpec,
    RibbonProfileSpec,
    RibbonTabSpec,
)
from enezaframework.views import BaseDetailView, BaseListView
from enezaframework.utils import auto_url_register

VENDOR_PROFILE = RibbonProfileSpec(
    key="accountpayable.vendor",
    name="Vendor",
    detail_tabs=[
        RibbonTabSpec(key="manage", label="Manage", order=20),
    ],
    menus=[
        RibbonMenuItemSpec(
            code="bank-details",
            label="Bank Details",
            icon="building",
            tab="manage",
            group="Banking",
            kind="related",
            display_mode="inline",
            target_kind="list",
            target_model="vendorbankaccount",
            parent_lookup="vendor",
            relation_name="bank_accounts",
        ),
    ],
)


@auto_url_register
class VendorListView(BaseListView):
    model = VendorTable

    def get_ribbon_profile(self):
        return VENDOR_PROFILE

    def set_list_fields(self):
        return ["code", "name"]

    def set_search_fields(self):
        return ["code", "name"]


@auto_url_register
class VendorDetailView(BaseDetailView):
    model = VendorTable
    default_ribbon_profile = "accountpayable.vendor"

When a row opens the detail page, the framework appends the profile key automatically. Direct detail links use default_ribbon_profile.

The profile may also be declared as a class attribute:

class VendorListView(BaseListView):
    ribbon_profile = VENDOR_PROFILE

get_ribbon_profile() is the recommended hook when the profile depends on the request.

Tabs, Groups and Menu Items

RibbonProfileSpec

RibbonTabSpec

key, label, context (list, detail or both) and order. icon is optional.

RibbonMenuItemSpec

Menu code may contain letters, numbers, underscores and hyphens.

Menu Kinds

Action

Runs a registered BaseAction URL. The framework appends return_url, the profile key and the active tab so the user returns to the same context.

RibbonMenuItemSpec(
    code="put-on-hold",
    label="Put on Hold",
    tab="options",
    kind="action",
    url_name="vendor_put_on_hold",  # resolves vendor_put_on_hold_action
    http_method="POST",
    confirm_message="Put this vendor on hold?",
)

Link

RibbonMenuItemSpec(
    code="open-website",
    label="Website",
    kind="link",
    url_name="accountpayable:vendor_website",  # or a full URL name
    display_mode="full_page",
)

Dropdown

RibbonMenuItemSpec(
    code="more",
    label="More",
    kind="dropdown",
    children=(
        RibbonMenuItemSpec(code="audit", label="Audit", kind="link", url_name="..."),
        RibbonMenuItemSpec(code="archive", label="Archive", kind="action", url_name="..."),
    ),
)

Only one dropdown level is supported.

Separator

RibbonMenuItemSpec(code="sep-1", label="", kind="separator")

Related Record Menus

A related menu targets another record page.

RibbonMenuItemSpec(
    code="bank-details",
    label="Bank Details",
    tab="manage",
    group="Banking",
    kind="related",
    target_kind="list",
    target_app_label="accountpayable",
    target_model="vendorbankaccount",
    parent_lookup="vendor",
    display_mode="inline",
)

display_mode

target_kind

For list/workspace menus, the framework adds the parent record identity to the target URL and filters the target list when parent_lookup is configured. For inline menus, the existing inline views are reused and the parent context is passed through main_object_pk.

Inline mode and full templates

A vendor bank-account menu can use display_mode="inline" to reuse the inline views. The inline list, detail, create and delete behavior stays the same as a normal inline section.

If the related records need the full list workspace (filters, paging, local New/Edit/Delete), use display_mode="workspace". The related record list opens inside #detail-container; its detail, edit and create views stay in the same workspace, and Back returns to the parent record with the Manage tab active.

Business Actions

BaseAction remains the execution contract. A menu only points at the action URL; the action view keeps its own business logic and permission checks.

from enezaframework.views import BaseAction

@auto_url_register
class VendorPutOnHoldAction(BaseAction):
    model = VendorTable

    def process_action(self, pk):
        vendor = VendorTable.objects.get(pk=pk)
        vendor.status = "on_hold"
        vendor.save()

The framework passes return_url, ribbon_profile and ribbon_tab to the action. If no safe return URL is supplied, BaseAction redirects to the record detail as before.

List-Context Menus

Set context="list" to add a menu to the list ribbon. Such menus act on exactly one selected row. The framework attaches the selected row’s resolved action URL to the row and enables the ribbon item only when one row is selected.

RibbonMenuItemSpec(
    code="put-on-hold",
    label="Put on Hold",
    context="list",
    tab="options",
    kind="action",
    url_name="vendor_put_on_hold",
)

Menus with requires_object=False can be static links and do not depend on selection.

Permissions and Entity Overrides

Menus may declare Django permissions and/or group names:

RibbonMenuItemSpec(
    code="bank-details",
    label="Bank Details",
    permissions=("accountpayable.view_vendorbankaccount",),
    groups=("Credit Control",),
)

All listed permissions must be held; if groups are supplied, the user must belong to at least one. Hidden items are not rendered. The action view must still enforce access because a user can call the URL directly.

Developer code profiles apply to every entity. The optional database overlay can add an entity-specific override (see below).

Database Overlay

The database overlay is optional. It is useful when a deployment needs to add or override menus without a code release. The models live in enezaframework/models/ribbon.py:

Resolution order:

1. Base get_ribbon_tabs().
2. Code profile.
3. Global DB overlay.
4. Entity-specific DB overlay.

An item with the same code in a later layer replaces the earlier item. If no profile resolves, the base ribbon is rendered unchanged.

There is intentionally no in-app setup screen for these models in this iteration. Create records through the ORM, shell or Django admin if the models are registered in the project.

Backward Compatibility

The following continue to work unchanged:

• get_ribbon_tabs() overrides.
• action_list and print_actions in the detail action bar.
• main_actions and the workflow dropdown in navactions.html.
• WorkflowMixin.
• Setup, journal, parameter, attachment and reporting screens.

If a view does not define a profile, no profile query parameter is added and the base tabs are used. A missing or invalid profile key falls back to the detail view’s default profile, then the base tabs.

Troubleshooting