History: Mods Details

            ! Mods Details
!! Morphology
Each Mod is defined by a type and a package name. the types are arbitrary strings to group mods in mods families. The initial set is composed of avatars, icons, menus, themes, languages, sqlupgrade, wikiplugins, features, services ... more types can be added with time, but please do not add wild types. New types should be only added after proper discussion with knowledgeable people (whatever that means for you).

A mod is managed by a control file with following characteristics :
* follows name convention type-name.info.txt
* stored in mods/Packages/ dir typically
* the syntax of this file is intended to be human-readable, composed by parameters and values
* each parameter block is separated by 2 line breaks
* the first line of parameter block is the parameter name, possibly ended by a colomn (:) which is stripped if present
* the following lines, until a blank one appear, is the value of the parameter
* the initial set of parameters is composed of : 
** __contributor__ : the login or name of the one that commits, can use the $Author$ cvs macro
** __revision__ : the incremental number of the version of the mod. it can follow the revision number $Revision$ from cvs but not necessarly
** __requires__ : the optional list of required mods by this mods. It must be one line by depend, each line must be of the form: type-name < | > | <= | >= | = revision (and you can have multiple revision tests in one line)
** __suggests__ : the optional list of suggesteds mods. Same syntax than __requires__.
** __conflicts__: the optional list of mods that conflict with this mod. Same syntax than __requires__.
** __lastmodif__ : the date of last version of the mod, using the macro $Date$
** __files__ : a list of all the files that compose the mod. One line per file, composed of the origin and the destination separated by a space. The origin is relative to mods/ and the destination relative too the tiki documentroot. Files in mods can be prepended with sample: prefix in which case they will be modified by the configuration at install time.
** __Description__ : an arbitrarily verbose (but not much) description of the functionalities of the mod
** __Docurl__ : the list of relevant urls (one per line) related to documentation of the mod
** __Devurl__ : list of urls used for the development of the mod (usually, but not mandatorily, in [http://mods.tiki.org])
** __Licence__ : the legal form under wish the mod is distributed. If not specified, follows the tikiwiki licence scheme
** __Author__ : the name, login or identifier of the author(s) of the mod. If it's a coolactive work, one name per line is accpetable.
** __Version__ : the list of restrictive version for which the mod is designed. If that field is absent, any version should be able to use the mod. ''(not functional yet)''
** __Changelog__ : the list of changes, descending, usually one line per change
** __Configuration__ : enables install-time setup of some values. One line per variable, composed of Label, name of the variable and default value from $_SERVER array (for example $HTTP_HOST will propose ~np~$_SERVER['HTTP_HOST']~/np~ as a default value in configuration screen). The configuration variables suubstituation will be processed only on files begining with "sample:" prefix in mods repository.
** __Configuration help__ : the text displayed on configuration screen at install time (remember to avoid empty lines as they are parameters separators).
** __help__ : a freeform text instruction about the mod installation and first use
** __sql-install__ : the list of sql command issued at install time, one command per line.
** __sql-remove__ : same as sql-install, but executed at removal time.
** __sql-upgrade__ : that's a special sql statement list. It's splited by version  numbers to which the upgrade sql statements apply. The version number has to be on a line prepended with a column. The lines below the version value will be associated to that version upgrade, so multiple upgrade can be run at once if needed.

The maintenance of the mods repository is managed by other text files that have to be present in the mods/Packages/ dir as well. Those files are indexes in CSV format, so they can be used by other tools. The indexes are following the conventions :
* name convention is that all indexes files begin with 00_list. and end with .txt so they are at the top of  the list when Packages content is sorted alphabetically
* each line in indexes is composed by strings enclosed with simple quotes and separated with commas
* the fields are 'type','mod name','revision','description','licence' (probably more will be added, but the order shouldn't change).
* of course the content of fields has to be addslashed (simple quotes preceeded by a backslash).
* there is differnt index files for different uses
** 00_list.txt : is the index of locally available mods. This index can be rebuidl locally by using the 'rebuild local list' link in tiki-mods.php
** 00_list.public.txt : is the index that is generated when you setup your mods to be able to be mods provider. It lists the mods that are available for other tikiwikis
** 00_list.xxxxxx.txt : is the index of remotely available from the sevrer configured in the tiki-mods_admin.php panel where xxxxxx is the urlencoded url of the server it comes from

!! for developers : mods.sh
In 1.9cvs you can find that script in doc/devtools/mods.sh. This script is recent and has only a few features, but the goal is to make possible to manage the mods only with it. Before use __edit this script__ to adapt the configuration to your environment, and when done you can launch it from your tiki root directory.
{CODE()}
Usage: ./doc/devtools/mods.sh <package_name> [copy|diff|install]

  copy : copy tiki files to mods
  diff : diff tiki files with mods
  install : copy mods files to tiki
  without 2nd arg, returns the list of files from package in tiki tree

  !!! note that this script only works with installed packages !!! 
  !!! (this is work in progress, use is quite limited for now) !!! 
{CODE}

!! How to add your own mods
Let's work a simple mods, a wikiplugin
!!! Get _mods
First get a CVS version of _mods from HEAD. From now on, all paths will be relative to the directory _mods.
!!! Create a wikiplugin
Create your plugin:
{CODE(colors=>php)}
<?php
/*
* $Header: /cvsroot/tikiwiki/_mods/wiki-plugins/dopplr/wiki-plugins/wikiplugin_dopplr.php,v 1.1 2007/12/20 23:37:10 franck Exp $
*
* Dopplr plugin. Add a Dopplr badge
*
* Syntax:
*
* {DOPPLR(badgeid=>id)}
* some content
* {DOPPLR}
*
*/
function wikiplugin_dopplr_help() {
return tra("Insert a dopplr.com badge on wiki page").":<br />~np~{DOPPLR(badgeid=>ID)}".tra("text")."{DOPPLR}~/np~";
}

function wikiplugin_dopplr($data, $params) {

extract ($params,EXTR_SKIP);
$badgeid = (isset($badgeid) && ctype_xdigit($badgeid)) ? "$badgeid" : "";

$begin = '<div id="dopplr-blog-badge"><sscript src="http://www.dopplr.com/blogbadge/script/'.$badgeid.'"></sscript></div>';
$data = "";
$end = "";
return $begin . $data . $end;
}
?>
{CODE}
Place it in __wiki-plugins/dopplr/wiki-plugins/wikiplugin_dopplr.php__

__Security__: ensure to test $params and $data so people cannot abuse these variables to compromise the site that runs this wikiplugin

Then create the following file __Packages/wikiplugins-dopplr.info.txt__
{CODE()}
contributor:
$Author: franck $

revision:
$Revision: 1.1 $

lastmodif:
$Date: 2007/12/20 23:37:10 $

files:
wiki-plugins/dopplr/wiki-plugins/wikiplugin_dopplr.php lib/wiki-plugins/wikiplugin_dopplr.php

author:
Franck

licence:
GNU/LGPL

Description:
Add a dopplr.com badge to a wiki page
{CODE}
add into the file __Packages/00_list.txt__ the line:
{CODE()}
'wikiplugins','dopplr','1.0','add a dopplr.com badge','GNU/LGPL'
{CODE}
!!Commit the wikiplugin
{CODE()}
cvs -z5 add wiki-plugins/dopplr
cvs -z5 add wiki-plugins/dopplr/wiki-plugins
cvs -z5 add wiki-plugins/dopplr/wiki-plugins/wikiplugin_dopplr.php
cvs -z5 add Packages/wikiplugins-dopplr.info.txt
cvs -z5 commit -m "Wikiplugin dopplr.com badge" Packages/wikiplugins-dopplr.info.txt Packages/00_list.txt wiki-plugins/dopplr/wiki-plugins/wikiplugin_dopplr.php
{CODE}
!!! Make it available
Go on irc://irc.freenode.net/#tikiwiki or send an e-mail to the developer list to have http://mods.tiki.org/ updated.

!! Mods evolution
The first version of mods feature is very basic, and will need to handle some more things :
* md5 signature of the tarball present in the control file
* management of scripted operation at install and remove time, for patching or anything. But anything being able to be anything by nature, it requires a good security attention and a non-risky context.
* adding more information in the control file
* possibility for having multiple author displayed in the mod details
* new type of mods for maintenance operations like upgrade, janitoring, cleaning, archiving, or anything that can be handled by sql commands, those mods are never installed and can be run at will
* languages modularisation, that would involve a new convention about translating mods-specific strings as well as gathering all strings in a common place for easy translation.
* styles modularization, by cutting the css in part, so mod can embed, as for language, the specific part needed for its use.
* Link to the installer to garantee a non-regressive upgrade from 1.8 or 1.9rc.
* development of a shell-based script for mods management, for easy administration and avoiding the perms change.
* maybe even development of a VB-based clickable tool for binboze users that reproduces the functionalities of the shell script cited above.
* find a way to manage the perms change for ftp-only users. Maybe the best way would be to use a ftp script to install mods on a remote server, using lftp on *nix or the vb-script for binboze victims.
* manage a dependancies system for linking installs
* add a way to update everything in a click
* manage a checking of existing tiki version to take in account the required minimal version for each mod
* remove the mod-application_menu.tpl so we can refer to the sql-based application menu (thhat can be changed easier by the mods installer
* change the features admin panel for it takes the features from the db rather than hardcoded, so mods can interact and add items in features admin panel.
* setup a new page for displaying the focus. The disply inside the list won't last long (as the list will grow).
Most of those evolutions should be ready before 1.9 final release.

---
mods system was initially designed by ((tw:mose)), use at your own risk and read the source code.

-=Related pages=-
* ((Mods))
* ((Mods User))
* ((Mods Admin))