History: Branching

            From Tiki 15 onwards, it is possible to include contents of other YAML files in profiles depending on branching logic.

!Basic usage

The basic usage is through the use of the !include directive. In YAML, the "!" preceding the string means that that is a directive and some kiind of execution is to happen, returning some kind of output that replaces the directive.

The following is an extremely basic example on how it works:
-+test.yml+-
{CODE(colors="yaml")}
preferences:
  feature_wysiwyg:
    - !include wysiwyg.yml 1 eq 1
    - !include nonwysiwyg.yml
{CODE}
-+wysiwyg.yml+-
{CODE(colors="yaml")}
feature_wysiwyg: y
{CODE}
-+nonwysiwyg.yml+-
{CODE(colors="yaml")}
feature_wysiwyg: n
{CODE}
Each of the options of YAML files to include for a particular key (in the above case, -+feature_wysiwyg+-) is an item in a list starting with the -+!include+- directive followed by the filename (relative to the profile), and then a condition comparing 2 values using operators.

If the condition is true, then it includes that YAML file and ignores the other conditions. If not it moves on to the next option and performs the test again. It is customary to provide a default YML file in case any of the preceding conditions are not met. This works pretty much is the same way as a typical CASE structure in PHP.

In the above example, -+wysiwyg.yml+- will be included and therefore Wysiwyg will be on. If on the other hand:
{CODE(colors="yaml")}
preferences:
  feature_wysiwyg:
    - !include wysiwyg.yml 1 eq 2
    - !include nonwysiwyg.yml
{CODE}
since 1 does not equal 2, it will default to the -+nonwysiwyg.yml+- and set -+feature_wysiwyg+- to 'n'.

Note that the contents of the included YAML files should start with the same key as that to be replaced. For example, wysiwyg.yml and nonwysiwyg.yml both start with "feature_wysiwyg".

!Comparison operators
; -+eq+-: equal to
; -+neq+-: not equal to
; -+lt+-:  less than
; -+le+-: less than or equal to
; -+gt+-: greater than
; -+ge+-: greater than or equal to

!Using references
!!Checking value of preferences
To build on the above, it is possible to check the value of the preference and then decide which YAML file to include. For example,
{CODE(colors="yaml")}
preferences:
  feature_wysiwyg:
    - !include wysiwyg.yml $preference:feature_page_title$ eq y
    - !include nonwysiwyg.yml
{CODE}

!!Checking profile input
This could be especially useful when profiles are executed through ((doc:Data Channels)). The following is an example of a profile that takes an input "juicetype" and creates/updates a wiki page with content depending on whether "juicetype" is "apple" or "orange".

-+juiceapp.yml+-
{CODE(colors="yaml")}
objects:
  -
    type: wiki_page
    ref: juicepage
    data:
      name: How to Make Your Favorite Juice
      mode: create_or_update
      content:
        - !include apple.yml $profilerequest:juicetype$orange$ eq apple
        - !include orange.yml
{CODE}
-+apple.yml+-
{CODE(colors="yaml")}
content: wikicontent:applejuice
{CODE}
-+orange.yml+-
{CODE(colors="yaml")}
content: wikicontent:orangejuice
{CODE}
-+juiceapp/applejuice.wiki+-
{CODE()}
These are the instructions on how to make apple juice.

Make sure you have a machine juicer. Cut the apple into approximately 6 wedges.
{CODE}
-+juiceapp/orangejuice.wiki+-
{CODE(colors="yaml")}
These are the instructions on how to make orange juice.

First, determine if you are using a machine juicer or a manual juicer. If you are using a manual juicer, cut the oranges into half. If using a machine juicer, peel the oranges.
{CODE}
!Current Limitations
*Included YAML files themselves cannot contain -+!include+- statements.
*There is no way to do ''boolean'' comparisons

!!! Alias
(alias(Conditional Include))
(alias(Conditions))