modules/ulink/DEVELOPER.txt

******************************************************************************
                     D R U P A L    M O D U L E
******************************************************************************
Name: uLink developer documentation
Author: Gartheeban Ganeshapillai 
        AKA garthee at drupal <garthee at gmail dot com>
Dependencies: filter.module, comment.module(optional), tokens.module(optional)
Required by: uAuto.module, ulink_gallery.module, ulink_imagecache.module

******************************************************************************
This document explains howto develop modules to extend the rendering
and configuring the default rendering through phpmode.

******************************************************************************
WRITING MODULES TO EXTEND ULINK

When it is required  to write a new module
--------------------------------------------------------------------
Often by configuring the default implementation provided by ulink
and using hard code you could obtain the needed output. In specific cases but
trivial, where it is not adequate, users can go for Macro mode or PHPmode 
(explained below).

However, there will be highly specific and complex situations where PHPmode 
won't suit the need. ulink_gallery.module and ulink_imagecache.module address
such cases, where they extend the ulink-functions by implementing the hooks.

Available hooks to be implemented
--------------------------------------------------------------------
1. function hook_ulink_*type*($link, $object=NULL)
2. function hook_ulink_*type*_settings()
3. function hook_ulink_*type*_info()

here *type* can be node, comment, user, image or files.

After providing the module.info file, it is enough to provide only
the first function ie. hook_ulink_*type*, and it is NECESSARY. 
Implementation of other two functions is optional.


hook_ulink_*type*($link, $object=Null)
--------------------------------------------------------------------
Provides the html code of the output by making use out of 

return: HTML code of the output
parameters:
  $link - array contains information about the target link
	  $link['text'] = text to be referenced
		$link['path'] = user entered path of the link, eg: node/44
		$link['type'] = type of the target, eg: image, node
		$link['mime'] = extension of the target if it is supplied,
                    else contains the user entered path
		$link['title'] = title to the link, if it is specified in attributes,
		                else equivalent to 'text'
    $link['alt'] = title to the link, if it is specified in attributes,
		                else equivalent to 'text'
		$link['attributes']
                  = user entered attributes in an array as key,value pair
	$object - for internal links it contains the reference to
						target object in drupal format. For example, for node types
						it contains node object
							
eg:
function mymodule_ulink_node($link, $object=Null) {
  return l($link['text'], $link['path'], $link["attributes"]);
}  


hook_ulink_*type*_settings()
--------------------------------------------------------------------
Using this other modules can hook into ulink configurations and add
their own settings needed.

return: $form - an array in drupal form api format

eg:
function mymodule_ulink_node_settings($link, $object=Null) {
  $form['settings']['mymodule_text'] =  array(
    '#type' => 'textfield',
    '#title' => t('Use this when text is empty'),
		'#default_value' => variable_get('mymodule_text', ''),	
  );
  return $form;
}  

hook_ulink_*type*_info()
--------------------------------------------------------------------
Using this other modules can provide details about the module
in the settings page where user enables module and gives the preference
of rendering.

return: HTML text.

eg:
function mymodule_ulink_comment_info() {
  return t('mymodule is providing an extended functionality to ulink');
}

Detailed demo
--------------------------------------------------------------------
I encourage the developers to look into ulink_imagecache, ulink_gallery to
understand the situations requiring extensions to ulink, and correct way
of implementing the hooks.

*****************************************************************************
PROVIDING TRIVIAL IMPLEMENTATIONS THROUGH PHPMODE OF DEFAULT IMPLEMENTATION

Although it is possible to write a new module and implement the hooks,
it is not the case always. For the example given above, ie 
 return l($link['text'], $link['path'], $link["attributes"]);
user need to go for a new module, instead he could choose PHPmode whose
configuration is available at.

admin > settings > type (eg: node) > ulink - module implementation > phpcode - configure
eg: for node type it could be admin/settings/ulink/node/ulink_3

there it is enough to provide the phpcode that is intended to come within 
the function

eg:
return l($link['text'], $link['path'], $link["attributes"]);

help on variables available for the user to be used, is given in the settings page.

