 |
Frequently Asked Questions v2
|
What is a module?
-----------------
You probably know slices - a part of database with its admin interface
which is able to manipulate with items/articles. The slices are very
configurable, so it can hold news or events as well as database of
links, organizations or members. Slices are great for presenting tabular
data of any type. On the oher hand, there are many cases, where we need
comletely different data structure, behavior of admin interface or
presentation layer. As example we could mention polls, petitions, ...
Because users of AA (including us) wants to manage such data in the same
(ActionApps) environment, we have to find the way, how to incorporate
such data administration into AA. The answer is modules.
It's hard to explain what modules are and how you can create it, because
the is no good example of working module, rihgt now. In fact, there are
two modules - module 'jump' and module 'site'. The Jump module is too
easy (it allows you just to jump to specified page of specified slice in
admin interface) and the site module is too complex and it is not fully
integrated into AA. That's why it is not commited into CVS at this moment.
What the module allows
----------------------
- allows you to create different admin interface for the module data
(You can replace Item Manager and Slice Admin by your own admin pages,
including left menu bar, ...
- allows you to use your own database tables
- allows you to use your own permissions in new module (there is general
permission system with standardized perm API defined, which provides
abstract layer for functions like AddPermObject, AddPermUser,... -
such functions then operates in backroud with LDAP, SQL, ...)
How modules apears to user in AA admin interface
------------------------------------------------
All modules which belogns to logged user are listed in 'Module
selectbox' which you uses for selection of slices, right now (well known
'Switch to' selectbox). The idea is, that in this selectbox then user
switch to administration of news of site XY, to administration of events
of site XY, and to administration of polls for this site. In fact the
slices now became just one of the modules incorporated into AA environment.
When user selects another module type in Module selectbox, then upper
navigation bar will be changed just slightly. User will see probably no
'Item Manager' as well as 'Slice Admin' menu options. (S)he will see
'Poll Manager' and 'Poll Admin', or maybe just Poll Manager (if we speak
about poll module as example).
How to create new module in APC Action Apps
-------------------------------------------
Basic steps, which is needed for module creation are:
1) copy the modules/module_TEMPLATE to the new directory and name it by
the name of module (just for clarity) (modules/poll for example).
2) open /include/constants.php3 and add new module in the $MODULES
array.
3) create database tables for the module and add the definition to
doc/aadb.sql and sql_update.php3
4) modify modedit.php3 script in your module directory - this script is
called after 'Add xy module' is pressed so there should be basic
module settings/creation options (as we already know from 'Slice
Admin' - slicedit.php3).
5) modify index.php3 script, which is the script, which apears after
user selects the module from 'Module selectbox' (for 'slice' module
such page is Item Manager.
6) insert new language file for the module to include/ directory (just
like en_poll_lang.php3), if you want to use module specific texts
(you probably will) (Note: all language files must be in include/
directory)
Done - module is created.
Before we go to detailed description of the steps, we have to mention
some facts, which maight be confusing.
I say, that slices are just on of the modules. That's true, but from
historical reasons there are some differences:
- the code for slice is not placed in module/ directory - it is placed
in admin/ and include/ directory instead
- name of slice configuration file is not modedit.php3, but it is
called slicedit.php3
- the id of the slice is hold in $slice_id variable. Better name for
this variable is module_id (as we use it in other modules). For now
just note, that the module_id is exactly the same as slice_id.
Let's describe the module creation steps in more detail (I will use (non
existant) 'poll' module as an example. Substitute all 'poll' words with
the name of your module, of course):
ad 1) copy module_TEMPLATE
--------------------------
In module_TEMPLATE directory are templates for all interesting scripts,
which we need for new module. So, create new directory (modules/poll/)
and copy there all files from modules/module_TEMPLATE. As steted abobe,
name of the new directory sholud be the same as the name of module.
ad 2) add module to constants.php3
----------------------------------
The only cyhange, which is need in constants.php3 script is to add new
record into $MODULES array. The array looks like:
$MODULES=array('S'=>array('name' => 'slice',
'directory' => AA_INSTAL_URL ."admin/",
'table' => 'slice',
'hide_create_module' => 1),
'W'=>array('name' => 'Site',
'directory' => AA_INSTAL_URL ."modules/site/",
'table' => 'site'),
'A'=>array('name' => 'MySQL Auth',
'directory'=>AA_INSTAL_URL ."modules/mysql_auth/"),
'table' => 'module',
'hide_create_module' => 1),
'J'=>array('name' => 'Jump inside AA control panel',
'directory' => AA_INSTAL_URL ."modules/jump/",
'table' => 'jump'));
There we see listed four modules in the example above. Each module is
identified by a letter. Let's choice any unused letter for new module -
we choose letter 'P' for poll module for example.
There are four values for each module:
- name - just a name of module as will be listed on 'Add module' page,
for example.
- directory - the name of directory, where index.php3 for this module is
stored (index.php3 script is the one, which will be
executed after user selects the module instance from
'Module selectbox' in admin interface). It is good idea to
specify the directory using AA_INSTAL_URL constant
- table - table parameter is just optional. You can specify main
database table of the module, so then you can call
GetModuleInfo() function in order to fill an info_array by
the values specific for selected module:
$poll_info = GetModuleInfo($module_id,'P');
Now you can access $poll_info['number_of_options'],
$poll_info['title'], ... when 'number_of_options' and 'title'
are fields of poll table.
- hide_create_module - set this optional option to true, if you want to
not show the module on 'Add module' page. This
option will be false for most modules.
The record to the $MODULES array for poll module could looks like:
'P' => array( 'name' => 'Poll',
'directory' => AA_INSTAL_URL ."modules/poll/",
'table' => 'poll'),
ad 3) create tables
-------------------
You will probably need the database table(s) for your module. Create it
in database and the table definition add to both:
a) doc/aadb.sql (used for new creation of new databases)
b) sql_updata.php3 script (used for database upgrades)
For clarity, prefix the new table names by the name of module (just like
table poll, poll_options or poll_votes)
ad 4) modify modedit.php3
-------------------------
modedit.php3 is the script, which is called when user on 'Add module'
page click on 'Add' for your module.
This script is used to create and modify module instance. There user
should set all main configuration options. To create such instance you
need to:
a) add a record into 'module' table (and maybe to module specific
table, just like 'poll', ...)
b) assign permissions for the module
ad a) add record into 'module' table
Module table is generalized version of slice table any module
instance (including slices) must have its recocord in module table.
The table have the following fields:
id char(16) NOT NULL,
# world wide unique module instance id. There we store packed
version of 32-digit hexadecimal number (you probably already
know
it from slices and its displaying
(<!--#include
virtual="/apc-aa/slice.php3?slice_id=763511f38a9b960c8e7a99f765e89ff9"
-->)).
The id is there stored packed to 16 characters long string by the
q_pack_id($module_id) function. If you are creating new module
instance, the new module_id should be generated by new_id() (both
functions in /include/util.php3 file). This id is foreign key for
module specific tables (such as poll table), where more
information in the instance is stored.
name char(100) NOT NULL,
# name to be displayed in 'Module selectbox' in admin interface
(Switch to:). From historical reasons it duplicates slice.name
for modules of 'slice' ('S') type
deleted smallint(5),
# boolean value to mark deleted modules. For new module you will
set it to '0'. From historical reasons it duplicates
slice.deleted for modules of 'slice' ('S') type
type char(16),
# module type - 'S' for slice, 'P' for polls (see already described
$MODULES variable in /include/constants.php3)
slice_url varchar(255),
# URL where user could view the module instance, if it is possible
for your module type. This is the url where user jumps after
(s)he click on 'View' in upper navigation bar in admin interface.
lang_file varchar(50),
# used language file for this module instance. Language files are
located in include directory (en_poll_lang.php3,
cz_poll_lang.php3) and they are described in paragraph 6)
created_at bigint(20),
# timestemp of module instance creation. We use unix timestamps -
use include/util.php3 funtion now(). This field should not be
user editable.
created_by varchar(255),
# user id of logged user. The id could be number (if you are using
SQL based permissons) or string like 'uid=honza,ou=People,ou=AA'
(if you are using LDAP permission system. In both cases you will
get such number in $auth->auth["uid"] object variable.
owner varchar(16),
# owner is the link (foreign key) to 'owner' database table
flag int(11) default '0'
# just a module flag. Not used yet. Fill it by '0'.
ad b) assign permissions for the module
The permission to the new instance will use the same functions as the
slice
- it will use AddPermObject($module_id, "slice"). The "slice" is
there from historical reasons and in fact much better name would
be "module", but we MUST use the "slice". Do NOT use any other
string then 'slice'!!!
- Note: you can (and in fact you should) redefine the meaning of
permission letters in permission string for the module (see
/include/perm_core.php3)
- If you want to assign some permissions to specified user, use
AddPerm($user_id, $module_id, 'slice', $perm), where $user_id is
the id described in section a) by the created_by field (see
above) and $perm is the permission letter(s) we mentioned in
'Note' above.
- If you do not assign any permission to any user, only superadmins
of AA will see the module instance in his 'Module selectbox' and
will be able to change it.
The admin interface of modedit.php3 should be inspired by the interface
of 'Slice Admin' (slicedit.php3). There should be upper navigation bar
(which could be slightly modified to better fit your module - see
navbar.php3) and possibly left navigation menu, if you need to split the
module configuration to more than one page.
ad 5) modify index.php3
-----------------------
index.php3 is the script, which apears after user selects the module
from 'Module selectbox'. The admin interface should be inspired by 'Item
Manager' for slice module. This is the main administration page for the
module - most users will probably have the permission to access this
page and only a few administrators will have the permission to access
configuration page - modedit.php3.
ad 6) create language file
--------------------------
Create the language file, where you will store all texts you use in
module. The language file should be named like en_poll_lang.php3,
cz_poll_lang.php3, ... (<language>_<module>_lang.php3). The language
file MUST be stored in include/ directory (just like all other language
files). The name of this file is filled in module.lang_file table field
as described in section 4).
In the language you can define as many language constants as you want,
but you MUST there define the LANG_FILE constant, where you fill the
name of language file:
define("LANG_FILE", "en_poll_lang.php3");
All others language constants are up to you.
Notes:
------
- You can create any file in your module directory, of course. If you
will use functions, prefix its name by Mod<module letter>_, so use
ModP_GetName(), ModP_Display(), ... functions, for example.
- It is good Idea to consult the features of new module on
apc-aa-general mailinglist, before you will start the
programming.
- Please, commit all created modules to CVS (ask us for write
permissions) or send the code to AA administrator.
- Write documentation for the module in order others would be able to
use it.
Last Edit: Aug 17 2011
<aafaq id=1687> ~ToDo: 1687 How to create new module? </aafaq>
This FAQ interface was developed
by Jason at Commons.ca
 |
APC
ActionApps is a free software content management system initiated by
the Association for Progressive Communications (APC)
APC - Internet and ICTs for social justice and development |