[GUI Plugin] Action Chains

[BetterRed]

Originally Posted by chaley

I am not sure what problem you are solving, but if what you want to do is open the tags editor from the booklist then SHIFT-F2 does that.

I was going to post something similar, but I don't have this plugin so I assumed OBC wanted something specific to it.

OBC could use the AHK or PTFB utility to send Shift/F2 when he/she presses some other key sequence.

BR

[ownedbycats]

I've been looking into AHK/Pulover's Macro Creator to automate some non-Calibre tasks anyways. I might be able to do something with that.

[Thasaidon]

Originally Posted by ownedbycats

I've been looking into AHK/Pulover's Macro Creator to automate some non-Calibre tasks anyways. I might be able to do something with that.

Good luck. I played with that program some time ago. I even managed to produce some working macros. I found it was not the easiest of programs to master.

[chaley]

Originally Posted by capink

I never use devices with calibre (non rootable kindle, only email one book at a time since collections are useless), so my knowledge here is very limited. I only went for device_uuid as way to prevent name clashes if the user has two similar devices. I will defer to others decide whether a device_uuid is needed.

Name clashing is a good argument for using the uuid. I added the template function current_device_uuid(storage_location). It is in source now.

[capink]

Thanks. Should be useful.

[capink]

The Chain Variables action enables the user to set variables to the chain, to be utilized in multiple ways like marking books or using them in conditional execution of actions. The user can set constant variables, or can set dynamic variables using Calibre's template. When setting dynamic variables using templates, only General Program Mode is supported. i.e templates starting with program.

In addition to user variables, the plugin offers some predefined variables that can be used by the user when setting dynamic variables. These Variables include:

1. Runtime chain variables:
   • _chain_name
   • _chain_iteration
   • _chain_start_time
2. Runtime action variables:
   • _action_name
   • _action_index
   • _action_comment
   • _previous_action_start_time
3. Other variables:
   • location
   • _event_name
   • _event_args

The location values are: library, main, card and cardb. The value depends in which library/device view you are currently in.
The selection count is the number of books currently selected in books view.
The _chain_iteration can be used in conjunction with _chain_name, to prevent clashes with variables set by previous runs of the same chain.

The chain variables action, like other actions, can be used multiple times during the lifetime of the chain to either set new variables, or re-set previously set variable to new values.

All the variables, can be accessed in templates, by using the globals function like the example below

program:
    n = globals(_chain_name);
    i = globals(_chain_iteration);
    strcat(n, '_', i)

Notes:

• Chain variables are only defined when you run the chain. While you are configuring the chain, if you try to access a user defined variable in one if you actions like (e.g. variable defined in a preceding action), like below"
  

  program:
      v = globals(myvar)

  v will be assigned an empty string, since the chain has not run yet and the variable is undefined. This is fine for string variables. But if your variable is being used in mathematical operations like below:
  
  

  program:
      v = 2 / globals(myvar)

  In that case, the template will return an error because an empty string cannot be used in mathematical operations. The solution is to provide a valid default value for the variable:
  
  

  program:
      v = 2 / globals(myvar=1)

[capink]

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:

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:

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.

Notes:

• And conditions are meant as a binary on/off switch on the action as the whole. They are meant as a tool to make the action work for some books and not on others. If you want to restrict the action to certain books, use other tools like the "Selection Modifier" action, scopes or "Search Using Template" action.

[capink]

EDIT: A modified version of this action is available as a builtin action in the action chains plugin starting from version 1.4.0. The builtin action is called "Search Using Templates".

This is a custom action that allows constructing a calibre search using calibre template editor. The search can be a simple text search or a search constructed from a template.

# python3 compatibility
from six import text_type as unicode

from calibre import prints
from calibre.constants import DEBUG
from calibre.gui2 import error_dialog
from calibre.ebooks.metadata.book.formatter import SafeFormat

from calibre_plugins.action_chains.actions.base import ChainAction
from calibre_plugins.action_chains.database import is_search_valid
from calibre_plugins.action_chains.templates import check_template, get_metadata_object
from calibre_plugins.action_chains.templates.dialogs import TemplateBox

try:
    load_translations()
except NameError:
    prints("ActionsChain::action/search.py - exception when loading translations")

