====== linkbonus Plugin ====== ---- plugin ---- description: Extended syntax for external links author : Luis Machuca Bezzaza email : luis.machuca [at] gulix.cl type : Syntax lastupdate : 2010-11-12 compatible : 2013-05-10a "Weatherwax", !Igor depends : conflicts : baselink similar : tags : links, !experimental downloadurl: https://trello.com/1/cards/5afdcb2ac4407c4f906b3038/attachments/5afdcb48bc5592f59426234c/download/dw-linkbonus-004.zip bugtracker : sourcerepo : donationurl: screenshot_img: ---- **LinkBonus**((tentative name)) is an experimental plugin undergoing development right now (as of //2010/11/12//) that extends the standard DokuWiki syntax for links in order to include some extra features. Namely, it implements at least the features indicated in the [[https://forum.dokuwiki.org/d/5026|linkbonus Introduction thread]] at the forums: - ability to set both the link name and tooltip - ability to automatically fetch the name from the external page - ability to display a visual indication if the external webpage is not available - ability to display the favicon of the remote site (see //tweaking// section) - ability to enter some formatting, such as italics, in links (see //tweaking// section) It also implements some other minor features which are explained below. > :!: **TAKE WARNING**: This plugin is experimental and is not considered stable -- it doesn't even have a definitive name. Using this extended syntax will slow page loading as data fetch must be performed, and will incur also in an overhead of outgoing connections. Use under your own risk. Once the major release is out **this page will be deleted and you will be advised to remove this plugin before installing the definitive version.** A courtesy of your friendly DokuWiki plugin developer Peter Parker Spiderman //[[user>ryan.chappelle|Luis Machuca Bezzaza]] --- 2010/11/12// ===== Download and Installation ===== Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. It is recommended to **clean your DokuWiki cache** right after installing or updating this plugin. ===== Syntax and Usage ===== To use this plugin simply extend the normal DokuWiki syntax for **links** with extra parameters: === External Link Syntax === An external link is like a [[:link|standard link]] pointing to somewhere in the Web and accepts the HTTP and HTTPS protocols. [[http://some.domain.tld/my/page | Link Name | | ]] === Server Link Syntax === A server link is a link that resolves relative to the root of the webserver where DokuWiki is installed, in a manner similar to that of the [[plugin:baselink]] plugin. [[@/my/page | Link Name | | ]] ===== ===== The extended link syntax has the following components: * **Link Name**: the name displayed for the link, the same way as the normal DokuWiki syntax. Special characters that interfere with DokuWiki syntax such as pipes (%%|%%) and braces (%%[ < > ]%%) can be escaped C-style: ''%%\| \[ \< \> \]%%''. * **Link Tooltip**: the tooltip that appears when hovering the pointer over the link. No DW syntax is allowed. If left empty, will default to the same content as the Link Name. * **extra parameters** are options that will affect the behaviour of the plugin. Parameters are of the form ''param="value"'' (where value can be empty) and are separated by pipes (%%|%%). If you don't want to specify any extra parameters (or no tooltip for that matter), just leave the corresponding sections blank and terminate the link syntax with a pipe: [[http://some.domain.tld/my/page | Link Name | Link Tooltip |]] ==== Parameters ===== === fetchname === fetchname="[tooltip|title]" If the "''fetchname''" parameter is present, the plugin will automatically **fetch the title** of the external page (as specified in the '''' tag and displayed in the browser's title bar). If the operation fails (eg.: the external link is not a HTML page or the link is not available, or maybe internet connection is down), the normal Link Name is used instead. The special value **''fecthname="tooltip"''** causes the fetched title to go into the Link Tooltip instead of the Link Name. The same considerations apply. === Dead or Alive === doa "Dead or Alive"((yes, like the videogame saga)) request when the "''doa''" parameter is present. In this mode, DokuWiki will try to fetch the external web page and store information about the operation. If the process fails (because eg.: a DNS resolution error or the page no longer exists, or requires authorization) a visual indication consisting of red underlining/border will be used to show the page is not available. Future versions of this plugin will display different warnings for different problem causes. === Favicon === favicon If the "''favicon''" parameter is present and the feature is enabled, DokuWiki will link to and present the favicon of the remote site's domain as the icon for the link, instead of the standard link icon in DokuWiki. This feature does not work in SSL-mode wikis, since doing so would cause a link or fetching of external content. :!: This feature is __disabled by default__. See [[#Tweaking]] to enable it. === Other Parameters === **''%%class="some_class"%%''**: sets the CSS class of the link. This class is applied as well as the standard (DokuWiki's) ''urlextern'' class. **''%%rel="value"%%''**: implements //rel// attributes, like for example ''%%"nofollow"%%''. === Reserved for Future Use === **The following parameters do not work in this version, but can be used and will work as indicated in future versions:** **''%%page="blank|self"%%''**: makes the link open in a new window/tab (''blank'') or in the same (''self''). Defaults to the Configuration value for [[config:target|link targets]]. ===== Demo ===== :!: [[http://ryan.gulix.cl/tests/doku.php/linkbonus]] <= Demo Site. FIXME There is another (unofficial) demo site which is my [[http://informatica.temuco.udelmar.cl/~lmachuca/dokuwiki-lucho/inicio|personal wiki]] FIXME, but the version of the plugin there incorporates some features not available in the public versions. ===== Development Information ===== ==== Tweaking ==== Some features are disabled or controlled. To modify their behaviour, add the required lines to your master configuration file (''$DOKU_CONF/local.php''): <code> $conf['plugin']['linkbonus']['option_name'] = option_value; </code> ^ Option ^ Key ^ Value ^ | [[#Favicon]] | '''link_favicons''' | '''true''' to enable the plugin to show favicons; '''false''' (default) to disable. | | Internal formatting | '''in_formatting''' | '''true''' (default) to enable italics, deleted and bold inside links, '''false''' to disable. | | Connection timeout | Change the ''$timeout'' variable in ''common.php'' to a quoted decimal value like %%'1.0'%% (the default). Connections to fetch external titles or check reachability of pages won't take more than this many seconds. || ==== Changelog ==== A list of features available can be found at the official demo site. ==== Known Issues ==== **Note**: This plugin does not work with [[:images#image_links|image links]]. **Note**: This plugin does not attempt to check the validity of an external title. If it has invalid characters or tags, this plugin will generate invalid XHTML code. **Note**: This plugin will increase page load time and cause a slight overhead on outgoing connections from your server. ==== Future Development ==== * better handling of links with no title (eg.: images?) * ability for the dead-or-alive mode to detect the cause of the error * ability to detect whether an internet connection is available and operate accordingly * ability to work with media links * interwiki syntax? * extended scheme syntax? (eg.: FTP, local file) * **a better name** (if you have ideas, //please// fire away! ^_^ ) ===== Discussion ===== Feel free to discuss here; just remember that this plugin is experimental and that it will be eventually superseded by another, much improved and "official"((as a plugin can be)) version.