modules/snippets/PROGRAMMING.txt

$Id: PROGRAMMING.txt,v 1.2 2005/02/20 20:59:34 axel Exp $

SIMPLE RULES OF SNIPPET PROGRAMMING

Because snippet code executes in Drupal framework, then all Drupal API
available. Internally snippets are become as functions. You write
snippet code between <?php ... ?> and let name to snippet function (name
must be unique). During text filtering snippets codes inserts to text 
of messages as function definitions. Example:

1. You write snippet with code <?php phpinfo(); ?> and name it as 'example'
2. In text will inserted definition (function names always prefixed 
with 'snippet_'):
   <?php function snippet_example($SNIPPET_NAME, $SNIPPET_PARAMS,
                                  $SNIPPET_MACRO) { ?>
   <?php phpinfo(); ?>
   <?php } ?>
3. Definition inserted once, but calls to this function may be multiple
   in one message:
   [example] -> 
     <?php print_r(snippet_example('example', array(), 'example')); ?>
   [example|par1|par2] ->
     <?php print_r(snippet_example('example', array([0] => 'par1',
                                                    [1] => 'par2'),
                                              'example|par1|par2')); ?>

As you see parameters of macro transferred to your snippet as function
parameters and you may use them as any other PHP-variables inside you
code.

You should return text prepared by you snipped if want to display
results:

  return $output;

Though you may also directly print it from you snippet with print or echo.

Use static variables to transfer parameters between snippet calls.

Ability to use other snippets from snippet will added in future.

Also in future versions become next additional variables:

SNIPPET_FILES	(become in beta)
FULLTEXT	(become in beta)

Result of snippet will be formatted with filters which used you site,
of course 'Snippet macros' must be one of these filters else you get
PHP-source on output instead of result of execution.

See more useful examples of snippets in EXAMPLES.txt
1	$Id: PROGRAMMING.txt,v 1.2 2005/02/20 20:59:34 axel Exp $
2
3	SIMPLE RULES OF SNIPPET PROGRAMMING
4
5	Because snippet code executes in Drupal framework, then all Drupal API
6	available. Internally snippets are become as functions. You write
7	snippet code between <?php ... ?> and let name to snippet function (name
8	must be unique). During text filtering snippets codes inserts to text
9	of messages as function definitions. Example:
10
11	1. You write snippet with code <?php phpinfo(); ?> and name it as 'example'
12	2. In text will inserted definition (function names always prefixed
13	with 'snippet_'):
14	<?php function snippet_example($SNIPPET_NAME, $SNIPPET_PARAMS,
15	$SNIPPET_MACRO) { ?>
16	<?php phpinfo(); ?>
17	<?php } ?>
18	3. Definition inserted once, but calls to this function may be multiple
19	in one message:
20	[example] ->
21	<?php print_r(snippet_example('example', array(), 'example')); ?>
22	[example\|par1\|par2] ->
23	<?php print_r(snippet_example('example', array([0] => 'par1',
24	[1] => 'par2'),
25	'example\|par1\|par2')); ?>
26
27	As you see parameters of macro transferred to your snippet as function
28	parameters and you may use them as any other PHP-variables inside you
29	code.
30
31	You should return text prepared by you snipped if want to display
32	results:
33
34	return $output;
35
36	Though you may also directly print it from you snippet with print or echo.
37
38	Use static variables to transfer parameters between snippet calls.
39
40	Ability to use other snippets from snippet will added in future.
41
42	Also in future versions become next additional variables:
43
44	SNIPPET_FILES (become in beta)
45	FULLTEXT (become in beta)
46
47	Result of snippet will be formatted with filters which used you site,
48	of course 'Snippet macros' must be one of these filters else you get
49	PHP-source on output instead of result of execution.
50
51	See more useful examples of snippets in EXAMPLES.txt