class TemplateSearchWidget(TemplateBox):
    def __init__(self, parent, plugin_action, action, name, title):
        self.plugin_action = plugin_action
        self.action = action
        self.gui = plugin_action.gui
        self.db = self.gui.current_db
        mi = get_metadata_object(self.gui)
        TemplateBox.__init__(
                self,
                parent,
                plugin_action,
                template_text='',
                placeholder_text=_('Enter a search expression here. It can be either '
                                   'an ordinary text string or a template.'),
                mi=mi
            )
        self.setWindowTitle(title)

    def textbox_changed(self):
        TemplateBox.textbox_changed(self)
        template = self.template_value.text()
        text = SafeFormat().safe_format(template, self.mi, 'Exception: ', self.mi, template_functions=self.plugin_action.template_functions)
        if text:
            ok = is_search_valid(self.db, text) and not text.lower().startswith('exception:')
            ss = 'QLineEdit { border: 2px solid %s; border-radius: 3px }' % (
            '#50c878' if ok else '#FF2400')
            self.template_value.setStyleSheet(ss)
        else:
            self.template_value.setStyleSheet('')

    def load_settings(self, settings):
        if settings:
            template = settings['template']
            self.textbox.insertPlainText(template)

    def save_settings(self):
        settings = {}
        settings['template'] = unicode(self.textbox.toPlainText()).rstrip()
        return settings

    def accept(self):
        self.settings = self.save_settings()
        # validate settings
        is_valid = self.action.validate(self.settings)
        if is_valid is not True:
            msg, details = is_valid
            error_dialog(
                self,
                msg,
                details,
                show=True
            )
            return
        TemplateBox.accept(self)

class TemplateSearchAction(ChainAction):

    name = 'Template Search'

    def run(self, gui, settings, chain):
        template = settings['template']
        template_output = chain.evaluate_template(template, book_id=None)
        gui.search.clear()
        gui.search.set_search_string(template_output)

    def validate(self, settings):
        gui = self.plugin_action.gui
        db = gui.current_db
        if not settings:
            return (_('Settings Error'), _('You must configure this action before running it'))
        mi = get_metadata_object(gui)
        is_template_valid = check_template(settings['template'], self.plugin_action, print_error=False)
        if is_template_valid is not True:
            return is_template_valid
        search_text = SafeFormat().safe_format(settings['template'], mi, 'Exception: ', mi, template_functions=self.plugin_action.template_functions)
        if not is_search_valid(db, search_text):
            return (_('Settings Error'), _('Search ({}) is not valid'.format(search_text)))
        return True

    def config_widget(self):
        return TemplateSearchWidget

N.B This custom action will not work with Action Chains versions < 1.2.0

[capink]

Version 0.3.99

• Update: Add option to disable wait cursor for calibre actions.
• Update: Add new action "Chain Variables".
• Update: Add support for conditional executions of actions.
• Update: Add support for conditional executions of chains.
• Update: Add support for the new global template function.
• Fix: predefined template error with marked field.

This version only works with the latest calibre version as it makes use of the new "globals" template function. The main change in this version is that it enables setting conditions that determines whether a chain, or an action inside a chain, is going to run. The conditions are set using calibre's template language. Simple examples are illustrated below on how to do this.

This version does change the config file of the plugin to accommodate a change made to Calibre Actions, so you are advised to backup the "Actions Chains.json" file in your plugin folder, just in case. Also the order and width of columns in the add actions dialog will be reset.

Special thanks for @chaley, as most of these features where ideas of his. He was also generous enough to add a new template function that made these new features possible.

@ownedbycats: This version addresses some problems you were having with the plugin.

• You now have a checkbox to turn off the wait cursor for calibre actions.
• The new contaning_folder() template function means you can now use a "copy to clipboard" action to get the containing folder, by using the below template:
  
  

  program: contaning_folder()

  Note that this template makes use of a template function defined by the Action Chains plugin, so it will not work outside the plugin.
  
• Now you can make the chain run only if a certain device is attached. This can be done using the new Chain Conditions dialog, by entering this following in the dialog:
  
  

  template = program: connected_device_name('main')
  datatype = text
  comparison = "="
  condition value = your device name

  In case you have multiple devices with similar names, you can use the newly added connected_device_uuid function instead to prevent name clashes.
  
• Also, to make chains enabled only if one book is selected, use the Chain Conditions dialog as follows
  
  

  template = program: selection_count()
  datatype = number
  comparison = "="
  condition value = 1

  Again, this makes use of new function selection_count(), which is defined by the plugin and will not work outside Action Chains.
  

@compurandom: See the examples above for conditional execution of chains. The exact dialog is available for single actions as well. Also, a new chains variables action is available, where you can set chain variables, either as constant values, or values calculated by templates. You have some predefined variables that you can access from a template using the new globals function. For example if you want to mark books after each action, you can use this template:

