フックを使用してContaoにカスタム機能を追加する方法

フックはデータコンテナ配列のコールバック関数と似た動作をします。特定のイベントに1つ以上の関数を登録でき、イベントが起きると登録した関数が呼び出されます。フックによってコアにカスタム機能を追加できます。

activateAccount ¶

activateAccountフックは新しいフロントエンドのアカウントを有効したときに呼び出します。フック関数の引数にはユーザーオブジェクトを渡し、戻り値は使用しません。バージョン2.4.3から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['activateAccount'][] = array('MyClass', 'myActivateAccount');

// MyClass.php
public function myActivateAccount(Database_Result $objUser)
{
    // Do something
}

activateRecipient ¶

activateRecipientフックはニュースレターの新しい宛先を追加したときに呼び出します。フック関数の引数には電子メールアドレス、宛先のID、チャンネルのIDを渡し、戻りは使用しません。バージョン2.8.RC1から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['activateRecipient'][] = array('MyClass', 'myActivateRecipient');

// MyClass.php
public function myActivateRecipient($strEmail, $arrRecipients, $arrChannels)
{
    // Do something
}

addComment ¶

addCommentフックはコメントを追加したときに呼び出します。フック関数の引数にはレコードのIDとデータ配列を渡し、戻り値は使用しません。バージョン2.8.2から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['addComment'][] = array('MyClass', 'myAddComment');

// MyClass.php
public function myAddComment($intId, $arrSet)
{
    // Do something
}

addCustomRegexp ¶

addCustomRegexpフックは不明な正規表現をみつけたときに呼び出します。フック関数の引数には正規表現の名前、現在の値、ウィジェットオブジェクトを渡し、論理値を戻り値とします。バージョン2.6.2から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['addCustomRegexp'][] = array('MyClass', 'myAddCustomRegexp');

// MyClass.php
public function myAddCustomRegexp($strRegexp, $varValue, Widget $objWidget)
{
    if ($strRegexp == 'postal')
    {
        if (!preg_match('/^0-9{4,6}$/', $varValue))
        {
            $objWidget-&gt;addError('Field ' . $objWidget-&gt;label . ' should be a postal code.');
        }

        return true;
    }

    return false;
}

addLogEntry ¶

addLogEntryフックは新しいログの項目を追加したときに呼び出します。フック関数の引数にはメッセージ、(ログの元となった)関数、アクションを渡し、戻り値は使用しません。バージョン2.8.RC1から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['addLogEntry'][] = array('MyClass', 'myAddLogEntry');

// MyClass.php
public function myAddLogEntry($strText, $strFunction, $strAction)
{
    // Do something
}

checkCredentials ¶

checkCredentialsフックは間違ったパスワードによってログインに失敗したときに呼び出します。フック関数の引数にはユーザーオブジェクトに加えて、ユーザー名、パスワードが渡され、論理値を戻り値とします。バージョン2.6.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['checkCredentials'][] = array('MyClass', 'myCheckCredentials');

// MyClass.php
public function myCheckCredentials($strUsername, $strPassword, User $objUser)
{
    // Check against a global database
    if ($this-&gt;checkGlobalDbFor($strUsername, $strPassword))
    {
        return true;
    }

    return false;
}

closeAccount ¶

closeAccountフックはユーザーがアカウントを廃止したときに呼び出します。フック関数の引数にはユーザーのID、操作モード、モジュールを渡し、戻り値は使用しません。バージョン2.8.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['closeAccount'][] = array('MyClass', 'myCloseAccount');

// MyClass.php
public function myCloseAccount($intId, $strMode, $objModule)
{
    if ($strMode == 'close_delete')
    {
        // Do something
    }
}

compileDefinition ¶

compileDefinitionフックはスタイルシートの書式定義が書き込まれたときに呼び出します。フック関数の引数には構成配列を渡し、文字列を戻り値とします。バージョン2.9.4から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['compileDefinition'][] = array('MyClass', 'myCompileDefinition');
 
// MyClass.php
public function myCompileDefinition($arrRow)
{
    if (isset($arrRow['border-radius']))
    {
        return "\nborder-radius:" . $arrRow['border-radius'] . ";";
    }
 
    return '';
}

createDefinition ¶

createDefinitionフックはスタイルシートの書式定義がインポートされたときに呼び出します。フック関数の引数にはキーと値、元の書式定義、データ配列が渡され、配列またはfalseを戻り値とします。バージョン2.9.4から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['createDefinition'][] = array('MyClass', 'myCreateDefinition');
 
// MyClass.php
public function myCreateDefinition($strKey, $strValue, $strDefinition, $arrSet)
{
    if ($strKey == 'border-radius')
    {
        return array('border-radius'=>$strValue);
    }
 
    return false;
}

createNewUser ¶

createNewUserフックはウェブサイトに新しいフロントエンドのユーザーを登録したときに呼び出します。フック関数の引数には新しいユーザーのIDとデータ配列が渡され、戻り値は使用しません。バージョン2.2.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['createNewUser'][] = array('MyClass', 'myCreateNewUser');

// MyClass.php
public function myCreateNewUser($intId, $arrData)
{
    // Modify the record
}

executePreActions ¶

executePreActionsフックは応答を求めないAjaxをリクエストの前に呼び出します。フック関数の引数にはアクションの名前を渡し、戻り値は使用しません。バージョン2.6.1から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['executePreActions'][] = array('MyClass', 'myExecutePreActions');

// MyClass.php
public function myExecutePreActions($strAction)
{
    if ($strAction == 'update')
    {
        // Do something
    }
}

executePostActions ¶

executePostActionsフックは応答を求めないAjaxのリクエストの後で呼び出します。フック関数の引数にはアクションの名前とデータコンテナオブジェクトを渡し、戻り値は使用しません。バージョン2.6.1から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['executePostActions'][] = array('MyClass', 'myExecutePostActions');

// MyClass.php
public function myExecutePostActions($strAction, DataContainer $dc)
{
    if ($strAction == 'update')
    {
        // Do something
    }
}

generateFrontendUrl ¶

generateFrontendUrlフックはフロントエンドのURLを再作成したときに呼び出します。フック関数の引数にはページオブジェクト、パラメーター引数、デフォルトのURLが渡し、文字列を戻り値とします。バージョン2.5.8から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['generateFrontendUrl'][] = array('MyClass', 'myGenerateFrontendUrl');

// MyClass.php
public function myGenerateFrontendUrl(Database_Result $objPage, $strParams, $strUrl)
{
    return str_replace('.html', '.xml', $strUrl);
}

generatePage ¶

generatePageフックは主となるレイアウト(fe_page)を処理する前に呼び出します。フック関数の引数にはページオブジェクトと自身への参照を渡し、戻り値は使用しません。バージョン2.8.RC1から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['generatePage'][] = array('MyClass', 'myGeneratePage');

// MyClass.php
public function myGeneratePage(Database_Result $objPage, Database_Result $objLayout, PageRegular $objPageRegular)
{
    // Do something
}

getAllEvents ¶

getAllEventsフックにより、カレンダーとイベントモジュールの結果のセットを変更できます。フック関数の引数には現在の結果のセット、親の項目のID、開始と終了の時刻を渡し、結果のセット(配列)を戻り値とします。バージョン2.6.4から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['getAllEvents'][] = array('MyClass', 'myGetAllEvents');

// MyClass.php
public function myGetAllEvents($arrEvents, $arrCalendars, $intStart, $intEnd)
{
    ksort($arrEvents);
    return $arrEvents;
}

getContentElement ¶

getContentElementフックはコンテント要素を表示(レンダリング)するときに呼び出します。フック関数の引数にはデータベースオブジェクトとバッファー文字列を渡し、バッファー文字列を戻り値とします。バージョン2.9.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['getContentElement'][] = array('MyClass', 'myGetContentElement');

// MyClass.php
public function myGetContentElement(Database_Result $objElement, $strBuffer)
{
    return $strBuffer;
}

getImage ¶

getImageフックはサムネイルを生成したときに呼び出し、カスタム処理を追加できます。フック関数の引数にはパス、幅と高さ、モード、キャッシュの名前、ファイルオブジェクトを私、パスを戻り値とします。バージョン2.8から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['getImage'][] = array('MyClass', 'myGetImage');

// MyClass.php
public function myGetImage($image, $width, $height, $mode, $strCacheName, $objFile)
{
    return MyImage::generateThumbnail($image, $widht, $height, $mode);
}

getPageIdFromUrl ¶

