Hooks Reference

This document is for a version of Craft CMS that is no longer supported. Please refer to the latest version →

Craft provides several hooks that give plugins the opportunity to get involved in various areas of the system.

See hooks-and-events for an explanation of how hooks work in Craft, and how they differ from events.

# General Hooks

# `addRichTextLinkOptions`

Called by: Craft\RichTextFieldType::getInputHtml() (opens new window)
Return: An array of additional options that should be available to Rich Text fields’ Link menus.

Gives plugins a chance to add additional options to Rich Text fields’ Link menus.

public function addRichTextLinkOptions()
{
    return array(
        array(
            'optionTitle' => Craft::t('Link to a product'),
            'elementType' => 'Commerce_Product',
        ),
    );
}

Each sub-array can contain the following keys:

'optionTitle' (required) – The user-facing option label
'elementType' (required) – The element type class that the option represents
'sources' (optional) – An array of source keys (matching the keys returned by the element type’s Craft\BaseElementType::getSources() (opens new window) method) which the element selector modal should be restricted to
'criteria' (optional) – Any element criteria params that should be applied to filter which elements can be selected
'storageKey' (optional) – The localStorage key that should be used to store the element selector modal state (defaults to RichTextFieldType.LinkTo[ElementType])

# `addTwigExtension`

Called by: Craft\TemplatesService::getTwig() (opens new window), Craft\TemplatesService::onPluginsLoaded() (opens new window)
Return: A new \Twig_Extension (opens new window) object

Gives plugins a chance to add a new Twig extension (opens new window).

public function addTwigExtension()
{
    Craft::import('plugins.cocktailrecipes.twigextensions.CocktailRecipesTwigExtension');
    return new CocktailRecipesTwigExtension();
}

# `addUserAdministrationOptions`

Called by: Craft\UsersController::actionEditUser() (opens new window)
Return: An array of additional administration options for the Edit User page.

Gives plugins a chance to add additional administration options to the Edit User page, which will show up when clicking on the gear icon menu at the top-right of the page.

The hook should return an array where each item is a sub-array with the following keys:

'label' – The user-facing option label
'action' – The controller action that should get loaded when the option is selected (optional)
'id' – The option’s id attribute value (optional)

If you include the 'action' key, the corresponding controller action can expect to find a userId POST parameter identifying the ID of the user that was being edited.

public function addUserAdministrationOptions(UserModel $user)
{
    if (!$user->isCurrent()) {
        return array(
            array(
                'label' => Craft::t('Pull finger'),
                'action' => 'fartbook/pullFinger'
            ),
        );
    }
}

# `getResourcePath`

Called by: Craft\ResourcesService::getResourcePath() (opens new window)
Return: A string identifying the server path to the requested resource, or null if your plugin isn’t sure.

Gives plugins a chance to map an incoming resource request’s path with the path to an actual file on the server.

public function getResourcePath($path)
{
    // Does this path start with "myplugin/"?
    if (strncmp($path, 'myplugin/', 9) == 0) {
        // Return the path to the file in craft/storage/
        return craft()->path->getStoragePath().'myplugin/'.substr($path, 9);
    }
}

# `modifyCpNav`

Called by: Craft\CpVariable::nav() (opens new window)

Gives plugins a chance to modify the control panel navigation.

public function modifyCpNav(&$nav)
{
    if (craft()->userSession->isAdmin()) {
        $nav['utils'] = array('label' => 'Utils', 'url' => 'utils');
    }
}

The config arrays can be set to the following:

A string representing the label of the nav item. (The array key will be used to generate the URL.)
An array with 'label' and 'url' keys, if you want to define the URL explicitly.

# `registerCachePaths`

Called by: Craft\ClearCachesTool::performAction() (opens new window)
Return: An array where the keys are paths and the values are the labels.

Gives plugins a chance to register new cache paths for the Clear Caches tool.

public function registerCachePaths()
{
    return array(
        craft()->path->getStoragePath().'drinks/' => Craft::t('Drink images'),
    );
}

# `registerEmailMessages`

Called by: Craft\EmailMessagesService::getAllMessages() (opens new window), Craft\EmailMessagesService::getMessage() (opens new window), Craft\EmailMessagesService::saveMessage() (opens new window)
Return: An array of email messages.

Gives plugins a chance to register their own email messages.

Craft will look for the email keys and messages in a translation file matching the plugins source language.

For example, if the plugin source language is en_us and a message key is myPluginMessageKey1, Craft will look in pluginHandle/translations/en_us.php for the following keys to get the appropriate email messages:

myPluginMessageKey1_heading
myPluginMessageKey1_subject
myPluginMessageKey1_body

