modules/reptag/DEVELOPER.txt

*****************************************************************************
Name: reptag developer documentation
Author: Thilo Wawrzik <drupal at profix898 dot de>
*****************************************************************************
This is a developer info on howto create a .tags module for reptag
and howto use the reptag-provided API to work with tags.
***************************************************************************** 
WRITING REPTAG .TAGS MODULES

function _reptag_sample_init($context) {
  return array(
    "#\{MYTEXT}#i"           => "This is replacement text",
    "#\{MYTIME}#i"           => date('H:i:s'),
    "#{MYFUNC}#i"            => _reptag_sample_myfunc(),
  );
}  

The array returned from _reptag_xxx_init contains all the replacement
definitions. Since the $reptags array is processed by preg_replace()
you should format (at least) the left side in a regexp compatible
format. 'sample' is to be replaced with the name of the .tags module. 

You can also provide replacement tags that are dependent on the node
they occur in. Variable $context contains all information about the
node/text currently processed. Look at node.tags for a working example
on that. This focuses on modules for other node types (e.g. flexinode)
to provide a similar functionality as node.tags. 
 
function _reptag_sample_info() {
  return array(t('Sample .tags file'), FALSE);
}

The array returned from _reptag_xxx_info contains a short description
on what this module does and/or what tags it exports. The text appears
under modules on the reptag settings pages. The second element is to
distinguish 'static' and 'dynamic' module tags (TRUE = static, FALSE =
dynamic). All modules using the old syntax without TRUE/FALSE are
assumed 'dynamic'. Static modules contain (invariant) replacement
tags, which do not change with the time or user on every view. With
partial cache feature enabled these tags are replaced only once when
the node form is submitted (-> 'About Partial Cache' in README.txt).

function _reptag_sample_help() {
  return array(
    "{MYTEXT}"           => "This is replacement text",
    "{MYTIME}"           => date('H:i:s'),
    "{MYFUNC}"           => 'return of the function',
  );
}

The array returned from _reptag_xxx_help should be formatted to create
a sample representation of the tags available in the current module.
What means 'left-side' entries should be reduced to {..} form and the
corresponding 'right-side' values must always generate meaningful
output. The array is presented to the user when he/she creates or
edits a node (on node form) under 'Rep[lacement]Tags - Help' section.

function _reptag_sample_require() {
  return TRUE;
}

Some of the modules may depend on other modules, libraries or PEAR
packages. For example the wiki Modul needs Text_Wiki (PEAR) to be
available on the server. You can check your prerequisites in this
function. When _reptag_xxx_require returns FALSE the module is
automatically disabled. Additionally a warning is shown when the admin
tries to enable the module on the modules settings page.

function _reptag_sample_process($text, $tags, $context) {
  //override default process procedure
  return $text;
}

By default reptags are processed with preg_replace(). Sometimes it can
be helpful (or necessary) to use a specialised processing function
instead. When such function is defined in your module it simply
overrides the reptag's default processing unit. $text contains the
content to be processed, $tags is the array defined in the module's
_init() function and $context provides direct access to the $node
object (when processing nodes only) and must be used carefully.

function _reptag_sample_myfunc() {
  return '<strong>my function test</strong>';
}

You can code and run user-defined procedures and replace a tag with
their output. In sample.tags_ the tag {MYFUNC} is replaced with
'<strong>my function test</strong>', the return value of
_reptag_sample_myfunc().

*****************************************************************************
EXPOSING FUNCTIONALITY TO REPTAG FROM EXISTING DRUPAL MODULES

It is possible to expose tags from other Drupal modules to reptag.
What means you can add functionality to reptag from your existing
module without the need to write a whole new .tags module. To archieve
that 2 hooks have been intoduced:

The first is hook_reptag() and MUST be implemented by your module.

function hook_reptag($op, $context = NULL) {
  switch($op) {
    case 'info':
      return array(t('API (Sample Implementation)'), TRUE);
    case 'help':
      return array("{API}Text{/API}" => "<a href=\"...\">Text</a>");
    case 'init':
      return array("#{API}(.*?){/API}#s" => "<a href='...'>\\1</a>");
  }
}

The arguments and return values are very similar to the .tags modules.
Instead of _reptag_xxx_hook in .tags module you simply return the
arrays from from hook_reptag($op == 'hook').

Where a .tags module implements _reptag_xxx_process a Drupal module
(optionally) implements hook_reptag_process() using the same
parameters.

function hook_reptag_process($text, $tags, $context = NULL) {
  return $text;
}

*****************************************************************************
CALL REPTAG TO PROCESS USER CONTENT DIRECTLY

With a recent Drupal 6 version of reptag you can use replacements from
within every module. Simply call the reptag_replace() wrapper:

if (function_exists('reptag_replace')) {
  $text = '[b]bold[/b]';
  $text = reptag_replace($text);
  echo $text;
}

reptag_replace() assumes that you want to process static replacement
tags only. Use reptag_replace($text, TRUE) to override this behaviour.
It also passes the current user's uid by default.

