====== chiplink Plugin ======

---- plugin ----
description: Provides automatic links to HTML reports on your server, by searching the wikitext 
author     : Jonas Berg 
email      : jonas.s.berg@home.se 
type       : syntax
lastupdate : 2012-04-01
compatible : 2010-11-07+
similar    : rtlink
tags       : links, documentation, reports

downloadurl: https://github.com/pyhys/dokuwiki-plugin-chiplink/zipball/master
bugtracker:  https://github.com/pyhys/dokuwiki-plugin-chiplink/issues
sourcerepo : https://github.com/pyhys/dokuwiki-plugin-chiplink/

----

===== Introduction =====
This plugin will automatically convert chip names in the wiki text into links pointing to HTML reports located on your wiki server. It is easy to adapt the plugin for similar automatic linking to HTML documents from labels in your wiki text. This might be part numbers, legal document paragraphs etc. 

As the generated links are relative to the server name, it works fine also when used with VPN (virtual private networks).


===== Usage =====


Just type the chip number in plain text as SW123p45 to activate the link:

<code>
SW123p45
</code>

This will convert the text into a link pointing to the report ''SW123.htm'' (and the bookmark ''#p45'') located on your server in ''/reportfolder/'' 

This HTML code will be inserted: 
<code>
<a href="/reportfolder/SW123.htm#p45">SW123p45</a>.
</code>

===== Syntax =====
The matched pattern is SW**xxxxx**p**xxxxx** where **x** are digits. See below how to adapt it for your needs.




===== Installation =====
Search and install the plugin using the [[plugin:extension|Extension Manager]].

If installing it manually, download the compressed file using the link above. Decompress it, and rename the folder inside to ''chiplink'' (it was something like ''pyhys-dokuwiki_plugin_chiplink-###''). Move this folder to ''lib/plugins/'' below your DokuWiki installation. Make sure a folder ''lib/plugins/chiplink/'' now is available, and it should have at least the ''syntax.php'' file and the subfolder ''conf''. 

Refer to [[:Plugins]] for more details on how to install plugins manually. 

===== Adapting the plugin to your needs =====
This plugin can easily be modified to fit your needs for automatic linking to HTML reports. The foldername for the reports (''$relativelocation'') can be set in the configuration manager. 

The matching pattern to look for in the wiki text, and the resulting link target can be changed in the file ''lib/plugins/chiplink/syntax.php''. These are the parts to change:

^ Description                ^ Code lines to change ^
| Wiki text matching pattern | <code php>// Match for example 'SW1613p8'
$this->Lexer->addSpecialPattern('[sS][wW][0-9]+[pP][0-9]+', $mode, 'plugin_chiplink'); </code> |
| Data extraction            | <code php>$stripped = substr($match, 2); // Remove initial 'SW'
$splitted = preg_split("/[pP]/", $stripped); // Split '1613p8' into '1613' and '8'.
list($wafer, $chip) = $splitted;</code> |
| Report link generation     | <code php>$url = "/".$relativelocation."/"."SW".$wafer.".htm#p".$chip;
$description = "SW".$wafer."p".$chip;</code> |

===== Credits =====
Thanks to Gregg Berkholtz for the [[plugin:rtlink]] plugin, on which this plugin is based.

===== Trouble shooting =====
When changing the plugin PHP code, make sure to add this to the URL to purge the cache:

  &purge=true

Otherwise the changes will not take effect immediately.

=== No link is created ===
Make sure that the plugin is installed properly. It should appear in the Plugin Manager, and 'Chiplink Plugin Settings' should appear in the Configuration Manager.

First try with the original wiki text pattern (SWxxxxxpxxxx) and the regular expression provided, and make sure some link is created. Then make necessary adjustments in the regular expressions.


=== The link points to wrong target ===
Right-click on the generated web page, and select 'View Page Source'. Look exactly how the link ended up. Make appropriate adjustmnents in the configuration settings or the sourcecode.

If it looks OK but still does not work, make a dummy HTML document with a link to your target (to make sure the target is on the correct location). 


===== Discussion =====