/
installation_function.html
80 lines (67 loc) · 2.65 KB
/
installation_function.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
---
layout: default
navPage: docs
heading: Installation Function
breadcrumbs:
- Module Development,/module_development/
- Form Tools 2,/module_development/index_ft2/
- Special Functions,/module_development/special_functions/
- Installation Function
prev: Special Functions,/module_development/special_functions/
next: Uninstallation Function,/module_development/uninstallation_function/
categories: module_development
---
{% include open_section.html nav='nav_module_development.html' selected='installation_function' nav_width=4 %}
<h3>Installation Function</h3>
<p>
This function must be named: <b>my_module__install()</b> (where <b>my_module</b> is
the module folder name). It takes a single parameter: the $module_id, passed to it from
the core code, in case you need it.
</p>
<p>
Here's a simple example of how this function is formatted:
</p>
{% codemirror php %}
/**
* My Module's installation function. This is automatically called by Form
* Tools on installation.
*
* @param integer $module_id
* @return array [0] true / false
* [1] success or error message
*/
function my_module__install($module_id)
{
global $g_table_prefix, $L;
// do anything you want here
return array($success, $message);
}
{% endcodemirror %}
<p>
The module ID is passed to the function in case you need that information. Otherwise you
can just ignore it.
</p>
<p>
The return value is important. It needs to be an array with two indexes. The first
indicates whether the installation was successful or not. If it's set to false, Form
Tools will halt the installation. The second parameter is what should be displayed to
the user - this is either a success or error message, depending on the first parameter.
Note: this second parameter does <b>not need to be included</b> for success messages.
By default, a successfully installed module will automatically display a message
informing the user of this with a "select this module" link. The second parameter,
if included, will override this default message. So to rely on the default message,
just pass an empty string as the second parameter, like so:
</p>
{% codemirror php %}
return array(true, "");
{% endcodemirror %}
<h3>What your install script DOESN'T need to contain</h3>
<p>
As mentioned, your custom installation function is called from within the Form Tools
core code. That code takes care of a lot of stuff you don't need to know about, including:
</p>
<ul>
<li>A new record for your module is created in the <b>modules</b> database table</li>
<li>The module menu is built and stored in the <b>module_menu_items</b> table.</li>
</ul>
{% include close_section.html %}