Helper Functions

Helper functions are functions usually meant to be used in templates to perform some specific tasks. They are defined in the helpers.py file of the extension.

List of Helper Functions

build_url_from_params(endpoint, url_params, row)

Build an action URL based on the endpoint and URL parameters.

The url_params might contain values like $id, $type, etc. We need to replace them with the actual values from the row

PARAMETER	DESCRIPTION
endpoint	The endpoint to build the URL for TYPE: str
url_params	The URL parameters to build the URL for TYPE: dict[str, Any]
row	The row to build the URL for TYPE: dict[str, Any]

Source code in ckanext/ap_main/helpers.py

@helper
def build_url_from_params(
    endpoint: str, url_params: dict[str, Any], row: dict[str, Any]
) -> str:
    """Build an action URL based on the endpoint and URL parameters.

    The url_params might contain values like $id, $type, etc.
    We need to replace them with the actual values from the row

    Args:
        endpoint: The endpoint to build the URL for
        url_params: The URL parameters to build the URL for
        row: The row to build the URL for
    """
    params = url_params.copy()

    for key, value in params.items():
        if value.startswith("$"):
            params[key] = row[value[1:]]

    return tk.url_for(endpoint, **params)

dumps(value)

Convert a value to a JSON string.

PARAMETER	DESCRIPTION
value	The value to convert to a JSON string TYPE: Any

RETURNS	DESCRIPTION
str	The JSON string

Source code in ckanext/ap_main/helpers.py

@helper
def dumps(value: Any) -> str:
    """Convert a value to a JSON string.

    Args:
        value: The value to convert to a JSON string

    Returns:
        The JSON string
    """
    return json.dumps(value)

generate_page_unique_class()

Build a unique css class for each page.

RETURNS	DESCRIPTION
str	A unique css class for the current page

Source code in ckanext/ap_main/helpers.py

@helper
def generate_page_unique_class() -> str:
    """Build a unique css class for each page.

    Returns:
        A unique css class for the current page
    """
    return tk.h.ap_munge_string(f"ap-{tk.request.endpoint}")

get_config_sections()

Prepare a config section structure for render.

RETURNS	DESCRIPTION
list[SectionConfig]	A list of sections with their config items

Source code in ckanext/ap_main/helpers.py

@helper
def get_config_sections() -> list[SectionConfig]:
    """Prepare a config section structure for render.

    Returns:
        A list of sections with their config items
    """
    config_sections = {}

    for _, section in ap_utils.collect_sections_signal.send():
        config_sections.setdefault(
            section["name"], {"name": section["name"], "configs": []}
        )
        config_sections[section["name"]]["configs"].extend(section["configs"])

    sections = list(config_sections.values())
    sections.sort(key=lambda x: x["name"])

    return sections

get_toolbar_structure()

Prepare a toolbar structure for render.

An extension can register its own toolbar buttons by implementing the register_toolbar_button method in the IAdminPanel interface.

RETURNS	DESCRIPTION
list[ToolbarButton]	A list of toolbar button objects

Source code in ckanext/ap_main/helpers.py

@helper
@Cache(duration=900)  # cache for 15 minutes
def get_toolbar_structure() -> list[ToolbarButton]:
    """Prepare a toolbar structure for render.

    An extension can register its own toolbar buttons by implementing the
    `register_toolbar_button` method in the `IAdminPanel` interface.

    Returns:
        A list of toolbar button objects
    """
    configuration_subitems = [
        ToolbarButton(
            label=section["name"],
            subitems=[
                ToolbarButton(
                    label=config_item["name"], url=tk.url_for(config_item["blueprint"])
                )
                for config_item in section["configs"]
            ],
        )
        for section in get_config_sections()
    ]

    default_structure = [
        ToolbarButton(
            label=tk._("Content"),
            icon="fa fa-folder",
            url=tk.url_for("ap_content.list"),
        ),
        ToolbarButton(
            label=tk._("Configuration"),
            icon="fa fa-gear",
            url=tk.url_for("ap_config_list.index"),
            subitems=configuration_subitems,
        ),
        ToolbarButton(
            label=tk._("Users"),
            icon="fa fa-user-friends",
            url=tk.url_for("ap_user.list"),
            subitems=[
                ToolbarButton(
                    label=tk._("Add user"),
                    url=tk.url_for("ap_user.create"),
                    icon="fa fa-user-plus",
                )
            ],
        ),
        ToolbarButton(
            label=tk._("Reports"),
            icon="fa fa-chart-bar",
            subitems=[],
        ),
        ToolbarButton(
            icon="fa fa-user",
            url=tk.url_for("user.read", id=tk.current_user.name),
            label=tk.current_user.display_name,
            attributes={"title": tk._("View profile"), "class": "ms-lg-auto"},
        ),
        ToolbarButton(
            icon="fa fa-gavel",
            url=tk.url_for("admin.index"),
            aria_label=tk._("Old admin"),
            attributes={"title": tk._("Old admin")},
        ),
        ToolbarButton(
            icon="fa fa-tachometer",
            url=tk.url_for("dashboard.datasets"),
            aria_label=tk._("View dashboard"),
            attributes={"title": tk._("View dashboard")},
        ),
        ToolbarButton(
            icon="fa fa-cog",
            url=tk.url_for("user.edit", id=tk.current_user.name),
            aria_label=tk._("Profile settings"),
            attributes={"title": tk._("Profile settings")},
        ),
    ]

    if tk.h.ap_show_toolbar_theme_switcher():
        default_structure.append(
            ToolbarButton(
                icon="fa-solid fa-moon",
                aria_label=tk._("Theme Switcher"),
                url="#",
                attributes={
                    "title": tk._("Theme Switcher"),
                    "data-module": "ap-theme-switcher",
                    "class": "ap-theme-switcher",
                },
            ),
        )

    # place logout button at the end
    default_structure.append(
        ToolbarButton(
            icon="fa fa-sign-out",
            url=tk.url_for("user.logout"),
            aria_label=tk._("Log out"),
            attributes={"title": tk._("Log out")},
        )
    )

    for plugin in reversed(list(p.PluginImplementations(IAdminPanel))):
        default_structure = plugin.register_toolbar_button(default_structure)

    return default_structure

munge_string(value)

Munge a string using CKAN's munge_name function.

PARAMETER	DESCRIPTION
value	The string to munge TYPE: str

RETURNS	DESCRIPTION
str	The munged string

Source code in ckanext/ap_main/helpers.py

@helper
def munge_string(value: str) -> str:
    """Munge a string using CKAN's munge_name function.

    Args:
        value: The string to munge

    Returns:
        The munged string
    """
    return munge.munge_name(value)

show_toolbar_theme_switcher()

Check if the toolbar theme switcher should be displayed.

Source code in ckanext/ap_main/helpers.py

@helper
def show_toolbar_theme_switcher() -> bool:
    """Check if the toolbar theme switcher should be displayed."""
    return ap_config.show_toolbar_theme_switcher()

user_add_role_options()

Return a list of options for a user add form.

RETURNS	DESCRIPTION
list[dict[str, str | int]]	A list of options for a user add form

Source code in ckanext/ap_main/helpers.py

@helper
def user_add_role_options() -> list[dict[str, str | int]]:
    """Return a list of options for a user add form.

    Returns:
        A list of options for a user add form
    """
    return [
        {"value": "user", "text": "Regular user"},
        {"value": "sysadmin", "text": "Sysadmin"},
    ]