====== dwinsect Plugin ======
---- plugin ----
description: Inserts a full section or only the first link in the section. The section-text can be used as a footnote. Includes a toolbar-button to editor.
author : Dietrich Wittenberg
email : dietrich.wittenberg@online.de
type : syntax, action
lastupdate : 2013-06-29
compatible : 2012-01-25 "Angua"
depends : dwtools
conflicts :
similar : embed, include
tags : links, include, footnotes
downloadurl: https://github.com/dwittenb/dokuwiki-plugin-dwinsect/zipball/master
bugtracker : https://github.com/dwittenb/dokuwiki-plugin-dwinsect/issues
sourcerepo : https://github.com/dwittenb/dokuwiki-plugin-dwinsect/
donationurl:
----
===== Installation =====
Search and install the plugin using the [[plugin:extension|Extension Manager]]. Refer to [[:Plugins]] on how to install plugins manually. Take care that the directory-name of the plugin is: ''dwinsect''
You need the dwtools-library. (look to the end of description where to get it)
===== Purpose of this plugin =====
==== Basic purpose of DWinsect plugin ====
With DW**insect** plugin you can easy **in**clude a **sect**ion of a page in two different ways: \\
- Include the whole section as it is (Headline, and section - text)
- Include the first link((any valid dokuwiki-link is allowed)) that is found in the section \\ and include the text before an after that link as
- plain text
- a footnote
==== Main purpose of DWinsect plugin ====
The main purpose of the DWinsect plugin is to use it like you use your favorite links in your browser. \\
You can refer to that link everywhere in your dokuwiki. If the link is broken you have to change the link only one time an not everywhere in your dkuwiki.
Thats all you have to do:
- craete a new page anywhere in your dokuwiki (e.g. name it "favorites" in the namespace "wiki:")
- edit the page and insert all your favorite links.
- add to each link a headline with a symbolic name of the link
- you can add any text before or after the link as a description (option).
- use DWinsect-syntax anywhere in your dokuwiki
===== Syntax =====
[*(ns:page#anchor?aparams|lparams)]
^syntax ^description ^usage ^default value ^
|''%%[*(%%'' |open-syntax |needed | |
|ns: | any valid namespace |optional |[[#namespace-default]] |
|page | any pagename in the namespace |optional |default value can be set in the configuration page |
|# | delimiter |optional |needed if a namespace or pagename is used to seperate ns:page from anchor |
|[[#anchor-syntax|anchor]] | name of the dokuwiki headline |needed | |
|? | delimiter |optional |needed if anchor parameters are used to seperate anchor from aparams|
|[[#aparams-syntax|aparams]] | anchor-parameters |optional |default value can be set in the configuration page |
|[[#lparams-syntax|lparams]] | link-parameters |optional |by default the link-parameter of the favorite link is used |
|''%%)]%%'' | close-syntax |needed | |
=== anchor-syntax ===
The name of the anchor is case sensitive und must match the name of a headline that exists. \\
:!: The Headline "Google" is differnt to the Headline "google". If the same headline occurs more than one time, the first hedline is choosen.
=== aparams-Syntax ===
name1=value1&name2=value2name3=value3 ...
^name ^value ^description ^
|text |none |no text before an after the link |
| |plain |text with dokuwiki-syntax before and after the link |
| |footnote |same as plain, but text as footnote before an after the link |
|link |none |no link |
| |plain |original link |
| |translate |if set, use lparams instead of the original link-params |
|include |none |nothing to include (empty) |
| |plain |include the whole section (headline an dokuwiki-text inside the section) |
| |link |include the first link |
=== lparams-Syntax ===
Each valid value that is allowed in dokuwiki-links after the "|" or in media-links after the "?". If you want to use named medialinks something like ''%%|my named linktext?50x200%%'' creates a name medialink (my named linktext) and changes the parameters to 50x200.
With the aparams you can decide if the original or the DWinsect parameters are used.
=== namespace-default ===
If no namespace is given, the plugin searches from the actual namespace looking for the page recursively until root is reached. If no page is found the DWinsect-syntax appears as *(ns:page#anchor?aparams|lparams) with the css used for non existing links (normally red font with a red dotted underline).
===== Examples/Usage =====
=== Page with favorites ===
e.g.: content of "favorites" in the root
== Google ==
http://www.google.de
Google is a search engine. You can find more at [[http://de.wikipedia.org/wiki/Google|Wikipedia]].
== Yahoo Deutschland ==
You can try Yahoo too, but [[http://www.yahoo.de|this is not GOOGLE.]]Yahoo is another search engine.
=== Examples using the parameter link = translate with different lparams===
^DWinsect - syntax ^Result ^description ^
|''%%[*(Yahoo Deutschland)]%%'' |''%%[[http://www.yahoo.de|this is not GOOGLE.]]%%'' |use original linktext |
|''%%[*(Yahoo Deutschland|)]%%'' |''%%[[http://www.yahoo.de]]%%'' |clear linktext |
|''%%[*(Yahoo Deutschland| )]%%'' |''%%[[http://www.yahoo.de|Yahoo Deutschland]]%%'' |change linktext to headline|
|''%%[*(Yahoo Deutschland|YAHOO)]%%'' |''%%[[http://www.yahoo.de|YAHOO]]%%'' |change linktext as defined |
=== Examples for using DWinsect ===
Assume the plugin configuration defaults are:
^name ^value ^description ^
|text |none |dont show the text bevore and after the link |
|link |translate |use the lparams if set and overwrite the original link-params |
|include |link |use the first link in the section |
The DWinsect - syntax results are:
^DWinsect - syntax ^ Result ^description ^
|''%%[*(Google)] %%'' |''%%http://www.google.de%%'' |just take the original link |
|''%%[*(google|GOOGLE)]%%'' |''%%*(google|GOOGLE)%%'' |:!: case sensitive: headline google is not defined |
|''%%[*(Google|GOOGLE)]%%'' |''%%[[http://www.google.de|GOOGLE]]%%'' |change the name of the link to "GOOGLE" |
|''%%[*(Yahoo Deutschland|YAHOO)]%%'' |''%%[[http://www.yahoo.de|YAHOO]]%%'' |change the name of the link to "YAHOO" |
|''%%[*(Yahoo Deutschland?text=footnote|not YAHOO.)]%%'' |''%%((You can try Yahoo too, but ))[[http://www.yahoo.de|not YAHOO.]]((Yahoo is another search engine.))%%'' |show the text before and after the link as a footnote |
|''%%[*(Yahoo Deutschland?text=plain|not YAHOO.)]%%'' |''%%You can try Yahoo too, but [[http://www.yahoo.de|not YAHOO.]]Yahoo is another search engine.%%'' |show the text before and after the link as plain text|
|''%%[*(Yahoo Deutschland?include=plain|not YAHOO.)]%%'' |''%%== Yahoo Deutschland ==%%'' \\ ''%%You can try Yahoo too, but [[http://www.yahoo.de|this is not GOOGLE.]]Yahoo is another search engine.%%'' |include the whole section as plain text |
:!: You can use the syntax inline. No additional paragraphs are added. The text is shown inside footnote with full dokuwiki-syntax
===== Change Log =====
[preferable GitHub RSS feed or similar]
* **2012-07-01**
* Initial release
===== ToDo/Wish List =====
:-( There is a bug when usin the syntax inside a list:
If in page links the link-section is defined as:
====Link to dwinsect-plugin====
Text before link
http://dokuwiki.org/plugin:dwinsect
Text after link
and a syntax like this is used:
'' * [*(links#linkname#Link to dwinsect-plugin|test)]''
the output gets to:
* [[http://dokuwiki.org/plugin:dwinsect|test]]((Text before link))((Text after link))
The text before or after the link, that is rendered as plain text or as a footnote is always placed after the link / url. Using the syntax not in a list works fine.
I am working to patch the bug.
:!: bug fixed now, made several changes to the syntax.php.
===== FAQ =====
yet emty.
===== Other Plugins =====
* [[plugin:dwinsect]]
* [[plugin:dwtools]]
* downloadurl: https://github.com/dwittenb/dokuwiki-plugin-dwlib/zipball/master
* some functions that are needed by dwinsect plugin.
* Installation: Create a directory named: dwtools und copy the lib.php inside it.
* [[plugin:dwspecialist]]
* [[plugin:dwstatistic]] great Plugin to track and view page-access. comming soon :!:
* [[plugin:dwchart]] great Plugin to create Charts. comming soon :!: