README.md
1# COPage
2
3Be warned. This component is one of the oldest in ILIAS with lots of complexity and little to none modern concepts. Dealing with it will be not the top software development experience for you.
4
5Feel free to make any pull requests to the ROADMAP.md to document pain points you would like to have being addressed in the future.
6
7## Consumer Documentation
8
9This component implements the ILIAS page editor as being used e.g. in learning modules, wikis, content pages in courses and other containers.
10
11Unfortunately the component does not offering a well defined API, instead using it mainly depends on extending a set of base classes.
12
13### [WIP] Using the page component in another component
14
15In order to use the page component in your component you first need to extend your `modules.xml` or `service.xml`.
16
17```
18 <copage>
19 <pageobject parent_type="{PARENT_TYPE}" class_name="{BASIC_CLASS_NAME}" directory="classes"/>
20 </copage>
21```
22
23The `{PARENT_TYPE}` should be unique through the ILIAS code base, e.g. this could be the module repository type of your component.
24
25You will need implement new classes in your component that derive from these classes of the COPage component:
26
27* `ilPageObject`
28* `ilPageObjectGUI`
29* `ilPageConfig`
30
31The class files should be located in the directory stated in `modules.xml` or `service.xml` (in this examples `classes`).
32
33* `class {BASIC_CLASS_NAME} extends \ilPageObject`
34* `class {BASIC_CLASS_NAME}GUI extends \ilPageObjectGUI`
35* `class {BASIC_CLASS_NAME}Config extends \ilPageObjectConfig`
36
37**class {BASIC_CLASS_NAME} extends \ilPageObject**
38
39This class should overwrite method `getParentType()` and returned the value specified in your `modules.xml` or `service.xml`.
40
41```
42/**
43 * @inheritdoc
44 */
45public function getParentType()
46{
47 return `{PARENT_TYPE}`;
48}
49```
50
51Please do not overwrite the constructor of this class.
52
53**class {BASIC_CLASS_NAME}GUI extends \ilPageObjectGUI**
54
55The weak point of this class is also its constructor. You should overwrite it in order to pass your parent type in the following way:
56
57```
58 function __construct($a_id = 0, $a_old_nr = 0, $a_prevent_get_id = false, $a_lang = '')
59 {
60 ...
61 parent::__construct('{PARENT_TYPE}', $a_id, $a_old_nr, $a_prevent_get_id, $a_lang);
62 ...
63 }
64```
65
66We might declare the constructor final in the base class in the future to enable a factory for these classes as well.
67
68**class {BASIC_CLASS_NAME}Config extends \ilPageObjectConfig**
69
70This class is used to enable/disable different features of the page (editor). You should overwrite its `init()` method:
71
72```
73/**
74 * @inheritdoc
75 */
76public function init()
77{
78 $this->setEnableInternalLinks(...);
79 ...
80}
81```
82
83**Embedding in ilCtrl control flow**
84
85Depending on where you want to use the presentation or editing features of the component, you will need to init and embed your {BASIC_CLASS_NAME}GUI in your `executeCommand()` methods.
86
87A good example for how this can be done is `Modules/ContentPage/classes/class.ilContentPagePageCommandForwarder.php`.
88
89
90## [WIP] Internal Documentation
91
92### Data
93
94The page editor stores data in XML format that needs to validate against the latest `xml/ilias_pg_x_x.dtd` (ILIAS main directory). This data is being stored in table `page_object` handled by class `ilPageObject`.
95
96### Rendering
97
98The main content rendering currently happens in class `ilPageObjectGUI` which transforms the XML using `./xsl/page.xsl` and a lot of post processing afterwards.
99
100### Page Content Components
101
102...
103
104### Multi-Language Support
105
106Multi language support has added an additional dimension of complexity to the content page component.
107
108Multi language support depends always on the parent repository object.
109
110**Basics**
111
112* new table `copg_multilang`: defines default language per repository obj id (-> "-" records)
113* all `page_object` records with "-" in `lang` field represent the default language (value is not set in page_object -> no dependent tables need to be updated)
114* table `copg_multilang_lang` contains all other languages supported by the repository object