++ Insertions

Insertions allow to insert some dynamic text into preview and HTML export of a page. This text can either be the content of another page or a list of wikipage links to pages which are parents or children of a page or to pages which form the result of a saved search.

To insert, for example, the content of the IncrementalSearch page, write:

[:page: IncrementalSearch]

----

If you switch now to the preview, you will see the content of the IncrementalSearch page above, instead of the insertion tag.


+++ Syntax
The tag begins always with '[:' then comes the _insertion key_, then a colon and the _insertion value_,
after that there may be appendices, separated by semicolons, to describe the way of presentation in more detail. The tag is closed by a closing bracket.

In the example above, "page" is the insertion key, "IncrementalSearch" is the value.

The value and appendices can be quoted (enclosed by quotation symbols) if they shall contain special characters or newlines. A quotation symbol is an arbitrary number of one of the quotation characters ", ', / or \ (double quotation mark, single quotation mark, slash or backslash). The starting and ending symbols must be the same. Examples for quotation symbols are:

"
'''
//
/////
\\

The above insertion example can therefore be written as:

<<
[:page: "IncrementalSearch"]
[:page: '''IncrementalSearch''']
[:page: //IncrementalSearch//]
[:page: /////IncrementalSearch/////]
[:page: \\IncrementalSearch\\]
>>

The following keys and values are built into WikidPad (further are possible by plugins):

    * *page* shows the content of the existing wiki page which is
      given as insertion value.
    * *rel* lists all wiki words related to this page in the way
      described by the value:
        * *parents*: all parents of the page
        * *children*: all children (= all wiki links) of the page.
          With appendix "existingonly" only the really existing
          pages are listed
        * *parentless*: all parentless pages. The list is
          independent from the page containing the insertion tag.
        * *undefined*: all undefined wiki word links. The list is
          independent from the page containing the insertion tag.
        * *back*: go back in history of WikidPad tab (or browser
          on export)
    * *savedsearch* lists all wiki words found by the saved search
      with the name given as value.
    * *toc* shows a little table of contents with the headings of 
      the current page. In HTML preview/export you can click on the
      the lines to go to the actual headings. The value of this
      insertion must be empty.
    * *iconimage* shows the icon whose name is given as value.
      You can use menu "Format"->"Icon Name" to find the name of
      an existing icon.
    * *eval* Evaluate the given Python expression and handle its
      result as if it replaces the insertion. You must switch on
      the appropriate option "Process insertion scripts" on the
      "Security" options page to make it work.
    * *self* Shows the name of the current page.


For insertion tags which produce lists of wiki links (all but the "page" and "eval" insertion), you can also have the appendix "columns 123" where 123 stands for the number of columns the list should have. By default, there is only one column.

+++ Examples

At first a few wiki links to demonstrate the functions: (KeyBindings, DeadLink, DeadLinkToo, ScratchPad, TextBlocks)

It is recommended to switch to preview to see the effect of the tags:

*\[:rel: parents]*
[:rel: parents]

*\[:rel: children]*
[:rel: children]

*\[:rel: children;existingonly;columns 2]*
[:rel: children;existingonly;columns 2]

*\[:savedsearch: nanny; columns 4]*  (all pages containing "any")
[:savedsearch: nanny; columns 4]

*\[:toc:]*
[:toc:]

*\[:eval:"5+6"]*
[:eval:"5+6"]