getPageIdFromUrlフックはURLの断片を評価したときに呼び出します。フック関数の引数にはURLの断片が渡され、URLの断片の配列を戻り値とします。バージョン2.5.4から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['getPageIdFromUrl'][] = array('MyClass', 'myGetPageIdFromUrl');

// MyClass.php
public function myGetPageIdFromUrl($arrFragments)
{
    return array_unique($arrFragments);
}

getSearchablePages ¶

getSearchablePagesフックは検索インデックスを再構築したときに呼び出します。フック関数の引数にはページの配列とルートページを渡し、完全なURL! の配列を戻り値とします。バージョン2.2.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['getSearchablePages'][] = array('MyClass', 'myGetSearchablePages');

// MyClass.php
public function myGetSearchablePages($arrPages, $intRoot)
{
    return array_merge($arrPages, array('Additional pages'));
}

importUser ¶

importUserフックは、データベースにユーザー名を見つけられないときに呼び出します。フック関数の引数にはユーザー名、パスワード、テーブル名を引数として渡し、論理値を戻り値とします。バージョン2.7.RC1から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['importUser'][] = array('MyClass', 'myImportUser');

// MyClass.php
public function myImportUser($strUsername, $strPassword, $strTable)
{
    if ($strTable == 'tl_member')
    {
        // Import user from an LDAP server
        if ($this-&gt;importUserFromLdap($strUsername, $strPassword))
        {
            return true;
        }
    }

    return false;
}

listComments ¶

listCommentsフックはコメントがバックエンドに一覧されるときに呼び出します。フック関数の引数には現在のレコードを渡し、文字列を戻り値とします。バージョン2.8.RC2から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['listComments'][] = array('MyClass', 'myListComments');

