Hooks Reference

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 byRichTextFieldType::getInputHtml()
ReturnAn 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 getSources() 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 byTemplatesService::getTwig(), TemplatesService::onPluginsLoaded()
ReturnA new \Twig_Extension object

Gives plugins a chance to add a new Twig extension.

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

addUserAdministrationOptions #

Called byUsersController::actionEditUser()
ReturnAn 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 byResourcesService::getResourcePath()
ReturnA 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 byCpVariable::nav()

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 byClearCachesTool::performAction()
ReturnAn 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 byEmailMessagesService::getAllMessages(), EmailMessagesService::getMessage(), EmailMessagesService::saveMessage()
ReturnAn 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 byUserPermissionsService::getAllPermissions()
ReturnAn 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 byCpHelper::getAlerts()
ReturnAn array of CP 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 CP page that the alert will be displayed on. (This won’t nceessarily be the same as HttpRequestService::getPath() 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 CP page load times.

Routing Hooks #

registerCpRoutes #

Called byUrlManager::parseUrl()
ReturnAn array of CP routes

Gives plugins a chance to register their own CP routes.

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

registerSiteRoutes #

Called byUrlManager::parseUrl()
ReturnAn 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 byUrlManager::parseUrl()
ReturnA 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 byEntryElementType::getAvailableActions()
ReturnAn 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 IElementAction object.

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

addCategoryActions #

Called byCategoryElementType::getAvailableActions()
ReturnAn 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 IElementAction object.

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

addAssetActions #

Called byAssetElementType::getAvailableActions()
ReturnAn 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 IElementAction object.

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

addUserActions #

Called byUserElementType::getAvailableActions()
ReturnAn 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 IElementAction object.

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

modifyAssetFilename #

Called byAssetsHelper::cleanAssetName()
ReturnThe 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 byEntryElementType::defineSortableAttributes()

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 byCategoryElementType::defineSortableAttributes()

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 byAssetElementType::defineSortableAttributes()

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 byUserElementType::defineSortableAttributes()

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 byEntryElementType::getSources()

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 byCategoryElementType::getSources()

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 byAssetElementType::getSources()

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 byUserElementType::getSources()

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 byEntryElementType::defineAvailableTableAttributes()

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

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

defineAdditionalCategoryTableAttributes #

Called byCategoryElementType::defineAvailableTableAttributes()

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

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

defineAdditionalAssetTableAttributes #

Called byAssetElementType::defineAvailableTableAttributes()

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

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

defineAdditionalUserTableAttributes #

Called byUserAssetType::defineAvailableTableAttributes()

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

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

getEntryTableAttributeHtml #

Called byEntryElementType::getTableAttributeHtml()
ReturnThe 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 byCategoryElementType::getTableAttributeHtml()
ReturnThe 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 byAssetElementType::getTableAttributeHtml()
ReturnThe 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 byUserElementType::getTableAttributeHtml()
ReturnThe 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 byBaseElementType::getTableAttributesForSource()
ReturnAn 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');
    }
}