The Conditions Dialog can be used to set conditions on chains or actions. If these conditions are not met, the action/chain will not run. Conditions are made possible by leveraging the powerful yet simple calibre template language. For more on templates, visit this
link.
The best way to understand conditions is through examples. Let's say you want your chain to run only if a certain device is connected to calibre. To do this, use the condition dialog to define the following:
Code:
template = program: connected_device_name('main')
datatype = text
comparison = "="
condition value = your device name
If the above condition is not met, when you try to run the chain, it will popup a message telling you chain will not run because conditions are not met. Optionally, you can tick a checkbox in the chain conditions dialog, to grey out the menu entry of the chain if conditions are not met.
In addition to the usual template functions that can be used to test a variety of conditions (e.g. current_library_name, connected_device_name .... etc), the action chains plugin define some extra template functions that can be used as well. For example, Action Chains defines a function selection_count(), which returns the number of books currently selected in books view. So if the user wants a chain to be enabled only when one books is selected the, he can do it like this:
Code:
template = program: selection_count()
datatype = number
comparison = "="
condition value = 1
Conditions can be defined for actions in the same way. This gives the user the ability to implement branches in his chain, where certain set of actions are carried out under one condition, while other actions are carried under a different condition.
The condition dialog available for both chains/actions, can be applied simultaneously to multiple chains/actions.
N.B Variables defined by the user through Chain vars action, can be accessed by using the globals() template function. These also can be used in testing conditions. For more on this see this
post.