開発者エリア/ローカルカスタマイゼーション: Difference between revisions

Latest revision as of 05:39, 27 September 2020

Maharaには/localディレクトリが含まれます。これはコアコードを編集せずにMaharaサイトの動作を変更可能にするための複数タイプのローカルカスタマイゼーション用フック提供用の中心的な場所です。

なぜ、/localなのですか?

あなたが新しいウェブサイト管理者である場合、「本当に必要ですか?」と自問することでしょう。私のMaharaサイトをカスタマイズしたい場合、Maharaコードを直接編集してはどうだろう?

その答えは「Maharaのコアコードを修正した場合、アップデートが困難になってしまいます」です。Maharaプロジェクトは定期的に更新をリリースしますが、極めて広範囲に渡る場合もあります。あなたがMaharaコードを全くカスタマイズしていない場合、単に既存のコードを更新済みコードに置換できます。しかし、あなたがMaharaコアファイルをカスタマイズしている場合、そして、私たちがそのファイルを更新している場合、あなたの更新を失ってしまうか、新しいバージョンのファイルの適用方法を見つけ出さなければなりません。特にGitのような適切なバージョンコントロールの使用することにより、この処理をさらに簡単にはできます。しかし、Maharaコアコードの修正を最小限にする方が簡単です。

/localディレクトリの使用はMaharaをカスタマイズするための方法の1つです。プラグインおよびテーマはカスタマイズのための他の主要な方法です。オプションに関する完全なリストはカスタマイズをご覧ください。/localディレクトリはMaharaをカスタマイズするための方法の1つにしか過ぎません。プラグインおよびテーマがMaharaをカスタマイズするための主な手段です。オプションの完全なリストに関してカスタマイジングをご覧ください。

/localでは何ができますか?

過去において、/local内の新しいフックは常にドキュメントが十分に整っているわけではなかったことに留意してください。そのため、あなたにとって最新情報を取得するための最善の方法は実際にコードを調査することです。

また、あなたがファイルをアップロードできる/local内にはすでに多くのファイルが配置されていることにも留意してください。そのため、あなたがそれらのファイルを編集するには「コアを編集」しなければなりません。しかし、これらのファイルはアップグレード処理中に常にあなた独自のファイルで安全に簡単に上書きできるよう設計されています。

フックをインストールする

ファイルlocal/install.phpにはlocalpreinst()およびlocalpostinst()という名称の関数が含まれます。これらはMaharaのインストール処理中に呼び出されます。localpreinst()はインストール処理の初期段階で呼び出されます。そして、localpostinst()はインストール処理の最終段階で呼び出されます。

これらのメソッドはは空のまま定義されています。あなたの独自コードを追加するため、事前および事後インストール処理として空のメソッドにオーバーライドできます。

DBフック

/localディレクトリには独自の「version.php」「insatall.xml」および「upgrade.php」ファイルがあります。これらのファイルは標準のMaharaプラグインに対するのと同じように動作します。Maharaの初回インストール時、データベース構造の定義されたlocal/install.xmlが作成されます。また、local/version.phpのバージョンナンバーが (設定値「localversion」として) データベースに保存されます。local/version.phpのバージョンが増加した場合、Maharaはこれを検知してlocal/upgrade.phpの適切なアップグレードセクションを実行するためのアップグレードスクリプトを実行するよう管理者に促します。

カスタム言語ストリング

あなたは/local/langディレクトリ配下に独自の言語ファイルを配置して既存の言語ストリングをオーバーライドできます。

詳細は開発者エリア/言語ストリング#/localのカスタム言語ストリングをご覧ください。

ヘルプをカスタムヘルプファイルでオーバーライドする

あなたは/local/langディレクトリ配下に独自のヘルプァイルを配置して既存のヘルプファイルのコンテンツをオーバーライドできます。

詳細は開発者エリア/言語ストリング#/local のカスタムヘルプファイルをご覧ください。

カスタムテーマオーバーライド

あなたは/local/theme/templatesディレクトリをテーマの「テンプレート」ディレクトリとして配下にカスタムテーマを設置できます。同様にあなたはイメージのような静的資源を/local/theme/staticに設置してカスタマイズできます。詳細はCustomising/Themes/1.10#Local_theme_overridesをご覧ください。

このように/localディレクトリに置かれるテンプレートファイルはMahara 1.10以前のバージョンでは現在のテーマディレクトリの下、すべての親テーマの上に順に置かれていました。既存のページを上書きせずに新しいページを作成できる点で多くの場合において/localディレクトリは有用です。Mahara 1.10以前のバージョンではプラグインのテンプレートファイルはMaharaに同梱されているテンプレートであっても、/localディレクトリ経由ではカスタマイズできませんでした。現在、Mahara 1.10ではこれらの制限が取り除かれました。/local テーマコンテンツが最初に読み込まれることになり、/localにプラグインのテーマコンテンツを同梱可能となりました。