*****************************************************************************
I encourage  developers to share the modules with ulink users. If the module 
addresses an important requirement, that can be included with ulink package.
Please send an email to <garthee at gmail dot com> to share your modules or 
for other suggestions also you are welcome to ask for further assistance.
1	******************************************************************************
2	D R U P A L M O D U L E
3	******************************************************************************
4	Name: uLink developer documentation
5	Author: Gartheeban Ganeshapillai
6	AKA garthee at drupal <garthee at gmail dot com>
7	Dependencies: filter.module, comment.module(optional), tokens.module(optional)
8	Required by: uAuto.module, ulink_gallery.module, ulink_imagecache.module
9
10	******************************************************************************
11	This document explains howto develop modules to extend the rendering
12	and configuring the default rendering through phpmode.
13
14	******************************************************************************
15	WRITING MODULES TO EXTEND ULINK
16
17	When it is required to write a new module
18	--------------------------------------------------------------------
19	Often by configuring the default implementation provided by ulink
20	and using hard code you could obtain the needed output. In specific cases but
21	trivial, where it is not adequate, users can go for Macro mode or PHPmode
22	(explained below).
23
24	However, there will be highly specific and complex situations where PHPmode
25	won't suit the need. ulink_gallery.module and ulink_imagecache.module address
26	such cases, where they extend the ulink-functions by implementing the hooks.
27
28	Available hooks to be implemented
29	--------------------------------------------------------------------
30	1. function hook_ulink_type($link, $object=NULL)
31	2. function hook_ulink_type_settings()
32	3. function hook_ulink_type_info()
33
34	here type can be node, comment, user, image or files.
35
36	After providing the module.info file, it is enough to provide only
37	the first function ie. hook_ulink_type, and it is NECESSARY.
38	Implementation of other two functions is optional.
39
40
41	hook_ulink_type($link, $object=Null)
42	--------------------------------------------------------------------
43	Provides the html code of the output by making use out of
44
45	return: HTML code of the output
46	parameters:
47	$link - array contains information about the target link
48	$link['text'] = text to be referenced
49	$link['path'] = user entered path of the link, eg: node/44
50	$link['type'] = type of the target, eg: image, node
51	$link['mime'] = extension of the target if it is supplied,
52	else contains the user entered path
53	$link['title'] = title to the link, if it is specified in attributes,
54	else equivalent to 'text'
55	$link['alt'] = title to the link, if it is specified in attributes,
56	else equivalent to 'text'
57	$link['attributes']
58	= user entered attributes in an array as key,value pair
59	$object - for internal links it contains the reference to
60	target object in drupal format. For example, for node types
61	it contains node object
62
63	eg:
64	function mymodule_ulink_node($link, $object=Null) {
65	return l($link['text'], $link['path'], $link["attributes"]);
66	}
67
68
69	hook_ulink_type_settings()
70	--------------------------------------------------------------------
71	Using this other modules can hook into ulink configurations and add
72	their own settings needed.
73
74	return: $form - an array in drupal form api format
75
76	eg:
77	function mymodule_ulink_node_settings($link, $object=Null) {
78	$form['settings']['mymodule_text'] = array(
79	'#type' => 'textfield',
80	'#title' => t('Use this when text is empty'),
81	'#default_value' => variable_get('mymodule_text', ''),
82	);
83	return $form;
84	}
85
86	hook_ulink_type_info()
87	--------------------------------------------------------------------
88	Using this other modules can provide details about the module
89	in the settings page where user enables module and gives the preference
90	of rendering.
91
92	return: HTML text.
93
94	eg:
95	function mymodule_ulink_comment_info() {
96	return t('mymodule is providing an extended functionality to ulink');
97	}
98
99	Detailed demo
100	--------------------------------------------------------------------
101	I encourage the developers to look into ulink_imagecache, ulink_gallery to
102	understand the situations requiring extensions to ulink, and correct way
103	of implementing the hooks.
104
105	*****************************************************************************
106	PROVIDING TRIVIAL IMPLEMENTATIONS THROUGH PHPMODE OF DEFAULT IMPLEMENTATION
107
108	Although it is possible to write a new module and implement the hooks,
109	it is not the case always. For the example given above, ie
110	return l($link['text'], $link['path'], $link["attributes"]);
111	user need to go for a new module, instead he could choose PHPmode whose
112	configuration is available at.
113
114	admin > settings > type (eg: node) > ulink - module implementation > phpcode - configure
115	eg: for node type it could be admin/settings/ulink/node/ulink_3
116
117	there it is enough to provide the phpcode that is intended to come within
118	the function
119
120	eg:
121	return l($link['text'], $link['path'], $link["attributes"]);
122
123	help on variables available for the user to be used, is given in the settings page.
124
125	*****************************************************************************
126	I encourage developers to share the modules with ulink users. If the module
127	addresses an important requirement, that can be included with ulink package.
128	Please send an email to <garthee at gmail dot com> to share your modules or
129	for other suggestions also you are welcome to ask for further assistance.