// MyClass.php
public function myListComments($arrRow)
{
    return '<a href="contao/main.php?do= ... ">' . $arrRow['title'] . '</a>';

loadFormField ¶

loadFormFieldフックはフォームのフィールドを読み込んだときに呼び出します。フック関数の引数にはウィジェットのオブジェクト、フォームのID、フォームのデータを渡し、ウィジェットのオブジェクトを戻り値とします。バージョン2.5.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['loadFormField'][] = array('MyClass', 'myLoadFormField');

// MyClass.php
public function myLoadFormField(Widget $objWidget, $strForm, $arrForm)
{
    $objWidget->class = 'myclass';
    return $objWidget;
}

loadDataContainer ¶

loadDataContainerフックはDCAファイルを読み込んだときに呼び出します。フック関数の引数にはファイル名を渡し、戻り値は使用しません。バージョン2.8.2から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['loadDataContainer'][] = array('MyClass', 'myLoadDataContainer');

// MyClass.php
public function myLoadDataContainer($strName)
{
    // Do something
}

loadLanguageFile ¶

loadLanguageFileフックは言語ファイルを読み込んだときに呼び出します。フック関数の引数にはファイル名と言語を渡し、戻り値は使用しません。バージョン2.8.RC1から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['loadLanguageFile'][] = array('MyClass', 'myLoadLanguageFile');

// MyClass.php
public function myLoadLanguageFile($strName, $strLanguage)
{
    // Do something
}

outputBackendTemplate ¶

outputBackendTemplateフックはバックエンドのテンプレートを画面に表示したときに呼び出します。フック関数の引数にはテンプレートの内容とテンプレート名を渡し、テンプレートのコンテンツを戻り値とします。バージョン2.6.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['outputBackendTemplate'][] = array('MyClass', 'myOutputBackendTemplate');

// MyClass.php
public function myOutputBackendTemplate($strContent, $strTemplate)
{
    if ($strTemplate == 'be_main')
    {
        // Modify output
    }

    return $strContent;
}

outputFrontendTemplate ¶

outputFrontendTemplateフックはフロントエンドのテンプレートを画面に表示したときに呼び出します。フック関数の引数にはテンプレートの内容とテンプレート名を渡し、テンプレートのコンテンツを戻り値とします。バージョン2.6.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['outputFrontendTemplate'][] = array('MyClass', 'myOutputFrontendTemplate');

// MyClass.php
public function myOutputFrontendTemplate($strContent, $strTemplate)
{
    if ($strTemplate == 'fe_page')
    {
        // Modify output
    }

    return $strContent;
}

parseBackendTemplate ¶

parseBackendTemplateフックはバックエンドのテンプレートを解析したときに呼び出します。フック関数の引数にはテンプレートの内容とテンプレート名を渡し、テンプレートのコンテンツを戻り値とします。バージョン2.6.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['parseBackendTemplate'][] = array('MyClass', 'myParseBackendTemplate');

// MyClass.php
public function myParseBackendTemplate($strContent, $strTemplate)
{
    if ($strTemplate == 'be_main')
    {
        // Modify output
    }

    return $strContent;
}

parseFrontendTemplate ¶

parseFrontendTemplateフックはフロントエンドのテンプレートを解析したときに呼び出します。フック関数の引数にはテンプレートの内容とテンプレート名を渡し、テンプレートのコンテンツを戻り値とします。バージョン2.6.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['parseFrontendTemplate'][] = array('MyClass', 'myParseFrontendTemplate');

// MyClass.php
public function myParseFrontendTemplate($strContent, $strTemplate)
{
    if ($strTemplate == 'ce_text')
    {
        // Modify output
    }

    return $strContent;
}

postDownload ¶

postDownloadフックはコンテント要素のダウンロードや複数ダウンロードで、ファイルをダウンロードした後で呼び出します。フック関数の引数にはファイル名を渡し、戻り値は使用しません。バージョン2.4.6から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['postDownload'][] = array('MyClass', 'myPostDownload');

// MyClass.php
public function myPostDownload($strFile)
{
    // Do something
}

postLogin ¶

postLoginフックはユーザーがフロントエンドにログインした後で呼び出します。フック関数の引数にはユーザーオブジェクトを渡し、戻り値は使用しません。バージョン2.4.3から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['postLogin'][] = array('MyClass', 'myPostLogin');

// MyClass.php
public function myPostLogin($objUser)
{
    // Do something
}

postLogout ¶

postLogoutフックはユーザーがフロントエンドからログアウトした後で呼び出します。フック関数の引数にはユーザーオブジェクトを渡し、戻り値は使用しません。バージョン2.4.3から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['postLogout'][] = array('MyClass', 'myPostLogout');

// MyClass.php
public function myPostLogout(Database_Result $objUser)
{
    // Do something
}

postUpload ¶

postUploadフックはユーザーがバックエンドで1つ、または複数のファイルをアップロードした後で呼び出します。フック関数の引数にはファイル名の配列を渡し、戻り値は使用しません。バージョン2.6.4から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['postUpload'][] = array('MyClass', 'myPostUpload');

// MyClass.php
public function myPostUpload($arrFiles)
{
    // Do something
}

printArticleAsPdf ¶

printArticleAsPdfフックはアーティクルをPDFとしてエクスポートしたときに呼び出します。フック関数の引数にはアーティクルのテキストとアーティクルのオブジェクトを渡し、戻り値は使用しません。バージョン2.8.RC1から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['printArticleAsPdf'][] = array('MyClass', 'myPrintArticleAsPdf');

// MyClass.php
public function myPrintArticleAsPdf($strArticle, Database_Result $objArticle)
{
    // Do something
}

processFormData ¶

processFormDataフックはフォームが提出された後に呼び出します。フック関数の引数にはデータ配列、データコンテナ配列、ファイル配列を渡し、戻り値は使用しません。バージョン2.4.4から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['processFormData'][] = array('MyClass', 'myProcessFormData');

// MyClass.php
public function myProcessFormData($arrPost, $arrForm, $arrFiles)
{
    // Do something
}

removeOldFeeds ¶

removeOldFeedsフックは古いXMLファイルをContaoのディレクトリから削除したときに呼び出します。フック関数の引数はなく、保存するためのファイル名の配列を戻り値とします。バージョン2.5.8から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['removeOldFeeds'][] = array('MyClass', 'myRemoveOldFeeds');

// MyClass.php
public function myRemoveOldFeeds()
{
    return array('custom.xml');
}

removeRecipient ¶

removeRecipientフックはニュースレターの宛先を削除したときに呼び出します。フック関数の引数には電子メールアドレス、チャンネルのIDを渡し、戻りは使用しません。バージョン2.8.RC1から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['removeRecipient'][] = array('MyClass', 'myRemoveRecipient');

// MyClass.php
public function myRemoveRecipient($strEmail, $arrChannels)
{
    // Do something
}

replaceInsertTags ¶

replaceInsertTagsフックは不明な挿入タグを見つけたときに呼び出します。フック関数の引数には挿入タグを渡し、置き換えた値かfalseを戻り値とします。バージョン2.6.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['replaceInsertTags'][] = array('MyClass', 'myReplaceInsertTags');

// MyClass.php
public function myReplaceInsertTags($strTag)
{
    if ($strTag == 'mytag')
    {
        return 'mytag replacement';
    }

    return false;
}

reviseTable ¶

reviseTableフックはContaoが孤児となったレコードをテーブルから削除するときに呼び出します。フック関数の引数には現在のテーブル、新しいレコードのID、親のテーブルの名前、すべての子のテーブルを渡し、論理値を戻り値とします(trueを返すと現在のページを再読み込みすることになります)。バージョン2.6.4から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['reviseTable'][] = array('MyClass', 'myReviseTable');

// MyClass.php
public function myReviseTable($table, $new_records, $parent_table, $child_tables)
{
    // Do something
}

setNewPassword ¶

setNewPasswordフックは新しいパスワードを設定した後で呼び出します。フック関数の引数にはユーザーオブジェクトと暗号化したパスワードを渡し、戻り値は使用しません。バージョン2.2.3から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['setNewPassword'][] = array('MyClass', 'mySetNewPassword');

// MyClass.php
public function mySetNewPassword($objUser, $strPassword)
{
    // Do something
}

validateFormField ¶

validateFormFieldフックはフォームのフィールドが提出されたときに呼び出します。フック関数の引数にはウィジェットのオブジェクト、フォームのIDを渡し、ウィジェットのオブジェクトを戻り値とします。バージョン2.5.0から利用可能です。

// config.php
$GLOBALS['TL_HOOKS']['validateFormField'][] = array('MyClass', 'myValidateFormField');

// MyClass.php
public function myValidateFormField(Widget $objWidget, $intId)
{
    if ($objWidget instanceof FormPassword)
    {
        // Do something
    }

    return $objWidget;
}

コメントを追加

Kamil Kuzminskiによるコメント| 2011年6月21日

サイトマップを生成するときに、getSearchablePagesフックも呼び出されます。

Kamil Kuzminskiによるコメント| 2011年8月30日

"postLogin"と"postLogout"の2つのコールバックを使用する場合は、両方を1つの関数に割り当てることができます。

public function postLoginLogout(FrontendUser $objUser)
{
    // ユーザーがログイン
    if (!FE_USER_LOGGED_IN)
    {
        // ...
    }

    // ユーザーがログアウト
    else
    {
        // ...
    }
}

Tsarmaによるコメント| 2011年9月5日

用意されているgenerateBreadcrumbフックにも触れていません。これを使うとナビゲーション項目を出力する前に操作できます。

Fredによるコメント| 2011年9月14日

ドキュメントされていないフックがあります。

if (isset($GLOBALS['TL_HOOKS']['updatePersonalData']) && is_array($GLOBALS['TL_HOOKS']['updatePersonalData']))
{
  foreach ($GLOBALS['TL_HOOKS']['updatePersonalData'] as $callback)
  {
    $this->import($callback[0]);
    $this->$callback[0]->$callback[1]($this->User, $_SESSION['FORM_DATA']);
  }
}

Kamil Kuzminskiによるコメント| 2011年9月28日

postLoginの例はContao 2.10以降では正しく動作しないでしょう、なぜならバックエンドのユーザーがログインした時も呼び出されるからです。従って、以下のようにコードを変更しなければなりません:

public function postLogin($objUser)
{
    // Front end
    if (TL_MODE == 'FE')
    {

    }
	
    // Back end
    elseif (TL_MODE == 'BE')
    {

    }
}

Kamil Kuzminskiによるコメント| 2011年12月23日

getSearchablePages()はrootのIDを渡さなくなっていることに注意してください!

Tsarmaによるコメント| 2011年12月23日

Templateを変更したいが、初期状態でテンプレートのドロップダウンがない状況ではparseTemplateフックが役に立ちます。

// HOOK: カスタマイズした解析フィルターを追加
if (isset($GLOBALS['TL_HOOKS']['parseTemplate']) && is_array($GLOBALS['TL_HOOKS']['parseTemplate']))
{
    foreach ($GLOBALS['TL_HOOKS']['parseTemplate'] as $callback)
    {
        $this->import($callback[0]);
        $this->$callback[0]->$callback[1]($this);
    }
}

先頭に戻る