/local/lib.php内の様々なフック関数

Maharaコードベースにはローカル「hook」関数の存在がチェックされる多くの場所を含みます。ローカル「hook」関数が存在する場合、この関数が実行されます。これはサイト管理者がMaharaの主要機能のコアコードを変更せずに変更を提供できることを意味します。

Mahara 1.10以降、これらすべては/local/lib.phpファイルのヘッダに文書化されています。以下、いくつかの主要部分です:

local_can_remove_viewtype($viewtype): ユーザによる特定タイプのページ削除をブロックできます。
local_get_allowed_blocktypes($category, $view): ページビルダからブロックタイプカテゴリを削除するため使用できます。
local_header_top_content(): 戻りデータはほとんどのページ最上部の「head」タグに表示されます。あなたに静止コンテンツの表示のみが必要な場合、Mahara 1.9現在、これは設定オプション「$cfg->additionalhtmlhead」 (lib/config-defaults.phpに記述) を使用して実現できます。
local_main_nav_update(&$menu): メインナビゲーションメニューのコンテンツを修正するため使用できます。
local_right_nav_update(&$menu): サイドバーのコンテンツを修正するため使用できます。
local_register_submit(&$values): 事前登録フックです。$values['extra']に追加されるコンテンツは自動的にusr_registration.extra内のデータベースに保存されます。
local_post_register($registration): 事前登録フックです。usr_registration.extraに保存されるデータの場所を意味します。これは検索可能であり現在登録中のユーザに適用できます。
local_init_user(): グローバル$USERオブジェクト初期化直後のページ読み込み時にコールされるフック関数です。

