Custom Tags

IntraWeb MarkDown is extensible and custom tags can easily be added.

Namespace

To avoid internal conflicts, all custom tags should contain a vendor prefix that is unique and separated from the tag name by a dash (-). For example, if Atozed were to add custom tags as a vendor the prefix atozed would be a good candidate. To add a custom uppercase tag, it would be added as atozed-uppercase.

Using a vendor prefix is not a requirement, but without such a prefix your custom tags may conflict with other custom tags, or even built in existing MarkDown tags or future tags.

Example

As an example we will use the previously mentioned atozed-uppercase tag to create a custom tag which changes the text to uppercase. This sample is available as part of the MarkDown.iwml test.

As MarkDown occurs in the browser, we need to use TypeScript, JavaScript, or some other language that cross compiles to JavaScript.

To add code for atozed-uppercase, we only need a single line of code:

IntraWeb.TagHandler.Add("Atozed-UpperCase", (aTag: IntraWeb.Tag) => aTag.Data.toUpperCase() );

This single line adds support for our new tag and will cause all rendering to be uppercase. This line is a compacted version and may be difficult to read if you are not familiar with the syntax. A more verbose version is shown here:

function UpperCaseHandler(aTag: IntraWeb.Tag): string {
  return aTag.Data.toUpperCase();
}

IntraWeb.Markdown.TagHandlers.Add("Atozed-UpperCase", UpperCaseHandler);

For this IWML:

ACORN 1.0 IWML 1.0
Tests.Playground
  Root[]
    Text [Atozed-UpperCase:Hello World]
  ]
]

Will render in the browser as:

Function Handler

The second parameter of AddTagHandler is aProcessFunc and expects a named or anonymous function to be passed. This function handler will be called each time the tag name is matched and must provide the rendering of the html output.

There are several built in functions which can provide default functionality in the Tag class such as Process_All and others. Each of these methods starts with the Process_ prefix.

Such methods are used to easily to support embedded tags and other functionality. These methods are not necessary and a tag handler can be written without their use.

Custom Match Function

  • To Document

Demos

  • MarkDown.iwml

See Also

  • InitTagHandlers() in MarkDown.ts – This is where the built in tags are registered along with their tag handler functions. It is a valuable resource for examples of tag handler implementations.