Markdown

IntraWeb supports a simple Markdown syntax which allows formatting of text, data binding and more.

Sample

ACORN 1.0 IWML 1.0
Page
  Root[]
    SimpleStack[Text]
      Plain Text
      [b:Bold] and [i:Italic]
      Embedded EOL[eol]After EOL
      One
    ]
  ]
]

Will generate this:

No Markdown in Data

Properties that support markdown, do not use markdown when the field is data bound.

Primary Syntax

IWML MarkDown only changes text found with in [ and ] markers. Within these square brackets the primary syntax is:

[TagName:Data]

Example:

[bold:This is bold text]

TagName is mandatory. Data is not used with some tags.

TagName specifies the behavior. Tags are expandable and custom tags can be defined.

Alternate Syntax

Tags can also take the following alternate form:

[TagName]Data

Example:

[bold]This is bold text

With this alternate syntax, Data will be unconstrained and will continue until the end of the input string. The alternate form is useful mostly for text and html types but can be used with any tag.

Data with this alternate form cannot contain any embedded tags. All tag markers and special sequences are ignored.

Casing

All tag names are case insensitive.

Parameters

In addition to the primary data, tags may support parameters:

[TagName(Params):Data]

or

[TagName(Params)]Data

Multiple parameters are also supported and can be optional or required. Multiple parameters can be supported but are up to the individual tag how it separates the parameters, but a comma is suggested for most cases. An example of a tag that optionally uses a parameter is the HTML tag.

Neither name nor parameters can contain any of the following characters:
[]:

Embedding

Tags can embedded inside other tags when the primary syntax is used.

Example:

[bold:This is bold and [i:italic text] ]

Note the space between the last two ] ending brackets. This is necessary in this case as ]] is a special sequence.

Special Sequences

! / !!

! when used at the beginning of markdown text specifies that what follows is plain text and will not be treated as markdown.

To start markdown text with !, use !! instead and only one ! will be rendered. This is only needed if ! is desired as the first character. ! characters that appear in other parts of the markdown will be rendered directly.

[]

As [] is never a valid tag but is often used to notate arrays in code examples. [] is valid and does not need any special sequences even if embedded inside a tag. [] will always be rendered as [].

]

] when not inside a tag is rendered exactly as is and no special handling is required.

HTML Conversion

Special characters such as “&'<> and EOL are automatically encoded for HTML output except within the html tag.

Standard Tags

Built in tags are as follows. Some tags have alternate shortcuts. Such tags will be listed with / as a separator.

[b:text] / [bold:text]

Renders text as bold.

[i:text] / [italic:text]

Renders text as italic.

[html(CssClass):data]

Renders data without any conversion for special HTML characters. Useful for embedding raw HTML into output.

html tag can be embedded in other tags, but the output will be encoded as if it were text. To use html tag as intended, it must be a top level tag.

Note: IWML is designed to be used with rendering engines other than HTML in the future. In such implementations the HTML tag may not be supported.

Example:

[html:<div id="Test">Bold Text</div>]

or

[html]<div id="Test">Bold Text</div>

The CssClass parameter is optional. If not specified the data will be output unchanged. If specified, the data will be wrapped in a span tag with the CssClass parameter as the class attribute.

[html(bluebg)]Hello

or

[html(bluebg):Hello]

Will render as:

<span class="bluebg">Hello</span>

[brackets:data]

Renders data in brackets as brackets are reserved characters used by MarkDown.

[func.FunctionName(Params)]

Tags are case insensitive, but JavaScript is not. Thus FunctionName is case sensitive but the func. prefix is not.

Because func. is not an inline tag data is required. If no data is needed, specify blank data:

[Func.TestFunc():]

If not parameters are needed, the () is not required however specifying them helps to visually emphasize that it is a function call.

The func tag will look in the code behind file for the page and pass aTag: Tag as the only argument. The function must return a string.

Example:

MarkDown.ts

namespace Tests {
  export class MarkDownGen extends IntraWeb.Code {
  }

  export class MarkDown extends MarkDownGen {
    public TestFunc(aTag: IntraWeb.Tag) {
      return "Hello from code";
    }

    public Repeat(aTag: IntraWeb.Tag) {
      const xCount = Number(aTag.Params);
      return aTag.Data.repeat(xCount);
    }
  }
}

MarkDown.iwml

ACORN 1.0 IWML 1.0
Tests.MarkDown
  Root[]
    SimpleStack[Text]
      [Func.TestFunc:] and more
      [Func.TestFunc():] and more
      [Func.TestFunc] and more
      [Func.TestFunc()] and more
      [Func.Repeat(4):Pete]
      [Func.Repeat(4)]Pete
    ]
  ]
]

Output

Note that the third and fourth entries do not display “and more”. This is because it is the data of the tag, and our TestFunc ignores the data value, so in essence it “eats” it. The data is available in the Tag object should the function decide to use it.

Inline Tags

Inline tags are without data and are always interpreted using primary syntax and never using alternate syntax.

[eol]

Renders a line break into the output.

[Left] / [Right]

Renders a left or right square bracket, ie [ or ].

[Space] / [Space(size)]

If size is omitted, will render am html nbsp. If size is specified, will render a div with the width specified by size.

[=<Data Binding Expression>]

= signifies that a data binding expression follows.

Tags can be used to bind to rows in datasets, or even properties in the code behind or other objects. Refer to the Data Binding topic for more information.

Custom Tags

Custom tags can be added globally using tag handlers, or locally using functions.

Demos

  • MarkDown.iwml