View Single Post
Old 11-20-2020, 02:01 PM   #1
capink knows more than wikipediacapink knows more than wikipediacapink knows more than wikipediacapink knows more than wikipediacapink knows more than wikipediacapink knows more than wikipediacapink knows more than wikipediacapink knows more than wikipediacapink knows more than wikipediacapink knows more than wikipediacapink knows more than wikipedia
Posts: 270
Karma: 47128
Join Date: Aug 2015
Device: Kindle
[GUI Plugin] Action Chains

Using this plugin you can define action chains that can be run from menu entries or an assigned keyboard shortcut. A chain can contain one or more action(s) that are run sequentially.

Available Actions:
The plugin defines some builtin actions you can use, it also provides a module editor where you can write your own actions using python.
  • Open With: Similar to the open with plugin, but with some modifications. Used in this plugin it allows you to chain it to other actions. e.g. update timestamps
  • Single Field Edit: Allows you to edit the value of a single field for selected books. You can choose the value at run-time, or use a predefined value, or define a template.
  • Search and replace: This action is based on calibre's search and replace and have the same interface, only difference is that it allows you define the values ahead of time in your chain. At run-time, it gets the predefined search/replace values and executes them, giving you the ability to chain it to multiple other actions (other search/replace or other actions).
  • Calibre Actions: This action allows you to choose an action from calibre interface actions, for the purpose of chaining it to other actions.

    There are some limitations on using calibre interface actions, see limitations section for more detail on this.
  • Selection Modifier: This action is useful when chaining actions together as it allows you to change the selections in calibre before an action. There are multiple criteria for modifying the selections. More on this below.
  • Copy to Clipboard: copy book metadata for selected books to clipboard. You choose the data copied by defining a template.
  • Formulas: Excel like formulas. e.g sum, mean, median .... etc. This action leverages calibre template language. Formulas can be entered at runtime or can be predefined. For more on this see this post.

  • Calibre Actions does expose most of calibre interface actions, but not all of them are suitable for use with this plugin. The reason is that some of these actions have their own progress bar, so they run the code on a different thread. So whenever you use an of these actions, the next action in the chain will start before they finish because they are on a different thread.

    Some other actions, like convert books, run one or more jobs, so the same problem is happening here. There is no way to run these action sequentially with other actions. They can only be used as the last action in a chain.

    Some other actions pop up dialogs so they might not be suitable for use mid-chain. This is why I added the search and replace action to avoid this happening.

    I have removed some of these actions like add books, remove books, convert books. But I cannot hunt down every possible action that might cause such problems, so you always have to test before using them.

    The best way for someone wanting to use one of these removed calibre action, is to write a custom action using the module editor.
  • The chain runs in the main gui thread because some actions cannot happen in a thread other than that of the main gui. As a result, the abort button for the progress bar (which is displayed in the status bar) is non responsive, so I removed it. There is currently no way to stop the chain midway.

How to use the plugin:

To make a new chain follow these steps:
  • From the drop-down menu choose the customize plugin entry to open the config dialog.
  • In the config dialog press the add button to add a new empty chain.
  • Double click on the name field to give the new chain a name, and optionally choose a sub-menu and an icon.
  • To start adding actions to the chain, press the settings button in the chain row, which will open the add actions dialog.
  • In the add actions dialog, press on the add action button. After this choose and action you want from the actions combo-box. Press the action settings button configure the action.
  • Repeat for all actions you want to add, and then press OK.

Suggested Use Cases:

Here are some tips to help get you started:
  • Chaining multiple search/replace actions to together.
  • Adding a chain to edit the rating value and applying a custom last_rated_date timestamps afterwards. For this chain, you need two actions:
    • for the first action select Single Field Action and configure it by choosing the rating field and ticking the option to ask for value at run-time.
    • Add a second Single Field Action to apply the timestamps to your custom last rated date field. This time set it to a predefined value, then check the option "set to current time".
    Whenever you run this action through the menu or a keyboard shortcut, a rating dialog editor will pop up, choose the rating you want and it will apply to all selected books together with the timestamps.
  • You can take the above idea one step further, by defining 5 chains and assigning each one to a different keyboard shortcut. In each of those chain, instead of letting the chain ask you for a value at run-time, specify a predefined value for each chain, starting with value of ★ for the first chain and repeating for the others until you reach ★★★★★ for the last chain. Each chain can contain an extra action for timestamps as in the previous example. Now you can rate your books with configured shortcuts. To make this easier, there is a copy button that allows you to copy chains.
  • You can use the edit metadata form Calibre Actions, together with a Single Field Action to modify a custom last_modified column afterwards. Note, however, that you need to add a Selection Modifier Action in-between and set it to select books modified by last action. More on this in the note about the Selection modifier below.

    You can use this action exclusively for editing book metadata, and it will update you custom last modified date column, which unlike calibre's last modified column, will not be subject to change by other actions like adding custom columns or changes in the tag editor.

    This will not cover other situations like bulk metadata download action for instance as this action starts a background job and is not suitable for use in chains.

    Note: you need to insert the selection modifier even if you are using a single metadata edit dialog, as this dialog can change selections through the next and previous buttons, and by applying the selection modifier, it will select all books whose metadata have been updated.
  • You can use the template feature in the Single Field Action to setup persistent composite columns. Note however that while it might improve performance for huge libraries, you lose the convenience of composite columns being updated automatically, so you will have to run the chain periodically to update them.
  • A chain does not have to contain multiple actions, you can have a chain with only one action. For example you can have multiple chains for different copy to clipboard templates. As an example, if you want to copy a format (e.g. epub) path to clipboard, create a chain containing a single copy to clipboard action with the following template:
    program: select(formats_paths(),'EPUB')
  • Another action that can be used alone in a chain is the Formulas action. For more on formulas, see this post.

