pWiki/v3/bootstrap/Doc/Macros.md

pWiki Macros

Syntax

Any macro can be used in any of the two forms, either inline or HTML-like.

Inline:

@macro-name(value)

@macro-name(value text=" ...text... ")

HTML-style:

<macro-name arg="value"/>

<macro-name arg="value">
  ...text...
</macro-name>

The two forms are almost identical, with the only difference being that the inline form does not support body text (note that some macros may provide this functionality as an argument, namely slot).

The two forms exist to fill two distinct functions:

• inline: compatible with attribute values and short
• html-like: element-like, simpler when dealing with html

Positional and keyword attributes

Attributes (arguments) can be set sequentially by value, as they are defined or by name in any order.

The following are equivalent:

<slot abc "some text"/>
<slot name=abc text="some text"/>
<slot "some text" name=abc/>

Keyword attributes are special attributes that are given by name rather than by value by default and if no value is set explicitly it defaults to true if passed, and to false if omitted.

The following are equivalent:

<slot some-name hidden/>
<slot some-name hidden=true/>

Special attributes

Two special attributes are handled differently: text and body, these are equivalent, the two names exist to make the semantics of macros simpler.

If both attributes are defined body takes precedence over text and both are overriden by a non-empty body, e.g. the following:

<slot slot text=text-attr body=body-attr>body</slot>

will resolve to body.

The main difference from normal attributes is that the value of these is parsed in the same way as the element's body is. Thus, the following are identical:

<macro-name text="body text"/>

<macro-name body="body text"/>

<macro-name>body text</macro-name>

The values are parsed lazily, i.e. only the final value is parsed, the overridden values are ignored.

Escaping macros

Macros can be escaped for inclusion in the page, the two types of macros are escaped a bit differently:

• inline macros -- escaped by preceding with a ""

  \\@include(\SomePage)
  

  Displayed in page as:

  @include(\SomePage)

  _NOTE: if displayed on github, this will show an extra "\" in both cases, this should be ignored as pWiki will consume the escaping "\" in both the code example and the preview._

• html-like macros -- escaped the HTML way

  <include src="\SomePage"\>
  

  Displayed in page as:

  <include src="\SomePage"\>

Conditional comments

In addition to HTML and filter-specific comments pWiki provides two types of conditional comments that serve two specific functions:

Show something in pWiki but hide it in HTML:

<!--\[pWiki[ ... ]]-->

Show something in HTML but hide in pWiki:

<pwiki-comment> ... </pwiki-comment>

This will enable writing documents (mainly in markdown) that are usable bot from within pWiki as well as outside.

Macros

now ()

\@now()

Get current date in seconds since epoch, this is equivalet Javascript's Date.now().

This is mostly used for automatically creating paths (see: todo / outline)

This is different from $NOW in path (see: Doc/Path) in that this gets the date once per page load, i.e. the date changes on page load, while $NOW is set every time the path is used, i.e. on every click or script use.

Will produce: 1471389217848

slot ( shown|hidden) / content

@slot(<name>)
@slot(<name> <text>)
@slot(<name> <text> hidden)
@slot(<name> <text> shown)

<slot <name> ...>
	...
	<content/>
	...
</slot>

Define or fill a slot.

First occurrence of a slot name will define a slot and set its value (fill it) with text if given. Each new occurrence of a slot with the same name will override slot content.

Only the first occurance of the name slot macro is displayed by default.

Slot display can be explicitly controlled via the hidden and shown keywords, if both are given hidden has precedence. All shown slots of the same name will display the same value.

Nested slots are processed in order of occurrence, i.e. a nested slot can override it's parent's value.

Example:

<slot X>
	some text 
	<slot X "new text"/>
</slot>

Will resolve to: new text

<content/> / @content() if encountered will be replaced with previous slot value.

Example:

This is: <slot X text="some text"/>

<slot X>[[ <content/> ]]</slot>

Will resolve to This is: [[ some text ]]

Example:

- [bootstrap view](/bootstrap/Templates/_view.html) - [bootstrap edit](/bootstrap/Templates/_edit.html)

---

filter (name)

Enable or disable a page filter.

A filter is a way to transform the page source.

Arguments:

• name -- filter name. If name is preceded with a '-' then it will be forced off. This is useful for disabling default filters, or filters added previously in templates.

Filters:

• wikiword (default)
• markdown

Example:

- [bootstrap \_edit](/bootstrap/Templates/_edit.html) – _see the macro at the end of the page._

include (src isolated text)

Include a page. The included page is rendered independently from current page and is inserted as-is in macro body.

Note that this will produce a include tag in the code that contains the included page, this makes this tag not suitable for use anywhere but an html element body.

Arguments:

• src -- path to source page.
• isolated -- prevent slots from included page from affecting the including page.
• text -- is used when recursive include is detected and ignored otherwise.

For examples see slot macro exaples below.

source (src) / quote (src)

Insert a page without rendering. This is similar to include but will not render the page.

The difference between source and quote is:

• source includes the page as-is
• quotes escapes the page (i.e. quotes it's source) for its code to display in the rendered HTML correctly.

Arguments:

• src -- path to source page.

Example:

- [bootstrap css](/bootstrap/Templates/_css.html)

macro (name src sort) / else ()

Apply macro to source page and include the result.

This is similar to include but does not require a separate page.

Both name and src are optional.

If name is given a named macro is defined. This macro can be later referenced (used) by name. A named macro can be redefined/overridden.

If src is given a macro is applied to a specific page or range of pages (see: WikiPath).

For a macro to be useful it must have a body (text), either defined as a named macro or in the current macro.

Arguments:

• name -- macro name (optional).
• src -- path to source page (optional).
• sort -- space separated list of methods to use for item sorting

else macro is applicable inside macro. it is used when the src path of macro matches no pages.

Example:

- [bootstrap pages](/bootstrap/Templates/pages.html)