program:
    c = globals(_chain_name);
    i = globals(_chain_iteration);
    a = globals(_action_name);
    i2 = globals(_action_index);
    strcat(c, '_', i, '_', a, '_', i2)

You add the previous template in a Single Field Edit template, and the choose the "marked" column. By using the _chain_iteration you make sure that you will not have clashes from books marked by a previous run of the same chain.

At the end of your chain, you can show all books marked by this chain, by using a custom action that constructs a search from templates. In the settings of this custom action, use this template to show all books marked by the chain:

program:
    c = globals(_chain_name);
    i = globals(_chain_iteration);
    strcat('marked:"', c, '_', i, '"')

You can define your own values using the Chains Variables actions, or if you writing custom action and want to define your own variables, you can use this in your code:

chain.set_chain_vars({'myvar': 'myval'})

Note that only strings are supported. Any other type will be discarded (with a message if running in debug mode).

Also, there is the ability to support book specific variables (see the example above about containing_folder). To to this, you add this to your custom action:

chain.set_book_vars(book_id, {'bookvar': 'bookval'})

Finally, when you are evaluating a template, to be able to make use of all the variables set, you should use this:

template_result = chain.evaluate_template('your template code', book_id)

@chaley: since much of this was suggested by you, I would like to hear your feedback. This is still in test mode. I am not sure about Chain Variables action, the only redeeming thing about it; is that it allows setting dynamic values using templates. I also scrapped to two column solution, in favor of the template based Chains/Actions Conditions dialog.

[ownedbycats]

Thank you, and happy holidays!

Another use for the new conditions: I added the same "is device connected?" template to add a new action to my send-to-device chain.

If the device is connected, it'll send the book directly there. Though it'll still appear on the list until I figure out the "if device is not connected" template.

EDIT: I kinda worked around this by setting up a "sync lists if device is connected" action. Clumsy but it works.

[Terisa de morgan]

Originally Posted by ownedbycats

Thank you, and happy holidays!

Another use for the new conditions: I added the same "is device connected?" template to add a new action to my send-to-device chain.

If the device is connected, it'll send the book directly there. Though it'll still appear on the list until I figure out the "if device is not connected" template.

EDIT: I kinda worked around this by setting up a "sync lists if device is connected" action. Clumsy but it works.

Attachment 184246

Isn't easier to do it with the Reading List plugin? I have a list that sends automatically to the device and another one that update the column "Aura One" or "Clara" depending on the device when I connect the ereader to calibre.

Pdta: I see that you're adding it to the list (so manual sync). The sync with reading list is automatic. Sorry for the misunderstanding.

[capink]

Originally Posted by ownedbycats

Thank you, and happy holidays!

Another use for the new conditions: I added the same "is device connected?" template to add a new action to my send-to-device chain.

If the device is connected, it'll send the book directly there. Though it'll still appear on the list until I figure out the "if device is not connected" template.

EDIT: I kinda worked around this by setting up a "sync lists if device is connected" action. Clumsy but it works.

Attachment 184246

Happy holidays for you as well. Nice use for conditions.

I don't use devices in calibre, so my knowledge is not very deep. But, the plugin does define a variable called location, I believe the following template can be used as a condition that makes sure no device is attached:

template = program: globals(location)
datatype = text
comparison = "="
condition value = library

if you want to test that a certain device is not attached, why don't you use the same template in the previous post and change the comparison operator to "!="? am I misunderstanding or missing something?

Edit: Also the icon I chose for conditions does not work well the dark mode, will look for a better one.

[ownedbycats]

globals(location) = library didn't work (I think this actually determines whether you're in 'library' or 'device' view) but setting the device to an arbitrary non-valid value did work.

Originally Posted by Terisa de morgan

Isn't easier to do it with the Reading List plugin? I have a list that sends automatically to the device and another one that update the column "Aura One" or "Clara" depending on the device when I connect the ereader to calibre.

Pdta: I see that you're adding it to the list (so manual sync). The sync with reading list is automatic. Sorry for the misunderstanding.

I do auto-sync my send-to-device list. The condition is for when the device is already connected so I need to toggle a second manual sync.

[Terisa de morgan]

Originally Posted by ownedbycats

I do auto-sync my send-to-device list. The condition is for when the device is already connected so I need to toggle a second manual sync.

Ah, ok, I hadn't caught it.

[ownedbycats]

Another thing to report: The "condition" icon has very low contrast on the dark background. On #2 and #4, it's difficult to see, and #3 and #5 I actually can't see at all unless the line's selected. If it's possible to change UI elements for dark mode, inverting it to white ought to do the trick.