Note on the Selection Modifier Action:
  • Since all the actions are selection dependent, the Modifier Selection Action gives you the option to change the current selection ahead of any action. You can choose only books modified by previous action, or you can specify search criteria to further narrow down you selections
  • If you choose a search to narrow down you selection, this will only change the current view of calibre to results of this search, so you need tick option "select all books in current view" together with the search.
  • Some actions may affect only some of the selected books. For example if you use the bulk metadata editor to remove certain tags, this action will only affect books that have that tags. If you want your next action to apply only to modified books (e.g. you want to add timestamp to only modified books), add a Selection Modifier to change the selections to "books modified by last action"

Note on Module Editor:
  • For information on how to write your own actions, see the comments in calibre_plugins.action_chains.actions.base
  • Instead of making a plugin for every small task you want, you can use the module to add a custom action and add it to its own chain, which will get its own menu entry.
  • For examples on how to write a simple custom action, see here. Another example that illustrate how to add a settings dialog to a custom action can be found here.

Custom actions:
  • A list of custom actions posted on this thread is maintained here.

Conditional execution for chains and actions (branching):
  • For more information on how to implement conditions on chains and actions, that allows for branching, see this post.

  • The icon dialog and the dynamic menus are based on code from the Open With plugin by kiwidude.
  • The Open With action is based on code from Open With plugin by kiwidude.
  • The Calibre Actions is based on code from the Favourites Menu plugin by kiwidude.
  • The module editor is based on calibre editor function editor by Kovid Goyal.
  • The Search and Replace Action is based on calibre's search and replace. (chaley and Kovid Goyal)
  • Special thanks for chaley for introducing the globals template function, that is used by the conditions dialog.

Installation Notes:
Special Notes:
  • Requires Calibre 5.8.1 or later.

Paypal Donations:
  • If you find this useful please feel free to show your appreciation.

Version History:

Version 0.6.2 - 11 January 2021
Update: Spanish translation. Thanks to @dunhill

Version 0.6.1 - 1 January 2021
Update: Add Formulas Action. (experimental)

Version 0.6.0 - 31 December 2020
Fix: Open with handle books selected with missing formats.
Fix: Conditions Evaluator choose active index instead of first selected book.
Fix: Calculate selection count once in about_to_show_menu when evaluating conditions for chains to prevent the menu from taking long time to show.

Version 0.5.3 - 30 December 2020
Fix: Another regression in icon combobox.
Fix: Regression in check templates.
Fix: Error converting int output from templates.

Version 0.5.2 - 29 December 2020
Fix: Regression in icon combobox.

Version 0.5.1 - 29 December 2020
Minor fixes.

Version 0.5.0 - 26 December 2020
Update: Add event manager.
Update: Add optional icon and tooltip entries in Conditions Dialog.

Version 0.4.0 - 22 December 2020
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: pre-defined template error with marked field.
Fix: problem in open with action when using multiple selections in windows.

Version 0.3.3 - 19 December 2020
Fix: Problem with Calibre Actions "show marked books"

Version 0.3.2 - 17 December 2020
Minor bug fixes.

Version 0.3.1 - 4 December 2020
Fix: Reset errors after changing action settings.
Minor bug fixes.

Version 0.3.0 - 3 December 2020
Update: Add option to clear value in the single field edit.
Fix: Allow the user to choose undefined predefined values for bool, enumeration and rating field types.
Fix: Multiple other fixes to the single field edit.
Fix: When copying a chain in the customize dialog, ensure the name is unique

Version 0.2.1 - 1 December 2020
Update: make columns movable.
Update: save and restore columns state.

Version 0.2.0 - 29 November 2020
Update: re-write add actions as a table dialog.
Update: re-write config dialog table.

Version 0.1.2 - 23 November 2020
Update: Add marked column to single field edit action.
Fix: Turn off the wait cursor temporarily while single edit field dialog are on.
Fix: Refresh gui after running chain.
Fix: Problem with calibre's show all marked books chaining its name depending on number of marked books, messing up the stored setting in calibre actions.

Version 0.1.1 - 20 November 2020
Fix: Problem with predefined dates set to today.

Version 0.1.0 - 16 November 2020
Initial Release.

Attached Thumbnails
Click image for larger version

Name:	1.png
Views:	113
Size:	48.8 KB
ID:	183718   Click image for larger version

Name:	2.png
Views:	117
Size:	62.0 KB
ID:	183719   Click image for larger version

Name:	3.png
Views:	112
Size:	36.3 KB
ID:	183720   Click image for larger version

Name:	4.png
Views:	96
Size:	84.0 KB
ID:	183721   Click image for larger version

Name:	5.png
Views:	99
Size:	49.9 KB
ID:	183722   Click image for larger version

Name:	6.png
Views:	89
Size:	32.4 KB
ID:	183723   Click image for larger version

Name:	7.png
Views:	81
Size:	44.7 KB
ID:	183724   Click image for larger version

Name:	8.png
Views:	82
Size:	19.9 KB
ID:	183725   Click image for larger version

Name:	9.png
Views:	83
Size:	38.2 KB
ID:	183726  
Attached Files
File Type: zip Action (154.5 KB, 301 views)

Last edited by capink; 01-11-2021 at 08:26 PM. Reason: version 0.6.2
capink is offline   Reply With Quote