++ 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. If it contains an appendix
      "adjheading" it adjusts the heading levels in the inserted page
      to the level of inserting page
    * *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.
    * *search* lists all wiki words found by the search string given
      as value. It supports the following appendices:
        * *type boolean*: Boolean regex search (default)
        * *type regex*: Simple regex search
        * *type asis*: Search "As is"
        * *type index*: Index based search (ignored if index not
          available)
        * *casesensitive*: Search case sensitive (default is
          insensitive)
        * *wholewordsonly*: Search whole words only 
        * *removeself*: Page on which the insertion is placed is
          omitted from search result (if you e.g. place a search
          insertion for "foo" on a page this page itself would be
          found just because it contains the search insertion
          with "foo" in it)
    * *toc* shows a little table of contents with the headings of 
      the current page. In HTML preview/export you can click on
      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.

++++ Lists of wiki links

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.

By default such a multi-column table is sorted rightwards:

<<pre
A B C
D E F
G H I
>>

With the appendix *"coldir down"* it is sorted downwards:

<<pre
A D G
B E H
C F I
>>

Appendix *"aslist"* shows a comma-separated list instead of a table. All other settings for link list are meaningless with this option.
*"colwidth equal"* ensures that all columns have equal width (as far as this is possible).
Appendix *"table_border_width 1"* shows a visible grid.


+++ 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: parents; aslist]*
[:rel: parents; aslist]

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

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

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

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

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


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

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