Toon geavanceerde kennisVerbergen geavanceerde kennisPage Component Plugins
This plugin slot has been published as stable with ILIAS 4.4. The goal of the user interface plugin add new page element types inside the ILIAS page editor. The ILIAS page editor is the editor used in e.g. in Wikis, ILIAS learning modules or if you "Customize Pages" of courses or groups.
Please make sure that you have read the general plugin implementation documentation.
This slot is defined by the COPage Service of ILIAS and named "PageComponent". This means all plugins have to be installed into directories at:
Customizing/global/plugins/Services/COPage/PageComponent/<Plugin_Name>
The ID of the COPage Service is "copg", the ID of the slot is "pgcp". These are used as prefixes together with your plugin id for database tables and for language variable identifiers:
DB Table / Language VariablePrefixes: copg_pgcp_<Plugin_ID>_
Plugin Directory Structure
A page component plugin has the following minimum file/directory structure. If needed templates/sql/lang directories and files may be used (see general plugin documentation). Another language file than ilias_en.lang may be present instead.
<PluginName> (Directory) classes (Directory) class.il<PluginName>Plugin.php class.il<PluginName>PluginGUI.php lang (Directory) ilias_en.lang plugin.php |
Plugin Files
At the end of this page you will find an example implementation. We walk through the files of this implementation. The name of the plugin is "PCExample", so its location will be at:
Customizing/global/plugins/Services/COPage/PageComponent/PCExample
plugin.php
All plugins must include a plugin.php file.
<?php // alphanumerical ID of the plugin; never change this $id = "pcexample"; // code version; must be changed for all code changes $version = "0.0.3"; // ilias min and max version; must always reflect the versions that should // run with the plugin $ilias_min_version = "4.4.0"; $ilias_max_version = "4.4.999"; // optional, but useful: Add one or more responsible persons and a contact email $responsible = "Alexander Killing"; $responsible_mail = "alex.killing@gmx.de"; ?> |
classes/class.il<PluginName>Plugin.php
<?php include_once("./Services/COPage/classes/class.ilPageComponentPlugin.php"); /** * Example user interface plugin * * @author Alex Killing <alex.killing@gmx.de> * @version $Id$ * */ class ilPCExamplePlugin extends ilPageComponentPlugin { /** * Get plugin name * * @return string */ function getPluginName() { return "PCExample"; } /** * Get plugin name * * @return string */ function isValidParentType($a_parent_type) { if (in_array($a_parent_type, array("lm", "wpg"))) { return true; } return false; } /** * Get Javascript files */ function getJavascriptFiles($a_mode) { return array("js/pcexp.js"); } /** * Get css files */ function getCssFiles($a_mode) { return array("css/pcexp.css"); } } ?> |
The class must be derived from ilPageComponentPlugin
. You need to replace the two occurrences of "PCExample" by your plugin name in the code above first.
After that you need to implement a function isValidParentType($a_type)
that returns true or false, depending on whether your component should be activated for the parent type or not. These types can be found in the ILIAS database table copg_pobj_def
. Current values for ILIAS 4.4 are:
- Blog Postings: "blp"
- Data Collection Detailed Views: "dclf"
- Glossary Definitions: "gdf"
- ILIAS Learning Module Pages: "lm"
- Media Pool Content Snippets: "mep"
- Portfolio Pages: "prtf"
- Portfolio Template Pages: "prtt"
- SCORM Editor Pages: "sahs"
- Test Question Hint Pages: "qht"
- Test Question Pages: "qpl"
- Test Generic Feedback Pages: "qfbg"
- Test Specific Feedback Pages: "qfbs"
- Wiki Pages: "wpg"
- Login Pages: "auth"
- Container (Course, Group, Folder, Category) Pages: "cont"
- Imprint: "impr"
- Shop Page: "shop"
- Page Template Page: "stys"
The example above only activates the component type for type "lm" (ILIAS learning module pages).
If your plugin needs and Javascript or CSS files to be included in HTML output, use the functions getJavacriptFiles()
and getCssFiles()
as shown above.
With ILIAS 5.2 the methods getJavascriptFiles($a_mode) and getCssFiles($a_mode) get the output mode passed as a parameter. This has been done for streamlining purposes (internal page components get this parameter already) and to allow optimization regarding the included files. Output modes are:
IL_PAGE_PRESENTATION (presentation)
IL_PAGE_EDIT (page editing)
IL_PAGE_PREVIEW (page preview while editing)
IL_PAGE_OFFLINE (html export)
IL_PAGE_PRINT (print view)
Changes in ILIAS 8
The onDelete() method got a third parameter $move_operation, which is set to true, if the deletion is done as parte of a move/cut/paste operation.
1 2 3 4 5 6 7 8 9 10 11 12 | /** * This function is called before the page content is deleted * @param array $a_properties properties saved in the page (will be deleted afterwards) * @param string $a_plugin_version plugin version of the properties * @param bool $move_operation true, if the delete is part of a move operation (cut for paste, move, ...) */ public function onDelete( array $a_properties, string $a_plugin_version, bool $move_operation = false ): void { } |
Please note that this method only indicates that elements are removed from the current page content. The elements will still be parts of the page history.
classes/class.il<PluginName>PluginGUI.php
This class must be derived from ilPageComponentPluginGUI
. The following functions must be implemented:
- executeCommand: This function executes all commands routed to the class.
- insert: This function must generate the creation dialog. It must use the method
$this->addCreationButton($form);
for adding a button that saves this initial form. - create: This function uses the form input to create the element.
- edit: This function must generate the editing dialog.
- getElementHTML: This function must return the HTML that should be included in the page.
<?php include_once("./Services/COPage/classes/class.ilPageComponentPluginGUI.php"); /** * Example user interface plugin * * * @author Alex Killing <alex.killing@gmx.de> * @version $Id$ * @ilCtrl_isCalledBy ilPCExamplePluginGUI: ilPCPluggedGUI */ class ilPCExamplePluginGUI extends ilPageComponentPluginGUI { /** * Execute command * * @param * @return */ function executeCommand() { global $ilCtrl; $next_class = $ilCtrl->getNextClass(); switch($next_class) { default: // perform valid commands $cmd = $ilCtrl->getCmd(); if (in_array($cmd, array("create", "save", "edit", "edit2", "update", "cancel"))) { $this->$cmd(); } break; } } /** * Form for new elements */ function insert() { global $tpl; $form = $this->initForm(true); $tpl->setContent($form->getHTML()); } /** * Save new pc example element */ public function create() { global $tpl, $lng, $ilCtrl; $form = $this->initForm(true); if ($form->checkInput()) { $properties = array( "value_1" => $form->getInput("val1"), "value_2" => $form->getInput("val2") ); if ($this->createElement($properties)) { ilUtil::sendSuccess($lng->txt("msg_obj_modified"), true); $this->returnToParent(); } } $form->setValuesByPost(); $tpl->setContent($form->getHtml()); } /** * Edit * * @param * @return */ function edit() { global $tpl; $this->setTabs("edit"); $form = $this->initForm(); $tpl->setContent($form->getHTML()); } /** * Update * * @param * @return */ function update() { global $tpl, $lng, $ilCtrl; $form = $this->initForm(true); if ($form->checkInput()) { $properties = array( "value_1" => $form->getInput("val1"), "value_2" => $form->getInput("val2") ); if ($this->updateElement($properties)) { ilUtil::sendSuccess($lng->txt("msg_obj_modified"), true); $this->returnToParent(); } } $form->setValuesByPost(); $tpl->setContent($form->getHtml()); } /** * Init editing form * * @param int $a_mode Edit Mode */ public function initForm($a_create = false) { global $lng, $ilCtrl; include_once("Services/Form/classes/class.ilPropertyFormGUI.php"); $form = new ilPropertyFormGUI(); // value one $v1 = new ilTextInputGUI($this->getPlugin()->txt("value_1"), "val1"); $v1->setMaxLength(40); $v1->setSize(40); $v1->setRequired(true); $form->addItem($v1); // value two $v2 = new ilTextInputGUI($this->getPlugin()->txt("value_2"), "val2"); $v2->setMaxLength(40); $v2->setSize(40); $form->addItem($v2); if (!$a_create) { $prop = $this->getProperties(); $v1->setValue($prop["value_1"]); $v2->setValue($prop["value_2"]); } // save and cancel commands if ($a_create) { $this->addCreationButton($form); $form->addCommandButton("cancel", $lng->txt("cancel")); $form->setTitle($this->getPlugin()->txt("cmd_insert")); } else { $form->addCommandButton("update", $lng->txt("save")); $form->addCommandButton("cancel", $lng->txt("cancel")); $form->setTitle($this->getPlugin()->txt("edit_ex_el")); } $form->setFormAction($ilCtrl->getFormAction($this)); return $form; } /** * Cancel */ function cancel() { $this->returnToParent(); } /** * Get HTML for element * * @param string $a_mode (edit, presentation, preview, offline)s * @return string $html */ function getElementHTML($a_mode, array $a_properties, $a_plugin_version) { $pl = $this->getPlugin(); $tpl = $pl->getTemplate("tpl.content.html"); //var_dump($a_properties); foreach ($a_properties as $name => $value) { $tpl->setCurrentBlock("prop"); $tpl->setVariable("TXT_PROP", $pl->txt("property")); $tpl->setVariable("PROP_NAME", $name); $tpl->setVariable("PROP_VAL", $value); $tpl->parseCurrentBlock(); } $tpl->setVariable("TXT_VERSION", $pl->txt("content_plugin_version")); $tpl->setVariable("TXT_MODE", $pl->txt("mode")); $tpl->setVariable("VERSION", $a_plugin_version); $tpl->setVariable("MODE", $a_mode); return $tpl->get(); } /** * Set tabs * * @param * @return */ function setTabs($a_active) { global $ilTabs, $ilCtrl; $pl = $this->getPlugin(); $ilTabs->addTab("edit", $pl->txt("settings_1"), $ilCtrl->getLinkTarget($this, "edit")); $ilTabs->addTab("edit2", $pl->txt("settings_2"), $ilCtrl->getLinkTarget($this, "edit2")); $ilTabs->activateTab($a_active); } /** * More settings editing * * @param * @return */ function edit2() { global $tpl; $this->setTabs("edit2"); ilUtil::sendInfo($this->getPlugin()->txt("more_editing")); } } ?> |
Please note that the line * @ilCtrl_isCalledBy ilPCExamplePluginGUI: ilPCPluggedGUI
is important to make your plugin work (replace ilPCExamplePluginGUI
with your plugin class name. This information will be parsed by ILIAS each time you force the plugin to be updated by increasing its version number.
Get Example
You will find an example for the latest releases at https://github.com/ILIAS-eLearning/TestPageComponent
Please report any bugs to our bug tracker.