In case you need a more flexible alternative to reptag_replace() use
reptag_process() directly. You only need to pass the required
parameters.

if (function_exists('reptag_process')) {
  $param->uid = 0;              // 0 or any uid
  $param->text = &$body;        // pass by reference
  reptag_process($param, array('text'));
  echo $body;                   // print output
}

if (function_exists('reptag_process')) {
  $param->uid = 0;              // 0 or any uid
  $param->text = '[b]bold[/b]'; // or pass string directly
  reptag_process($param, array('text'));
  echo $param->text;            // print output
}

uid is used to determine permissions (and therefore available tags).
It should be set to 0 (anonymous user) if no special permissions are
required. Be careful with 'dynamic' .tags modules (e.g. node.tags).
Some tags depend on the $node/$context object which is not necessarily
available!

By default all tags, what means static and dynamic replacement tags,
are used in reptag_process(). If you want to process with static or
dynamic tags only, you can set the third parameter accordingly. (!The
default behaviour is different from reptag_replace().) If you need to
select the modules to use directly you can set the fourth parameter.

Take a look at the inline docs of reptag_process.inc to get more
details on the parameters for reptag_process().

*****************************************************************************
SOME GENERAL IDEAS

1. I decided to keep the .tags modules concept. There is no reason IMO
to add a dozen modules to Drupal's modules page whose sole purpose is
to serve reptag internally. Instead hooks_reptag is a supplement for
existing Drupal modules to expose functionality to reptag.

2. Reptag uses a module registry (table reptag_registry) to manage the
available modules. The registry brings several advantages over older
reptag versions: #1) reduced memory footprint because only required
module are included #2) faster execution / less overhead (only one db
query and additional access check instead of iterating over all
modules) #3) configurable order of module processing (weight concept)
#4) simple and unified code to work with .tags modules and other
module exported tags

3. All the .tags modules live in the private _reptag_xxx_ namespace
(e.g. _reptag_mymodule_hook()) to avoid namespace collision issues.

