docu update for link widget from aleksander.adamowski-AT-olo.org.pl

etemplate/doc/reference.html

@@ -390,7 +390,7 @@ implement only a subset of XUL. Here are the main differences:</p>
 		<b>3.</b> if set URLs in the content get activated<br />
 		<b>4.</b> name of form-element the label is for: gives focus to that element if the label gets clicked<br />
 		<b>5.</b> target for the link, eg. _blank<br />
-		<b>6.</b> width<i>x</i>height if a popup should be used for the link, eg. 600x400
+		<b>6.</b> width<i>x</i>height if a popup should be used for the link, eg. 600x400<br />
 		<b>7.</b> title<i>x</i>title for the link
 	</td>
 </tr>
@@ -954,17 +954,56 @@ function index($content = 0)
 	<td>no</td>
 	<td>link-to<p>link-list<p>link-string</td>
 	<td>
-		These widget are the UI-part of the link-class ({bo|so}link) in InfoLog and maybe the API soon.<p>
+		These widgets are the UI-part of the link-class ({bo|so}link) in the API.<p>
-		<b>link-to</b><br />
+		eGroupWare has a linking system that lets you link two records from different apps together.<p>
-		Widget to make a links to other entries of link-aware apps and to attach files.<p>
+		For example, you can link the addressbook entry of the person you're meeting with to the meeting on your calendar,
+		or an infolog entry for the phone call you made to postpone the meeting.<p>
+		To display links in your own application, you should use the LinkList group of widgets.<p>
 		<b>link-list</b><br />
 		Widget to shows the links to an entry and a Unlink Button for each link. <p>
+		It needs an array with two entries. If you name the LinkList widget 'links', you need: </p>
+<pre>
+$data['links']['to_app'] = 'myapp';
+$data['links']['to_id'] = $record_id;
+</pre>
+		<p>This will display links where the $record_id record of myapp is one side of the link.
+		Make sure that both variables are properly defined before the form template gets executed.
+		<p><b>link-to</b><br />
+		Widget to make a links to other entries of link-aware apps and to attach files.<p>
 		<i><u>Note</u>:</i> Both Widgets can be used on the same template with the <u>same</u> name. They share
-		the content of that variable, which contains just the id of the entry in the current app.<p>
+		the content of the variable with that name, which contains just the id of the entry in the current app.<p>
 
 		<b>link-string</b><br />
 		Comma-separated list of link-titles with a link to its view-method, value is like the return
-		of bolink::get_links().
+		of bolink::get_links().<p>
+		<hr>
+		Before you can use a link to your application, you need to specify some information in a 'search_link' hook.<p>
+		In your setup.inc.php, you need to point $setup_info['myapp']['hooks']['search_link'] to a function that will return an array: <p>
+<pre>return array(
+'query' =&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 'myapp.bo_myapp.link_query',&nbsp;
+	// A function that takes a search string
+	// and returns a list of matching records
+'title' =&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 'myapp.bo_myapp.link_title',&nbsp;
+	// A function that takes an id from one side
+	// of a link and returns a string for that entry
+'view'&nbsp; =&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; array('menuaction'=&gt;'myapp.ui_myapp.link_view'),
+	// Function to view a link, may be an existing view function
+'view_id'&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; =&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; 'link_id',&nbsp;
+	// name of the id variable provided to the view function above
+'add'&nbsp;&nbsp; =&gt;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp; array('menuaction' =&gt; 'myapp.ui_myapp.new_entry'),&nbsp;
+	// Function to add a new entry 
+);
+</pre>
+		<p>Also, make sure that the declared methods are implemented and methods from the UI class are listed in its $public_methods attribute:
+<pre>
+class ui_myapp {
+	var $public_methods = array(
+		'view' => true,
+		'add' => true
+	);
+...
+}
+</pre>
 	</td>
 </tr>
 </table>

etemplate/inc/class.link_widget.inc.php

@@ -13,20 +13,23 @@
 	 * eTemplate Extension: several widgets as user-interface for the link-class
 	 *
 	 * All widgets use the link-registry, to "know" which apps use popups (and what size).
+	 * Participating apps need to register a proper "search_link" hook - see eTemplate-reference (LinkWidgets) for info.
 	 * If run in a popup and the app uses no popups, a target will be set, to open a new full decorated window.
 	 *
 	 * The class contains the following widgets:
 	 * - link: Show a link to one linked entry specified by an array with keys app, id and optional title and help-message
 	 * - link-to: Widget to create links to an other entries of link-aware apps
-	 *	If an id was set, this widgets creats the links without further interaction with the calling code.
+	 *	If the variables $data['widget_id']['to_app'] = $app and $data['widget_id']['to_id'] = $entry_id
+	 *      are set, this widget creates the links without further interaction with the calling code.
 	 *	If the entry does not yet exist, the widget returns an array with the new links in the id. After the
-	 *	entry was successful create, bolink::link($app,$new_id,$arr) has to be called to create the links!
+	 *	entry was successfuly created, bolink::link($app,$new_id,$arr) has to be called to create the links!
-	 * - link-list: Widget to shows the links to an entry in a table with an unlink icon for each link
+	 * - link-list: Widget to show the links to an entry in a table with an unlink icon for each link. Needs the same
+	 *	pair of variables as link-to widget and needs to have the same id, as the data is shared with link-to.
 	 * - link-string: comma-separated list of link-titles with a link to its view method, value is like get_links() 
 	 *	or array with keys to_app and to_id (widget calls then get_links itself)
 	 * - link-add:    Add a new entry of the select app, which is already linked to a given entry
 	 * - link-entry:  Allow to select an entry of a selectable or in options specified app
-	 * - link-apps:   Select an app registerd in the link system, options: '' or 'add'
+	 * - link-apps:   Select an app registered in the link system, options: '' or 'add'
 	 *
 	 *<code>
 	 * $content[$name] = array(
@@ -43,7 +46,7 @@
 	 * );
 	 *</code>
 	 *
-	 * This widget is independent of the UI as it only uses etemplate-widgets and has therefor no render-function.
+	 * This widget is independent of the UI as it only uses etemplate-widgets and has therefore no render-function.
 	 *
 	 * @package etemplate
 	 * @subpackage extensions