Preprocessor for Page Markup - tremho/thunderbolt-common GitHub Wiki

When composing page markup, there are occasionally instances where you might want to have different markup for different situations that you can define.

Note: Preprocessor operations for Component markup is not currently supported

This is where the preprocessor comes in. Use it to conditionally emit sections of markup depending upon conditionals. Define values that may be used to test as conditionals, or to embed within the emitted line code.

Preprocessor statements are enclosed within an XML-style comment, like this:

<!-- #if desktop -->
<!-- #define Mode=Release -->
<!-- #else -->
<!-- #define Mode=Development -->
<!-- #end if -->

It is important that each preprocessor line be contained within its own comment wrapper (<!-- -->). Multi-line comments containing preprocessor directives is unsupported.

Preprocessor directives themselves are not case sensitive. That is, #define, #DEFINE, and #Define are all equivalent, as are #if and #IF.

Tokens and their referenced values, however, are case-sensitive. Thus, #define COLOR=GREEN is not the same as #define color=green

The following tokens are reserved and should not be used when defining custom values.
Each of these tokens are semi-case insensitive, meaning, for example, DESKTOP, desktop, and Desktop are all reserved, but something like dEskToP is not.

• DESKTOP - used as in <!-- #if desktop --> Evaluates true if output is destined for Desktop applications
• MOBILE - used as in <!-- #if mobile --> Evaluates true if output is destined for Nativescript mobile export
• TRUE - used as in <!-- #if true --> May be useful for troubleshooting. Always evaluates true.
• FALSE - used as in <!-- #if false --> May be useful for troubleshooting. Always evaluates false.

A common use of the preprocessor is to target markup code to either desktop or mobile separately.

<!-- #if desktop -->
<simple-label text="This appears only for desktop"/>
<!-- #else -->
<simple-label text="This appears only for mobile"/>

<!--- #if false -->
<... all the markup here will be ignored...>
<!-- #end if -->

You may define values you later use to compare to or embed into emitted lines using the #define statement.

Use a single = character to assign a value to the token name. Do not use quotes unless you wish these to be part of the value.

<!-- #define FOO=foobar -->

You may test defined values for matches as a conditional test, like so

<!-- #if FOO==foobar -->
  <simple-label text="the foobar case goes here"/>
<!-- #else if FOO=baz -->
  <simple-label text="the baz case goes here"/>
<!-- #else -->
  <simple-label text="all other cases go here"/>
<!-- #end if -->

The use of the double-equals (==)is important here.

Inequality is also supported, using !=:

<!-- #if FOO!=foobar -->
  <simple-label text="this is not foobar"/>
<!-- #end if -->

There may be spaces around the == or != operators to separate the token and test value better, if you like.

You can create a value of substitution text (aka "macro") that is emitted into the emitted markup by defining a token with a value and referencing that token with #{name} in your code.

For example:

<!-- #define Color=green -->
<simple-text text="example of embedding" color="#{Color}"/>

will result in the output:

<simple-text text="example of embedding" color="green"/>

An undefined token will return an empty string (""), but of course without the quotes. To test for an undefined value, simply do not include a value to test. Example: <!-- #if Unknown== --> returns true if Unknown is not defined.

Token values can be redefined. A previously defined value will change if a new #define statement declares it with a new value. A token can be reset by <!-- #define Token= -->, which effectively sets the value of Token to nothing.