In this example you will learn:
- What Options are.
- How Options can be used to wrap actions.
- How Options can be used interact with the user.
Options are basically wrappers around actions.
Instead of writing a Rule that performs an action, it is often better to create an Option to perform that action. This is because Options can be interacted with.
Options serve multiple purposes, but the most common ones are:
- To delay performing an action, so that other Rules can be executed first. These other Rules can then decide whether the Option should be executed, or discarded, or delayed until later. The complex interactions between Rules and Options are important for making Elody flexible. This will be shown in detail in later sections of the tutorial. For now, we will just have a look at a demonstration.
- To give the user the ability to choose between alternatives. If two developers both offer a program that can solve the same problem, each of them should create an Option for it, so that the user gets to choose between them.
We will use two different Scenario Plans to demonstrate these uses of Options:
- The Scenario Plan (Tutorial) Option used as a wrapper demonstrates how an Option can wrap around an action, so that its execution is delayed.
- The Scenario Plan (Tutorial) Option used to give a choice demonstrates how Options can be used to offer the user a choice.
The Scenario Plans here work the same way as the one in the first example. The only thing that is different is the Rule. So just pick some appropriate names for the two new Symbols, one for each plan, and otherwise define them in the same way.
Using Options to wrap actions
This Rule is used by (Tutorial) Option used as a wrapper and demonstrates how an Option can wrap around an action:
The Rule has three actions. Action 1 is to print "Message 1", action 2 is to create an Option, and action 3 is to print "Message 2".
The Option has a name, description, trigger and actions, just like a Rule. These values work in the same way. What's different is that the Option also has a confidence value.
The confidence of an Option determines what Elody does with the Option. An Option with a high confidence is executed automatically. One with a low confidence is ignored. One with a medium confidence is presented to the user if possible, so that the user can choose whether or not to use it. Default confidence values can be found in the Best Practices, and will also be explained later in the tutorial.
A confidence of 1000 is very high, and means that the Option will be executed right away. Notably, Elody still finishes executing all actions of the Rule, and only then picks the Option to run next. That is why the Option creates "Message 3", even though the Option itself is created before "Message 2".
Using Options to wrap actions
This Rule is used by (Tutorial) Option used to give a choice and demonstrates how an Option can be used to offer the user a choice:
The Rule creates two Options. Both Options have a confidence of 0.9, which is just below the threshold where Elody executes the Option without asking (1.0) and above the threshold where the Option is ignored (0.5). That means that Elody will present both Options to the user and ask them what to do.
Both Options have a new type of field that only Options can have: display. The display field tells Elody how to display the Option to the user.
The first Option has two values in its display field:
- must_always_be_shown tells Elody that this Option should always be presented to the user for confirmation, and should never be run automatically. This is optional here since the confidence is below the execution threshold of 1.0 anyway, but is usually a good idea to include.
- message_components lists the elements of a Message that is displayed to the user to describe the Option.
The second Option also explicitly defines two buttons for the Option. The first Option does not specify these explicitly, and so just gets a default button when it is displayed to the user.
When the user clicks one of the buttons, the Option is selected and executed. Elody will now execute any actions associated with the button as well as any actions of the Option itself. No matter which button is clicked, the Option counts as selected and will not be shown again. This behavior is heavily customizable: See the later parts of the tutorial or the documentation for details.
In general, it is almost always a good idea to wrap your actions in an Option. We will see exactly why later in the tutorial. However, this tutorial itself does not follow this advice: The next few pages don't use Options unless necessary. This is just to make the tutorial easier to understand by cutting out unnecessary parts. In practice, using Options is recommended.