Subversion Repositories ALCASAR

Rev

Details | Last modification | View Log

Rev Author Line No. Line
2770 rexy 1
phpSysInfo 3.1 - http://phpsysinfo.sourceforge.net/
2
===================================================
3
 
4
Document written by Michael Cramer (bigmichi1 at sourceforge.net)
5
 
6
!!Please read if you want to develop a plugin to understand our plugin system!!
7
 
8
 
9
Plugins
10
-------
11
 
12
Beginning with phpSysInfo 3.0, phpSysInfo can be extended by Plugins. So here is
13
a description that a developer of a plugin must take care of. Plugins can be
14
enabled through the `phpsysinfo.ini` in the PLUGINS variable. The name of the
15
plugin is essential for the function of the plugin system. Lets say you write a
16
plugin with the name 'pingtest', then this name is added to the PLUGINS
17
variable in `phpsysinfo.ini`. And this is also then the name which is everywhere in
18
the plugin system used, like creating the object, locate the needed files and
19
so on.
20
 
21
So if the name is now specified, phpSysInfo needs a special directory structure
22
to find the needed files. The directory structure for the example `pingtest`
23
plugin can be seen here:
24
 
25
```
26
-+ phpSysInfo root
27
 |
28
 +---+ plugins (directory in that plugins are installed)
29
 |   |
30
 |   +---+ pingtest (the real plugin directory, must have the same name like
31
 |   |   |            the plugin named in PLUGINS, else it won't be found)
32
 |   |   |
33
 |   |   +---+ js (directory in which the needed JavaScript file is located,
34
 |   |   |   |     to generate the html output out of the xml)
35
 |   |   |   # pingtest.js (the js file must have the same name, like the
36
 |   |   |                   plugin in PSI_PLUGINS with the extension js)
37
 |   |   +---+ css (directory in which the needed style sheet information are
38
 |   |   |   |      located, can exists, but it's up to the author)
39
 |   |   |   # pingtest.css (the css file must have the same name, like the
40
 |   |   |                    plugin in PSI_PLUGINS with the extension css)
41
 |   |   +---+ lang (directory where translations for the plugin are located)
42
 |   |   |   |
43
 |   |   |   # en.xml (at least an english translation file must exist)
44
 |   |   |
45
 |   |   # class.pingtest.inc.php (this is the core file of the plugin,
46
 |   |                              name must consists of 'class' +
47
 |   |                              name from PSI_PLUGINS + '.inc.php')
48
```
49
 
50
other files or directorys can be included in the plugin directory, but then
51
its up to the developer to include them in the plugin. So it might be possible
52
to have a 'gfx' directory in which some pics are located that are used in the
53
output.
54
 
55
If the directory structure is build up, then it's time to start programming.
56
 
57
Files
58
-----
59
 
60
An example implementation is the pingtest plugin, which is shipped with phpSysInfo
61
 
62
* en.xml - at least this file must exist to get the translation working, and the
63
         the first entry in this file is normally the headline of the plugin.
64
         So one translation migth exists everytime. Other translation files
65
         are also in the same directory like the `en.xml` file.
66
         The id's specified in the translation file SHOULD have the following
67
         look `plugin_hdd_status_001`. First we say that this is a plugin
68
         translation, then the name of plugin and at last a increasing number
69
         for each translation. Please create your id's in that way, so that
70
         other plugins don't redefine your translations. At the time of writing
71
         this, there is no check to verify the id's, so be carfull.
72
 
73
* pingtest.css - here can all custom style sheet informations written down. The
74
         names of the id's and classes SHOULD also begin, like the translation
75
         id's, with `'plugin_' + pluginname`. If thats not the case it might be
76
         possible that another plugin is overwriting your css definitions.
77
 
78
* class.pingtest.inc.php - this file MUST include a class with the plugin name
79
         and also this class MUST extend the 'psi_plugin' class. A check that
80
         such a class exist and also extends 'psi_plugin' will be included in
81
         the near future. And if the check fails the plugin won't be loaded.
82
         The psi_plugin class checks the existens of the js and the en.xml
83
         files. Also an extra configuration of the plugin is loaded
84
         automatically from `phpsysinfo.ini`, if present.
85
         Through the extension of the psi_plugin class there is a need to
86
         include at least two public function. These are the execute() function
87
         and the xml() function. Other functions can be exist, that depends on
88
         the plugin needs or the author of the class. The execute() function is
89
         called to get the required information that should be later included
90
         in the xml file. The xml() function is called when the xml output
91
         should be generated. This function must return a simplexml object. This
92
         object is then included in another xml at the right position or as a
93
         standalone xml. So there is no need to do some special things, only
94
         create a xml object for the plugin.
95
 
96
* pingtest.js - this file is called when the page is loaded. A block for the
97
        plugin is automatically created. This one is a div container with the
98
        id `'plugin_'+ pluginname ("plugin_pingtest")`. The entire output must be
99
        placed in that container.
100
        There is a helper function for creating the headline: buildBlock() that
101
        can be called. This function returns a string with the html code of the
102
        headline, this code can then be appended to the plugin block. The
103
        generated headline can provide a reload icon for an ajax request. Only
104
        the click action of that icon must be created. The id of this icon is
105
        `'reload_' + pluginname + 'Table' ("reload_pingtestTable")`.
106
        Everything that then is done to get the html output out of the xml is up
107
        to the author.
108
        To get the xml document the ajax request url is `'xml.php?plugin=' +
109
        pluginname (xml.php?plugin=pingtest)`. This xml includes only the xml
110
        from the plugin nothing more.
111
        The last two executed commands should/must be the translation call and
112
        the unhide of the filled div container.
113
        The translation function that needs to be called is named
114
        plugin_traslate() with one argument, that is the pluginname like in
115
        `PSI_PLUGINS (plugin_translate("pingtest");)`.
116
        To unhide the filled container call the .show() function of it.
117
        `$("plugin_" + pluginname).show() ($("plugin_hdd_stat").show())`.
118
 
119
FAQ
120
---
121
 
122
Q: Is the plugin system ready to use?
123
 
124
A: It can be used, but it might change slightly in the future, if there are some
125
   special needs.
126
 
127
SUGGESTION
128
----------
129
 
130
If anybody out there has some suggestions in improving the plugin system let us
131
know. We are looking forward to get some feedback, suggestions and patches and
132
more. Feel free to contact us on our website: http://phpsysinfo.sourceforge.net.
133
 
134
$Id: README_PLUGIN 463 2011-04-19 17:34:41Z namiltd $