public function registerEmailMessages()
{
    return array(
        'myPluginMessageKey1',
        'myPluginMessageKey2',
    );
}

# `registerUserPermissions`

Called by: Craft\UserPermissionsService::getAllPermissions() (opens new window)
Return: An array of user permissions.

Gives plugins a chance to register new user permissions.

public function registerUserPermissions()
{
    return array(
        'drinkAlcohol' => array('label' => Craft::t('Drink alcohol')),
        'stayUpLate' => array('label' => Craft::t('Stay up late')),
    );
}

# `getCpAlerts`

Called by: Craft\CpHelper::getAlerts() (opens new window)
Return: An array of control panel alerts, or null if there are no alerts to display.

Gives plugins a chance to register new control panel alerts.

public function getCpAlerts($path, $fetch)
{
    if (craft()->config->devMode) {
        return array('Dev Mode is enabled!');
    }
}

The hook is passed the following arguments:

$path – The path to the main control panel page that the alert will be displayed on. (This won’t nceessarily be the same as Craft\HttpRequestService::getPath() (opens new window) because getCpAlerts() is often called over Ajax after the main page has loaded.)
$fetch – Whether the method can create HTTP requests when determining if it should display alerts. When this is false, if the alerts can not be determined without an HTTP request, null should be returned, so the method does not significantly impact control panel page load times.

# Routing Hooks

# `registerCpRoutes`

Called by: Craft\UrlManager::parseUrl() (opens new window)
Return: An array of control panel routes.

Gives plugins a chance to register their own control panel routes.

public function registerCpRoutes()
{
    return array(
        'cocktails/new'               => 'cocktails/_edit',
        'cocktails/(?P<widgetId>\d+)' => array('action' => 'cocktails/editCocktail'),
    );
}

# `registerSiteRoutes`

Called by: Craft\UrlManager::parseUrl() (opens new window)
Return: An array of site routes.

Gives plugins a chance to register their own front-end site routes.

public function registerSiteRoutes()
{
    return array(
        'cocktails/(?P<widgetId>\d+)' => array('action' => 'cocktails/editCocktail'),
    );
}

It’s a good practice to make any URL segments in your site routes configurable by the site administrator, so you’re not forcing a particular URL scheme on sites using your plugin.

# `getElementRoute`

Called by: Craft\UrlManager::parseUrl() (opens new window)
Return: A route, or null

Gives plugins a chance to override the default site route for a given element.

public function getElementRoute(BaseElementModel $element)
{
    if (
        $element->getElementType() == ElementType::Entry &&
        $element->getSection()->handle == 'products'
    ) {
        return array('action' => 'products/viewEntry');
    }
}

# Element Hooks

# `addEntryActions`

Called by: Craft\EntryElementType::getAvailableActions() (opens new window)
Return: An array of element actions.

Gives plugins a chance to add additional actions to the entry index page. Each item in the array can either be an element action’s class handle or an instantiated Craft\IElementAction (opens new window) object.

public function addEntryActions($source)
{
    return array(
        'Foo',
        new BarElementAction(),
    );
}

# `addCategoryActions`

Called by: Craft\CategoryElementType::getAvailableActions() (opens new window)
Return: An array of element actions.

Gives plugins a chance to add additional actions to the category index page. Each item in the array can either be an element action’s class handle or an instantiated Craft\IElementAction (opens new window) object.

public function addCategoryActions($source)
{
    return array(
        'Foo',
        new BarElementAction(),
    );
}

# `addAssetActions`

Called by: Craft\AssetElementType::getAvailableActions() (opens new window)
Return: An array of element actions.

Gives plugins a chance to add additional actions to the asset index page. Each item in the array can either be an element action’s class handle or an instantiated Craft\IElementAction (opens new window) object.

public function addAssetActions($source)
{
    return array(
        'Foo',
        new BarElementAction(),
    );
}

# `addUserActions`

Called by: Craft\UserElementType::getAvailableActions() (opens new window)
Return: An array of element actions.

Gives plugins a chance to add additional actions to the user index page. Each item in the array can either be an element action’s class handle or an instantiated Craft\IElementAction (opens new window) object.

public function addUserActions($source)
{
    return array(
        'Foo',
        new BarElementAction(),
    );
}

# `modifyAssetFilename`

Called by: Craft\AssetsHelper::cleanAssetName() (opens new window)
Return: The modified asset filename.

Gives plugins an opportunity to customize asset filenames as they are being cleansed.

public function modifyAssetFilename($filename)
{
    return 'KittensRule-'.$filename;
}

# `modifyEntrySortableAttributes`

Called by: Craft\EntryElementType::defineSortableAttributes() (opens new window)

Gives plugins a chance to modify the attributes that entries can be sorted by in the control panel.

