A common module is a module integrated into Obliquid, it will be stored inside the common directory tree. The common directory tree will be overwritten by upgrades, so it's not advised to store anything there before agreeing with us.
It will be now explained the steps necessary to create a news module. First it will be necessary to add a row to the module table, but it can't be simply added to the database, because this row will have to be created by the next setup, and has to work for every possible table prefix. This is done by adding a row to common/configs/module.tpl file. In our case:
INSERT INTO {{$tprefix}}module VALUES (4, 'news',
'Simple content management for publishing purposes', '0.1', '2003-01-04',
'Stefano Locati', 'stefano@obliquid.it', 'www.obliquid.com', 'info@obliquid.it',
'Copyright (c) 2003 Obliquid', 'LGPL', 'common/docs/license.txt', 4, 'Y')This insert is here broken on several rows for convenience, but it has to be on a single line in module.tpl file, or the insert will fail. To activate the change, we have to go to a core module page, like "Page groups, pages, slots", and choose "Resets a table to default" in the left menu, select module and press ok. This operation will reload the module table. A new setup will do it too.
A module will also need php scripts and html templates, our news module php scripts will be in common/pages/news directory and our templates will be in common/templates/news directory. This two news directory has thus to be created, notice that this name is the same of the module. This is a mandatory rule.
A module will need an access point, generally this is done through core/nav slot. This is normally shown as a top icon bar, we will then need to find an appropriate icon that will be stored in common/images/news directory that we have to create for the purpose. We will store there a news.gif icon, of size 32x32 pixels.
We can now open common/pages/core/nav.php to add the new icon and text to the $navpages array.
$navpages["news_adm"] = array(_l("News Administration"),"common/images/news/news.gif");
Note that we need to call _l() to translate the popup text into the correct language.
We have then to decide when this news icon will be shown, and it will be to users that have the news_adm page. Since this security object still doesn't exist the icon won't be shown yet.
Therefore we open common/configs/security.tpl and add a row for the new news_adm page. We can just pick the next available ID number for this row. It will be a objtype='n' (Navigation Page). Be careful to make sure that you have the ':' in the right places. The demo site has three groups defined. g1 is Administrators g2 is Developers, and g3 is Customers. Since we want to permit both the Administrators and Developers to administer news, we need to add both to the security table.
INSERT INTO {{$tprefix}}security VALUES (14,':news_adm:','g1','n')
INSERT INTO {{$tprefix}}security VALUES (15,':news_adm:','g2','n')
Now we need this new security to really appear to continue our work. This can be done as we did before to reload the module table, but this time we need to reload the security table. Of course a new setup will reload this new values too.
We could do this also by logging on as pascal and going through the Security and Groups icon. But that would only change the database, and the next time the database got reloaded our changes would be gone.
Now, despite all this, clicking on the new icon will give an error, because we didn't create any news_adm page yet. This can be done by editing manually local/configs/config.xml or by using site configuration. We use the second way: click on Page groups, pages, slot icon and choose add a new page. Insert news_adm as name and news as group and don't modify the other two fields, then click on the ok icon: the new page is now created (empty).
To add core/nav slot in this page we go down to "Creates a new slot in page news_adm" window and type core/nav as name, center1 for position and none for block, leaving the other fields unchanged, then we can click on the ok icon. We can already test our page by clicking on it. It will have only the icon bar.
For example we can now add a core/changelang slot to the left by typing core/changelang for name, left2 for position, title for block and clicking ok. We also have to add the most important slot for this page: news/adm. We have to type news/adm for name, center2 for position and click ok. If we test the news_adm page now it will show two errors: this is because there is still no php script and no template file.
We start by creating a adm.php file inside common/pages/news directory, including the disclaimer too.
<?php
/* Obliquid - PHP/XML application framework for groupware websites.
* Copyright (C) 2003 Stefano Locati <info@obliquid.it>
*
* This library is free software; you can redistribute it and/or
* modify it under the terms of the GNU Lesser General Public
* License as published by the Free Software Foundation; either
* version 2.1 of the License, or (at your option) any later version.
*
* This library is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
* Lesser General Public License for more details.
*
* You should have received a copy of the GNU Lesser General Public
* License along with this library; if not, write to the Free Software
* Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
*/
/** News administration
* @version $Id: common_mod.xml,v 1.5 2004/02/11 00:38:31 vrtisworks Exp $
* @package news
*/
function news_adm_()
{
global $_obweb;
$_obweb->smblock->assign("title", _l("News Administration"));
}
?>
Then we create a template file called adm.tpl inside common/templates/news directory.
Now when we click on the icon, we still do not see anything. That is because we did not create any security access to the news/adm slot. Remember that there might be some slots on this page that everybody can see (such as core/nav), but not everybody should be allowed to get to news/adm. So we need to go back to security.tpl and add the two entries for news/adm.
INSERT INTO {{$tprefix}}security VALUES (31,'news/adm::','g1','s')
INSERT INTO {{$tprefix}}security VALUES (32,'news/adm::','g2','s')
Notice that these entries are type 's' (Slots). Now after we reload the security table, as explained before, we can click on the icon and see our work!