*****************************************************************************
Hope this helps. Please send an email to <drupal at profix898 dot de>
to share your .tags modules with other users. You are always welcome
to ask for further assistance.
1	*****************************************************************************
2	Name: reptag developer documentation
3	Author: Thilo Wawrzik <drupal at profix898 dot de>
4	*****************************************************************************
5	This is a developer info on howto create a .tags module for reptag
6	and howto use the reptag-provided API to work with tags.
7	*****************************************************************************
8	WRITING REPTAG .TAGS MODULES
9
10	function _reptag_sample_init($context) {
11	return array(
12	"#\{MYTEXT}#i" => "This is replacement text",
13	"#\{MYTIME}#i" => date('H:i:s'),
14	"#{MYFUNC}#i" => _reptag_sample_myfunc(),
15	);
16	}
17
18	The array returned from _reptag_xxx_init contains all the replacement
19	definitions. Since the $reptags array is processed by preg_replace()
20	you should format (at least) the left side in a regexp compatible
21	format. 'sample' is to be replaced with the name of the .tags module.
22
23	You can also provide replacement tags that are dependent on the node
24	they occur in. Variable $context contains all information about the
25	node/text currently processed. Look at node.tags for a working example
26	on that. This focuses on modules for other node types (e.g. flexinode)
27	to provide a similar functionality as node.tags.
28
29	function _reptag_sample_info() {
30	return array(t('Sample .tags file'), FALSE);
31	}
32
33	The array returned from _reptag_xxx_info contains a short description
34	on what this module does and/or what tags it exports. The text appears
35	under modules on the reptag settings pages. The second element is to
36	distinguish 'static' and 'dynamic' module tags (TRUE = static, FALSE =
37	dynamic). All modules using the old syntax without TRUE/FALSE are
38	assumed 'dynamic'. Static modules contain (invariant) replacement
39	tags, which do not change with the time or user on every view. With
40	partial cache feature enabled these tags are replaced only once when
41	the node form is submitted (-> 'About Partial Cache' in README.txt).
42
43	function _reptag_sample_help() {
44	return array(
45	"{MYTEXT}" => "This is replacement text",
46	"{MYTIME}" => date('H:i:s'),
47	"{MYFUNC}" => 'return of the function',
48	);
49	}
50
51	The array returned from _reptag_xxx_help should be formatted to create
52	a sample representation of the tags available in the current module.
53	What means 'left-side' entries should be reduced to {..} form and the
54	corresponding 'right-side' values must always generate meaningful
55	output. The array is presented to the user when he/she creates or
56	edits a node (on node form) under 'Rep[lacement]Tags - Help' section.
57
58	function _reptag_sample_require() {
59	return TRUE;
60	}
61
62	Some of the modules may depend on other modules, libraries or PEAR
63	packages. For example the wiki Modul needs Text_Wiki (PEAR) to be
64	available on the server. You can check your prerequisites in this
65	function. When _reptag_xxx_require returns FALSE the module is
66	automatically disabled. Additionally a warning is shown when the admin
67	tries to enable the module on the modules settings page.
68
69	function _reptag_sample_process($text, $tags, $context) {
70	//override default process procedure
71	return $text;
72	}
73
74	By default reptags are processed with preg_replace(). Sometimes it can
75	be helpful (or necessary) to use a specialised processing function
76	instead. When such function is defined in your module it simply
77	overrides the reptag's default processing unit. $text contains the
78	content to be processed, $tags is the array defined in the module's
79	_init() function and $context provides direct access to the $node
80	object (when processing nodes only) and must be used carefully.
81
82	function _reptag_sample_myfunc() {
83	return '<strong>my function test</strong>';
84	}
85
86	You can code and run user-defined procedures and replace a tag with
87	their output. In sample.tags_ the tag {MYFUNC} is replaced with
88	'<strong>my function test</strong>', the return value of
89	_reptag_sample_myfunc().
90
91	*****************************************************************************
92	EXPOSING FUNCTIONALITY TO REPTAG FROM EXISTING DRUPAL MODULES
93
94	It is possible to expose tags from other Drupal modules to reptag.
95	What means you can add functionality to reptag from your existing
96	module without the need to write a whole new .tags module. To archieve
97	that 2 hooks have been intoduced:
98
99	The first is hook_reptag() and MUST be implemented by your module.
100
101	function hook_reptag($op, $context = NULL) {
102	switch($op) {
103	case 'info':
104	return array(t('API (Sample Implementation)'), TRUE);
105	case 'help':
106	return array("{API}Text{/API}" => "<a href=\"...\">Text</a>");
107	case 'init':
108	return array("#{API}(.*?){/API}#s" => "<a href='...'>\\1</a>");
109	}
110	}
111
112	The arguments and return values are very similar to the .tags modules.
113	Instead of _reptag_xxx_hook in .tags module you simply return the
114	arrays from from hook_reptag($op == 'hook').
115
116	Where a .tags module implements _reptag_xxx_process a Drupal module
117	(optionally) implements hook_reptag_process() using the same
118	parameters.
119
120	function hook_reptag_process($text, $tags, $context = NULL) {
121	return $text;
122	}
123
124	*****************************************************************************
125	CALL REPTAG TO PROCESS USER CONTENT DIRECTLY
126
127	With a recent Drupal 6 version of reptag you can use replacements from
128	within every module. Simply call the reptag_replace() wrapper:
129
130	if (function_exists('reptag_replace')) {
131	$text = '[b]bold[/b]';
132	$text = reptag_replace($text);
133	echo $text;
134	}
135
136	reptag_replace() assumes that you want to process static replacement
137	tags only. Use reptag_replace($text, TRUE) to override this behaviour.
138	It also passes the current user's uid by default.
139
140	In case you need a more flexible alternative to reptag_replace() use
141	reptag_process() directly. You only need to pass the required
142	parameters.
143
144	if (function_exists('reptag_process')) {
145	$param->uid = 0; // 0 or any uid
146	$param->text = &$body; // pass by reference
147	reptag_process($param, array('text'));
148	echo $body; // print output
149	}
150
151	if (function_exists('reptag_process')) {
152	$param->uid = 0; // 0 or any uid
153	$param->text = '[b]bold[/b]'; // or pass string directly
154	reptag_process($param, array('text'));
155	echo $param->text; // print output
156	}
157
158	uid is used to determine permissions (and therefore available tags).
159	It should be set to 0 (anonymous user) if no special permissions are
160	required. Be careful with 'dynamic' .tags modules (e.g. node.tags).
161	Some tags depend on the $node/$context object which is not necessarily
162	available!
163
164	By default all tags, what means static and dynamic replacement tags,
165	are used in reptag_process(). If you want to process with static or
166	dynamic tags only, you can set the third parameter accordingly. (!The
167	default behaviour is different from reptag_replace().) If you need to
168	select the modules to use directly you can set the fourth parameter.
169
170	Take a look at the inline docs of reptag_process.inc to get more
171	details on the parameters for reptag_process().
172
173	*****************************************************************************
174	SOME GENERAL IDEAS
175
176	1. I decided to keep the .tags modules concept. There is no reason IMO
177	to add a dozen modules to Drupal's modules page whose sole purpose is
178	to serve reptag internally. Instead hooks_reptag is a supplement for
179	existing Drupal modules to expose functionality to reptag.
180
181	2. Reptag uses a module registry (table reptag_registry) to manage the
182	available modules. The registry brings several advantages over older
183	reptag versions: #1) reduced memory footprint because only required
184	module are included #2) faster execution / less overhead (only one db
185	query and additional access check instead of iterating over all
186	modules) #3) configurable order of module processing (weight concept)
187	#4) simple and unified code to work with .tags modules and other
188	module exported tags
189
190	3. All the .tags modules live in the private _reptag_xxx_ namespace
191	(e.g. _reptag_mymodule_hook()) to avoid namespace collision issues.
192
193	*****************************************************************************
194	Hope this helps. Please send an email to <drupal at profix898 dot de>
195	to share your .tags modules with other users. You are always welcome
196	to ask for further assistance.