public function modifyEntrySortableAttributes(&$attributes)
{
    $attributes['id'] = Craft::t('ID');
}

# `modifyCategorySortableAttributes`

Called by: Craft\CategoryElementType::defineSortableAttributes() (opens new window)

Gives plugins a chance to modify the attributes that categories can be sorted by in the control panel.

public function modifyCategorySortableAttributes(&$attributes)
{
    $attributes['id'] = Craft::t('ID');
}

# `modifyAssetSortableAttributes`

Called by: Craft\AssetElementType::defineSortableAttributes() (opens new window)

Gives plugins a chance to modify the attributes that assets can be sorted by in the control panel.

public function modifyAssetSortableAttributes(&$attributes)
{
    $attributes['id'] = Craft::t('ID');
}

# `modifyUserSortableAttributes`

Called by: Craft\UserElementType::defineSortableAttributes() (opens new window)

Gives plugins a chance to modify the attributes that users can be sorted by in the control panel.

public function modifyUserSortableAttributes(&$attributes)
{
    $attributes['id'] = Craft::t('ID');
}

# `modifyEntrySources`

Called by: Craft\EntryElementType::getSources() (opens new window)

Gives plugins a chance to modify the available sources for entries.

public function modifyEntrySources(&$sources, $context)
{
    if ($context == 'index') {
        $sources[] = array('heading' => 'Statuses');

        $statuses = craft()
            ->elements
            ->getElementType(ElementType::Entry)
            ->getStatuses();

        foreach ($statuses as $status => $label) {
            $sources['status:'.$status] = array(
                'label' => $label,
                'criteria' => array('status' => $status)
            );
        }
    }
}

# `modifyCategorySources`

Called by: Craft\CategoryElementType::getSources() (opens new window)

Gives plugins a chance to modify the available sources for categories.

public function modifyCategorySources(&$sources, $context)
{
    if ($context == 'index') {
        $sources[] = array('heading' => 'Statuses');
        $statuses = craft()->elements->getElementType(ElementType::Category)->getStatuses();

        foreach ($statuses as $status => $label) {
            $sources['status:'.$status] = array(
                'label' => $label,
                'criteria' => array('status' => $status)
            );
        }
    }
}

# `modifyAssetSources`

Called by: Craft\AssetElementType::getSources() (opens new window)

Gives plugins a chance to modify the available sources for assets.

public function modifyAssetSources(&$sources, $context)
{
    if ($context == 'index') {
        $sources[] = array('heading' => 'File Kinds');

        foreach (IOHelper::getFileKinds() as $kind => $info) {
            $sources['kind:'.$kind] = array(
                'label' => $info['label'],
                'criteria' => array('kind' => $kind)
            );
        }
    }
}

# `modifyUserSources`

Called by: Craft\UserElementType::getSources() (opens new window)

Gives plugins a chance to modify the available sources for users.

public function modifyUserSources(&$sources, $context)
{
    if ($context == 'index') {
        $sources[] = array('heading' => 'Statuses');
        $statuses = craft()
            ->elements
            ->getElementType(ElementType::User)
            ->getStatuses();

        foreach ($statuses as $status => $label) {
            $sources['status:'.$status] = array(
                'label' => $label,
                'criteria' => array('status' => $status)
            );
        }
    }
}

# `defineAdditionalEntryTableAttributes`

Called by: Craft\EntryElementType::defineAvailableTableAttributes() (opens new window)

Gives plugins a chance to make additional table columns available to entry indexes.

public function defineAdditionalEntryTableAttributes()
{
    return array(
        'foo' => "Foo",
        'bar' => "Bar",
    );
}

# `defineAdditionalCategoryTableAttributes`

Called by: Craft\CategoryElementType::defineAvailableTableAttributes() (opens new window)

Gives plugins a chance to make additional table columns available to category indexes.

public function defineAdditionalCategoryTableAttributes()
{
    return array(
        'foo' => "Foo",
        'bar' => "Bar",
    );
}

# `defineAdditionalAssetTableAttributes`

Called by: Craft\AssetElementType::defineAvailableTableAttributes() (opens new window)

Gives plugins a chance to make additional table columns available to asset indexes.

public function defineAdditionalAssetTableAttributes()
{
    return array(
        'foo' => "Foo",
        'bar' => "Bar",
    );
}

# `defineAdditionalUserTableAttributes`

Called by: Craft\UserElementType::defineAvailableTableAttributes() (opens new window)

Gives plugins a chance to make additional table columns available to user indexes.

public function defineAdditionalUserTableAttributes()
{
    return array(
        'foo' => "Foo",
        'bar' => "Bar",
    );
}

# `getEntryTableAttributeHtml`

