[GUI Plugin] Action Chains

[chaley]

@capink: how can I get the list of book ids in the current scope in a ChainVariables action?

[capink]

I got it. Will fix by initializing an empty dictionary at startup.

[capink]

Originally Posted by chaley

@capink: how can I get the list of book ids in the current scope in a ChainVariables action?

I can add a template function to do that, but it will only be available when the chain is running. At configure time it will no be available (will return empty list) because it might not be possible to calculate it then (in case of template based scopes that might depend on variables set on runtime). Will call it scope_ids().

[capink]

What is Scopes?

• By default actions work on selected books in library view. If a user wanted to make certain actions in the chain to work on different set of books, the solution was to use the Selection Modifier before that action to alter the selections in calibre before the action is called to act on them. This worked well, but it led to rapid changes in selection when in a chain was running, which can be sometimes unpleasant.
• Scopes provides a mechanism for actions to act on books other than those selected in the library view, so actions can specify what books to act on without the need to alter the selection in the library view.
• Not all actions support scopes. Most notable example of action that does not support scopes is Calibre Actions.
  
  There is a scope column in the Actions Table that show icons indicating whether an action has a scope set or not. Actions that does not support scopes by default will not show any icons.
• Scopes are optional. If an action support scopes but the user has not set any scopes for it, it will fall back to act to books selected in the library view.
• Scopes are configured per action, and will only affect the action they are configured for.

How to use scopes?

• You can open the scopes dialog for the action by either double clicking the icon in the scope column, or by choosing add/modify scope item from the context menu.
• In the combobox in the scope dialog, choose the scope manager you want. After that you will presented with options to choose from.

Builtin actions that support scopes are:

• Single Field Edit.
• Search And Replace.
• Chain Variables (partial support only for variables that have iterate check enabled).
• Open With (partial support only for multiple selection mode).
• Copy To Clipboard (partial support only for multiple selection mode).

Note for developers

If you a writing and action and want it to support scopes you have to do two things:

1. You have to set the following attribute:
   

   support_scopes = True

   When the plugin finds an action that have this attribute set to true, it knows to enable the scope settings dialog for the action. It will also show the relevant icons next to the action in the scope column.
2. After setting the above attribute, whenever the action wants to get a list of book_ids to work on, it should call the following:
   

   chain.scope().get_book_ids()

   The above will look for scope settings configured by the user for the action, if it finds them, it hands them to the scope manager selected by the user to take care of getting the list of book_ids. If no scope settings are configured for the action, it will use a fallback scope manager, which returns a list of books selected in library view.

[chaley]

I just spent some time to try to test book var scopes. I finally got there. It works very well.

First, I was confused about when Chain Variables actions ran. I forgot about the meaning of the "iterate" box. This is why I asked about getting the ids of the scope. With "iterate" I don't need that, and in any event I could get the list using a from_selection('id'). As far as I am concerned you can forget about that "request".

Once I checked 'Iterate' things fell together. The following chain searches all books for "important titles" that contain the word 'all' and updates some metadata. The first action uses an "all books" scope. All the books with "important" titles have a book var set. This action is followed by two single field edit actions with book_var scope that update metadata in the "important" books, specifically storing an altered title and the strlen of the original title.

I tried setting the scope of the second metadata action to "books changed". It worked, but I struggled with the results until I remembered that a book doesn't "change" if the metadata stored an action is the same as already there.

The attached zip contains the chain, in case you are interested.

[ownedbycats]

Question: I made a View action (I previously used the last-viewed column option of Job Spy, but some of its behavior frustrated me):