@@ Line 1: / Line 1: @@
-作成中です - [[User:Mits|mits]] ([[User talk:Mits|talk]])
+Maharaには'''/local'''ディレクトリが含まれます。これはコアコードを編集せずにMaharaサイトの動作を変更可能にするための複数タイプの'''ローカルカスタマイゼーション'''用フック提供用の中心的な場所です。
-Mahara includes a '''/local''' directory. This is a central place which provides hooks for several types of '''local customizations''', that allow a Mahara site to change the behavior of Mahara without editing Mahara core code.
+=== なぜ、/localなのですか? ===
+あなたが新しいウェブサイト管理者である場合、「本当に必要ですか?」と自問することでしょう。私のMaharaサイトをカスタマイズしたい場合、Maharaコードを直接編集してはどうだろう?
-=== なぜ /local なのですか? Why /local? ===
+その答えは「Maharaのコアコードを修正した場合、アップデートが困難になってしまいます」です。Maharaプロジェクトは定期的に更新をリリースしますが、極めて広範囲に渡る場合もあります。あなたがMaharaコードを全くカスタマイズしていない場合、単に既存のコードを更新済みコードに置換できます。しかし、あなたがMaharaコアファイルをカスタマイズしている場合、そして、私たちがそのファイルを更新している場合、あなたの更新を失ってしまうか、新しいバージョンのファイルの適用方法を見つけ出さなければなりません。特に[https://en.wikipedia.org/wiki/Git_git Git]のような適切なバージョンコントロールの使用することにより、この処理をさらに簡単にはできます。しかし、Maharaコアコードの修正を最小限にする方が簡単です。
-If you're new to website administration, you may be asking, why bother? If I want to make a customization to my Mahara site, why not just edit the Mahara code directly?
+/localディレクトリの使用はMaharaをカスタマイズするための方法の1つです。プラグインおよびテーマはカスタマイズのための他の主要な方法です。オプションに関する完全なリストは[[Mahara日本語ドキュメント/カスタマイズ|カスタマイズ]]をご覧ください。/localディレクトリはMaharaをカスタマイズするための方法の1つにしか過ぎません。プラグインおよびテーマがMaharaをカスタマイズするための主な手段です。オプションの完全なリストに関して[[カスタマイジング]]をご覧ください。
-The answer is that '''editing Mahara core code makes updates difficult'''. The Mahara project regularly releases updates, some quite extensive. If you haven't customized your Mahara code at all, you can simply replace your existing code base with the updated one. But if you ''have'' customized a Mahara core file, and our updates change that file, you will either have to lose your updates or figure out how to apply them to the new version of the file. Using proper [http://en.wikipedia.org/wiki/Revision_control revision control], especially [http://en.wikipedia.org/wiki/git git], can make this process easier, but it's still easiest to avoid it by minimizing changes to the Mahara core code.
+=== /localでは何ができますか? ===
+過去において、/local内の新しいフックは常にドキュメントが十分に整っているわけではなかったことに留意してください。そのため、あなたにとって最新情報を取得するための最善の方法は実際にコードを調査することです。
-The "/local" directory is just one way to customize Mahara. Plugins and Themes are the other main ways to do this. See [[Customising]] for the full list of options.
+また、あなたがファイルをアップロードできる/local内にはすでに多くのファイルが配置されていることにも留意してください。そのため、あなたがそれらのファイルを編集するには「コアを編集」しなければなりません。しかし、これらのファイルはアップグレード処理中に常にあなた独自のファイルで安全に簡単に上書きできるよう設計されています。
-=== /localで何ができますか? What /local can do ===
+==== フックをインストールする ====
+ファイル'''local/install.php'''には'''localpreinst()'''および'''localpostinst()'''という名称の関数が含まれます。これらはMaharaのインストール処理中に呼び出されます。localpreinst()はインストール処理の初期段階で呼び出されます。そして、localpostinst()はインストール処理の最終段階で呼び出されます。
-Note that in the past, new hooks in /local have not always been well documented. So when in doubt, your best bet for the latest information will be to search the codebase.
+これらのメソッドはは空のまま定義されています。あなたの独自コードを追加するため、事前および事後インストール処理として空のメソッドにオーバーライドできます。
-Also note that many of the files you can place under /local are already present in Mahara core. So you do have to "edit core" in order to edit them. However, these files will always be designed in such a way that you can safely and easily overwrite them with your own files during the upgrade process.
+==== DBフック ====
+/localディレクトリには独自の「version.php」「insatall.xml」および「upgrade.php」ファイルがあります。これらのファイルは標準のMaharaプラグインに対するのと同じように動作します。Maharaの初回インストール時、データベース構造の定義されたlocal/install.xmlが作成されます。また、local/version.phpのバージョンナンバーが (設定値「localversion」として) データベースに保存されます。local/version.phpのバージョンが増加した場合、Maharaはこれを検知してlocal/upgrade.phpの適切なアップグレードセクションを実行するためのアップグレードスクリプトを実行するよう管理者に促します。
-==== フックをインストールする Install hooks ====
+==== カスタム言語ストリング ====
+あなたは/local/langディレクトリ配下に独自の言語ファイルを配置して既存の[[開発者エリア/言語ストリング|言語ストリング]]をオーバーライドできます。
-The file '''local/install.php''' contains functions named '''localpreinst()''' and '''localpostinst()'''. These are called during the Mahara installation process; localpreinst() is called early during the installation process, and localpostinst() is called as the final step in the installation process.
+詳細は[[開発者エリア/言語ストリング#/localのカスタム言語ストリング]]をご覧ください。
-These methods are defined empty. You may override them to add your own code to the preinstall and postinstall process.
+==== ヘルプをカスタムヘルプファイルでオーバーライドする ====
+あなたは/local/langディレクトリ配下に独自のヘルプァイルを配置して既存のヘルプファイルのコンテンツをオーバーライドできます。
-==== DBフック DB hooks ====
+詳細は[[開発者エリア/言語ストリング#/local のカスタムヘルプファイル]]をご覧ください。
-The /local directory has its own "version.php", "install.xml", and "upgrade.php" files. These act similarly to how they would for a standard Mahara plugin. When Mahara is first being installed, any database structures defined in local/install.xml will be created, and the version number in local/version.php will be stored in the database (as the config value "localversion"). If the version in local/version.php is incremented, Mahara will detect this and prompt the admin to run the upgrade script, running any appropriate upgrade sections in local/upgrade.php.
+==== カスタムテーマオーバーライド ====
+あなたは/local/theme/templatesディレクトリをテーマの「テンプレート」ディレクトリとして配下にカスタムテーマを設置できます。同様にあなたはイメージのような静的資源を/local/theme/staticに設置してカスタマイズできます。詳細は[[Customising/Themes/1.10#Local_theme_overrides]]をご覧ください。
-==== カスタム言語ストリング Custom language strings ====
+このように/localディレクトリに置かれるテンプレートファイルはMahara 1.10以前のバージョンでは現在のテーマディレクトリの下、すべての親テーマの上に順に置かれていました。既存のページを上書きせずに新しいページを作成できる点で多くの場合において/localディレクトリは有用です。Mahara 1.10以前のバージョンではプラグインのテンプレートファイルはMaharaに同梱されているテンプレートであっても、/localディレクトリ経由ではカスタマイズできませんでした。現在、Mahara 1.10ではこれらの制限が取り除かれました。/local テーマコンテンツが最初に読み込まれることになり、/localにプラグインのテーマコンテンツを同梱可能となりました。
-You can override [[Developer_Area/Language_strings|language strings]] by placing lang files under /local/lang. This is particularly useful if you only need to change one or two language strings.
+==== /local/lib.php内の様々なフック関数 ====
+Maharaコードベースにはローカル「hook」関数の存在がチェックされる多くの場所を含みます。ローカル「hook」関数が存在する場合、この関数が実行されます。これはサイト管理者がMaharaの主要機能のコアコードを変更せずに変更を提供できることを意味します。
-See [[Developer_Area/Language_strings#Custom_lang_strings_in_.2Flocal]] for details.
+Mahara 1.10以降、これらすべては/local/lib.phpファイルのヘッダに文書化されています。以下、いくつかの主要部分です:
-==== ヘルプをカスタムヘルプファイルでオーバーライドする Override help Custom help files ====
+* local_can_remove_viewtype($viewtype): ユーザによる特定タイプのページ削除をブロックできます。
+* local_get_allowed_blocktypes($category, $view): ページビルダからブロックタイプカテゴリを削除するため使用できます。
-You can override the content of help filesHelp files can be customized by placing help files under /local/lang.
+* local_header_top_content(): 戻りデータはほとんどのページ最上部の「head」タグに表示されます。あなたに静止コンテンツの表示のみが必要な場合、Mahara 1.9現在、これは設定オプション「$cfg->additionalhtmlhead」 (lib/config-defaults.phpに記述) を使用して実現できます。
+* local_main_nav_update(&$menu): メインナビゲーションメニューのコンテンツを修正するため使用できます。
-See [[Developer_Area/Language_strings#Custom_help_files_in_.2Flocal]] for details.
+* local_right_nav_update(&$menu): サイドバーのコンテンツを修正するため使用できます。
+* local_register_submit(&$values): 事前登録フックです。$values['extra']に追加されるコンテンツは自動的にusr_registration.extra内のデータベースに保存されます。
-==== カスタムテーマオーバーライド Custom theme overrides ====
+* local_post_register($registration): 事前登録フックです。usr_registration.extraに保存されるデータの場所を意味します。これは検索可能であり現在登録中のユーザに適用できます。
+* local_init_user(): グローバル$USERオブジェクト初期化直後のページ読み込み時にコールされるフック関数です。
-You can provide custom theme templates under /local/theme/templates, as if this were the "templates" directory of a theme. Likewise, you can customize static assets like images by placing them under /local/theme/static. See [[Customising/Themes/1.10#Local_theme_overrides]]
-Prior to Mahara 1.10, template files placed in /local in this way were placed in order of precedence below the current theme, but above any parent themes. This made them mostly useful for supporting the creation of new pages, rather than overriding existing pages. Also prior to Mahara 1.10, the template files of plugins, even those that ship with Mahara, ''cannot'' be customized via the /local directory. As of Mahara 1.10 these restrictions have been lifted; /local theme contents come first in precedence, and /local can include theme contents for plugins.
-==== /local/lib.php の様々なフック関数　Miscellaneous hook functions in /local/lib.php ====
-The Mahara code base contains a number of places where the presence of a local "hook" function is checked for, and if present, this function is executed. These are meant to provide an easy method for site administrators to change core functionality of Mahara without changing core code.
-As of Mahara 1.10, all of these are documented in the header to the /local/lib.php file. Here are some of the highlights:
-* local_can_remove_viewtype($viewtype): Can be used to block users from being able to delete certain types of views
-* local_get_allowed_blocktypes($category, $view): Can be used to remove some blocktypes from the page builder.
-* local_get_allowed_blocktype_categories($view): Can be used to remove some blocktype categories from the page build.r
-* local_header_top_content(): Returned data is printed at the top of the "head" tag on most pages. (If you only need to print static content, as of Mahara 1.9 you can do this using the $cfg->additionalhtmlhead config option, described in lib/config-defaults.php)
-* local_main_nav_update(&$menu): Can be used to modify the contents of the main navigation menu
-* local_right_nav_update(&$menu): Can be used to modify the contents of the sidebar
-* local_register_submit(&$values): Pre-registration hook. Content added to $values['extra'] will be automatically stored in the database in usr_registration.extra
-* local_post_register($registration): Post-registration hook. Meant to be a place where data stored in usr_registration.extra can be retrieved and applied to the now-registered user.
-* local_init_user(): Hook function, called on each pageload immediately after the global $USER object is initiated.