Called by: Craft\EntryElementType::getTableAttributeHtml() (opens new window)
Return: The HTML that should be displayed in the table cell for the given attribute.

Gives plugins a chance to customize the HTML of the table cells on the entry index page.

public function getEntryTableAttributeHtml(EntryModel $entry, $attribute)
{
    if ($attribute == 'price') {
        return '$'.$entry->price;
    }
}

# `getCategoryTableAttributeHtml`

Called by: Craft\CategoryElementType::getTableAttributeHtml() (opens new window)
Return: The HTML that should be displayed in the table cell for the given attribute.

Gives plugins a chance to customize the HTML of the table cells on the category index page.

public function getCategoryTableAttributeHtml(CategoryModel $category, $attribute)
{
    if ($attribute == 'color' && $category->color) {
        return '<div class="colorbox" style="background-color: '.$category->color.';"></div>';
    }
}

# `getAssetTableAttributeHtml`

Called by: Craft\AssetElementType::getTableAttributeHtml() (opens new window)
Return: The HTML that should be displayed in the table cell for the given attribute.

Gives plugins a chance to customize the HTML of the table cells on the asset index page.

public function getAssetTableAttributeHtml(AssetFileModel $asset, $attribute)
{
    if ($attribute == 'smallScreenImage' || $attribute == 'largeScreenImage') {
        $altImage = $asset->$attribute->first();

        if ($altImage) {
            return craft()->templates->render('_elements/element', array(
                'element' => $altImg
            ));
        }

        return '';
    }
}

# `getUserTableAttributeHtml`

Called by: Craft\UserElementType::getTableAttributeHtml() (opens new window)
Return: The HTML that should be displayed in the table cell for the given attribute.

Gives plugins a chance to customize the HTML of the table cells on the user index page.

public function getUserTableAttributeHtml(UserModel $user, $attribute)
{
    if ($attribute == 'twitter' && $user->twitter) {
        return '<a href="https://twitter.com/'.$user->twitter.'">@'.$user->twitter.'</a>';
    }
}

# `getTableAttributesForSource`

Called by: Craft\BaseElementType::getTableAttributesForSource() (opens new window)
Return: An array of table attributes, or null.

Gives plugins a chance to customize the visible table attributes for a given element index source.

public function getTableAttributesForSource($elementType, $sourceKey)
{
    if ($sourceKey == 'foo') {
        return craft()->elementIndexes->getTableAttributes($elementType, 'bar');
    }
}

Hooks Reference

# General Hooks

# addRichTextLinkOptions

# addTwigExtension

# addUserAdministrationOptions

# getResourcePath

# modifyCpNav

# registerCachePaths

# registerEmailMessages

# registerUserPermissions

# getCpAlerts

# Routing Hooks

# registerCpRoutes

# registerSiteRoutes

# getElementRoute

# Element Hooks

# addEntryActions

# addCategoryActions

# addAssetActions

# addUserActions

# modifyAssetFilename

# modifyEntrySortableAttributes

# modifyCategorySortableAttributes

# modifyAssetSortableAttributes

# modifyUserSortableAttributes

# modifyEntrySources

# modifyCategorySources

# modifyAssetSources

# modifyUserSources

# defineAdditionalEntryTableAttributes

# defineAdditionalCategoryTableAttributes

# defineAdditionalAssetTableAttributes

# defineAdditionalUserTableAttributes

# getEntryTableAttributeHtml

# getCategoryTableAttributeHtml

# getAssetTableAttributeHtml

# getUserTableAttributeHtml

# getTableAttributesForSource

Was this page helpful?

# `addRichTextLinkOptions`

# `addTwigExtension`

# `addUserAdministrationOptions`

# `getResourcePath`

# `modifyCpNav`

# `registerCachePaths`

# `registerEmailMessages`

# `registerUserPermissions`

# `getCpAlerts`

# `registerCpRoutes`

# `registerSiteRoutes`

# `getElementRoute`

# `addEntryActions`

# `addCategoryActions`

# `addAssetActions`

# `addUserActions`

# `modifyAssetFilename`

# `modifyEntrySortableAttributes`

# `modifyCategorySortableAttributes`

# `modifyAssetSortableAttributes`

# `modifyUserSortableAttributes`

# `modifyEntrySources`

# `modifyCategorySources`

# `modifyAssetSources`

# `modifyUserSources`

# `defineAdditionalEntryTableAttributes`

# `defineAdditionalCategoryTableAttributes`

# `defineAdditionalAssetTableAttributes`

# `defineAdditionalUserTableAttributes`

# `getEntryTableAttributeHtml`

# `getCategoryTableAttributeHtml`

# `getAssetTableAttributeHtml`

# `getUserTableAttributeHtml`

# `getTableAttributesForSource`