{
  "ActionsChainMenus": {
    "Menus": [
      {
        "active": true,
        "chain_settings": {
          "chain_links": [
            {
              "action_name": "Calibre Actions",
              "action_settings": {
                "disable_busy_cursor": false,
                "selection": [
                  {
                    "display": "View",
                    "path": [
                      "View",
                      "View"
                    ],
                    "paths_text": "View"
                  }
                ],
                "wait_jobs": false,
                "wait_progress": false
              },
              "comment": "Open book"
            },
            {
              "action_name": "Single Field Edit",
              "action_settings": {
                "col_name": "#read",
                "template": "program:\n\n\tif and(check_yes_no('#read', '', '', 1),) then \t'No'\n\telse $#read\n\tfi",
                "value_type": "template"
              },
              "comment": "Set #read column (TEMPLATE)"
            },
            {
              "action_name": "Single Field Edit",
              "action_settings": {
                "col_name": "#percentread",
                "template": "program:\n\tif raw_field('#percentread', '1') ==# '0' then '1'\n\telse raw_field('#percentread')\n\tfi",
                "value_type": "template"
              },
              "comment": "Set #percentread to 1 (TEMPLATE)"
            },
            {
              "action_name": "Single Field Edit",
              "action_settings": {
                "col_name": "#lastread",
                "value": [
                  {
                    "__class__": "datetime.datetime",
                    "__value__": "2021-03-30T00:13:43.637933+00:00"
                  },
                  true
                ],
                "value_type": "predefined"
              },
              "comment": "Set #lastread to current time"
            },
            {
              "action_name": "Refresh View",
              "action_settings": {},
              "comment": "Refresh view"
            }
          ],
          "refresh_gui": true
        },
        "condition_settings": {
          "affect_menu": false,
          "cmp_type": "=",
          "datatype": "number",
          "icon": "",
          "template": "program: selection_count()",
          "tooltip": "",
          "value": 1.0
        },
        "image": "",
        "menuText": "View",
        "subMenu": "Invisible"
      }
    ]
  },
  "schemaVersion": 1.3
}

I notice that after it opens the book in whatever program is set, the chain seems to stall in the background until I switch back to Calibre. Is this expected?

[capink]

The plugin waits for every action to complete (return control of the main thread) before it proceeds to the next action. So this depends on what calibre viewer is doing.

However, I tested your chain and this behavior does not happen for me. But maybe we have different (viewer) settings that might affect this.

Edit: If you have other reader apps installed on your system, try temporarily making them the default reader (preferences > behavior > un-check use internal view for + make the other reader the default on your system), and see whether this makes a difference.

[capink]

Version 1.5.2

• Update: Actions table: Add button to duplicate actions.

Version 1.6.0

• Update: Add scopes.
• Update: Conditions button is removed and replaced by context menu items.
• Fix: Bug with set_book_vars() when running for the first time when configuring a chain.

@chaley: I've implemented most of your suggestions on the UI (except right click which always opens a context menu). After thinking about them they made more sense than what I was trying to do. Also template scopes is now builtin.

[ownedbycats]

Originally Posted by capink

Edit: If you have other reader apps installed on your system, try temporarily making them the default reader (preferences > behavior > un-check use internal view for + make the other reader the default on your system), and see whether this makes a difference.

It happens for other viewers too - I have .paperbooks set to open with Notepad2 and it still stalls.

[capink]

It is not happening for with any viewer. Would be difficult to investigate without being able to replicate.

[ownedbycats]

I wonder if it might be some sort of OS-specific thing with the window focus. I think you're on Linux.

[capink]

I don't think it is OS specific. If this is, most probably there is nothing I can do about it. Will test later with Windows and see if it makes any difference.

[ownedbycats]

How exactly does this new Scopes feature work? I saw some of the discussion on it and it looks like some sort of replacement for selection modifiers?

Also, how do I get rid of the horizontal scroll bar?

Minor UI suggestion: Perhaps the unlocked conditional icon could be a slightly different colour; something like light skyblue3 or azure3 might work.

[capink]

Originally Posted by ownedbycats

How exactly does this new Scopes feature work? I saw some of the discussion on it and it looks like some sort of replacement for selection modifiers?

It works pretty much the same as the selection modifier. You right click the action and choose the add/modify scope, choose Basic Scopes from the combobox, the rest of the options should be self explanatory.

Note, however, that scopes should be configured per action. Also some actions, most notably Calibre Actions, do not support scopes. Actions that don't support scopes will not have any icons in the scope column, and add/modify scope menu entry will be greyed out for them.

Originally Posted by ownedbycats

Also, how do I get rid of the horizontal scroll bar?

The only way to do this would be by making the dialog wide enough for it to disappear. Nothing has changed regarding this. It has been this way from the start.

Originally Posted by ownedbycats

Minor UI suggestion: Perhaps the unlocked conditional icon could be a slightly different colour; something like light skyblue3 or azure3 might work.

I will see about that.

[chaley]

Originally Posted by ownedbycats

How exactly does this new Scopes feature work? I saw some of the discussion on it and it looks like some sort of replacement for selection modifiers?

In addition to what capink said, scopes don't change the selection.