View Single Post
Old 11-20-2020, 01: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: 501
Karma: 47410
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.

  • The chain runs in the main gui thread because some actions cannot run 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 "Add/Modify chains" 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.
  • You can use the Library View Double Clicked event to change the default action to any calibre action you want, by using the Event Manager to connect the event to a whatever chain you want. For more on this, 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".
  • The point above applies to adding new books. If you want to select all books added by last action, add a selection modified right after the add action, with option "Select books modified by last action" checked.
  • For users who have the highlight search setting turned on, the selection modifier will temporarily turn it off, and then restores it back after it finishes. This is done to allow the "select all books in current view" option to work as expected when combined with a search.
  • Starting with version 1.6.0, the plugin introduced a new feature called scopes that can replace the functionality of the selection modifier. Note that not all actions support the new scopes feature, so some actions, most notably Calibre Actions, will still depend on the Selection Modifier specify which book they will act on.

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.

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.

Action chains template functions:
  • Action chains define some extra template functions to supplement calibre's template language. You can read more on this here.

  • Starting with version 1.6.0, the plugin introduced a new feature called scopes that can replace the functionality of the selection modifier for actions that support this new feature.

Event Manager
  • Starting with version 0.5.0 actions chains added an event manager where you can configure chains to run in response to events. You can read more on this here.

Action chains API (Experimental)
  • Starting with version 1.4.0 actions chains added an experimental API that enables other plugins to communicate with action chains. You can read more on this here.

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

Misc tips:
  • A list of some of the tips posted on this thread is maintained here.

Misc links
  • 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 multiple modifications to template language and dialog that are used by the plugin.

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

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

Version History:

Version 1.9.0 - 16 May 2021
Update: Allow adding separator to submenus.
Update: Calibre Actions: Add device actions.
Minor Fixes.

Version 1.8.10 - 14 May 2021
Fix: Search And Replace: Regression in validation.
Fix: Regression in chain validation.

Version 1.8.9 - 13 May 2021
Fix: Bug: ,
Update: Chain Variations (Experimental): Rename _chain_argument into _variant_argument

Version 1.8.8 - 09 May 2021
Fix: Single Field Edit: Fix but where "Clear Value" does not work for the standard date column "timestamp".

Version 1.8.7 - 06 May 2021
Fix: KeyError when validating Open With action.

Version 1.8.6 - 05 May 2021
Fix: Regression in Single Field Edit when processing templates for marked field.
Minor improvements.

Version 1.8.5 - 05 May 2021
Fix: KeyError when having and empty event.

Version 1.8.4 - 05 May 2021
Update: Events: Store event arguments as chain variable _event_args.
Update: New Template Functions: field_names() and field_metadata()
Minor Fixes.

Version 1.8.3 - 27 April 2021
Some modification to allow the Chain Caller to have access to unsaved chains and to the parent chain name.

Version 1.8.2 - 27 April 2021
Update: Experimental: new "Chain Caller" action.
Minor changes.

Version 1.8.0
Update: New template functions: sanitize_path(), cover_path().
Update: Events: New "Calibre Initialized" Event.
Update: Experimental: New chain variation feature.
Update: Open With: Template GPM can be used for command arguments.
Fix: Crash if you delete a row from the actions table with editor open but no action selected.

Version 1.7.2 - 14 April 2021
Fix: Regression that led to chain conditions not being checked when called from keyboard shortcut.
Fix: Pass option to disable QApplication.processEvents() when a "Library View Double Clicked" is activated as it leads to active cell entering edit mode on double click for chains that have more than one action.
Update: Changes to the button delegate to make it behave like a real button.
Update: Search Using Templates: Add option to make template return a list of book ids.

Version 1.7.1 - 13 April 2021
Fix: Regression with conditions because of a missing import.

Version 1.7.0 - 9 April 2021
Update: Add persistent storage for templates. Can be accessed using these new template functions: persistent_vars(), set_persistent_vars(), list_persistent_vars(), delete_persistent_vars(), list_persistent_namespaces(), delete_persistent_namespaces()
Update: Copy To Clipboard: Add option to write to a file.
Update: Chain Variables: Add option to ask for variables at runtime.
Update: Library View Double Clicked: tweak to allow single click edit (action_chains_single_click_edit).
Update: Add a tweak to allow disabling submenu inheriting first action icon (action_chains_default_sub_menu_icon).
Update: Update the way table state is saved to avoid messing it up every-time a new column is added.
Update: Add options to customize scope icon and tooltip.
Update: Add new template function: list_book_vars().

Version 1.6.2 - 4 April 2021
Fix: Template Scopes: Discard book ids not currently present in library.
Minor changes to the icons.

Version 1.6.1 - 2 April 2021
Fix: Scope dialog should not open when double clicking on actions that does not support scopes.
Fix: Bug when importing settings and resources/images file is not present.

Version 1.6.0 - 2 April 2021
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.

Version 1.5.2 - 27 March 2021
Update: Actions table: Add button to duplicate actions.

Version 1.5.1 - 26 March 2021
Fix: bug in treecombbox adding extra levels of user actions for every time the delegate is initiated.
Remove to_timestamp as it is made obsolete by the new changes introduced to calibre's format_date().

Version 1.5.0 - 25 March 2021
Fix: Calibre Actions: Bug that allowed choosing two actions if they are not top level items.
Update: Calibre Actions: Add option to wait for jobs started by action to finish before proceeding.
Update: Calibre Actions: Add option to wait for progress bar started by action to finish before proceeding.
Update: Calibre Actions: re-add previously excluded action like add books, remove books, convert books ... etc as they can be used with newly introduced options.
Update: New template function to_timestamp which makes it possible to do date comparisons by converting date to float numbers.
Update: Add new event: Library View Double Clicked.
API changes: Rename some methods.

Version 1.4.3 - 23 March 2021
Fix: Module editor failing to load source if it contains errors (e.g imported objects that no longer exist).
Minor modification to the TemplateBox.
Events: pass singal args to the Event loop.

Version 1.4.2 - 17 March 2021
Update: Single Field Edit: Add identifiers.
Fix: bug when deleting multiple non-contiguous rows.

Version 1.4.1 - 16 March 2021
Fix: Bug with colors in the tree combobox when in dark mode. Thanks to @chaley.

Version 1.4.0 - 15 March 2021
Update: Add a new Action: Search Using Templates.
Update: Change actions/events combobox into tree combobox.
Update: Import/Export: Include schema version plus other minor changes.
Update: Conditions Evaluator: Add option to turn off action validation of conditions are not met. The default as of this version if to verify all actions regardless of conditions unless this option is checked.
Update: (Experimental) Add two API methods: action_chains_resources(), on_action_chains_modules_update(). The first enables other plugins to provide action chains with resources (actions, events, template_functions). The second method makes the modules manager available for other plugins.
Code refactoring.

Version 1.3.3 - 5 March 2021
Fix: Calibre Actions: Always persist non translated strings in settings. This is done to avoid the settings being invalid if the the user switches languages.

Version 1.3.2 - 27 February 2021
Minor changes to TemplateBox.
Minor changes to category_items() template function.

Version 1.3.1 - 26 February 2021
Fix: For chains triggred by events, if conditions are not met, print a message to the status bar instead of an error dialog.
Fix: Single Field Edit: Bug when setting marks from template.
Single Field Edit: Some minor technical changes (pass plugin_action instead of db).

Version 1.3.0 - 21 February 2021
Fix: from_selection() and from_search() formulas always return a constant list of 1,2,3,4,5 when in any template dialog, no just in the formula dialog.
Update: Add new template function: category_items().
Update: Chain Variables: Double clicking the value cell always opens the formula dialog.

Version 1.2.4 - 20 February 2021
Update: Selection Modifier: Add two new options: "Clear Selections", "Select first book in current view"
Update: Add new template function set_book_vars.
Update: Chain Variables: Guarantee order of processing of variables is same as order in table.
Update: Chain Variables: Double clicking value cell will open template dialog if value start with "program:"

Version 1.2.3 - 20 February 2021
Update: Chain Variables: Add option to loop over all books per var in the table.
Update: Chain Variables: Right clicking value cell opens template editor.
Update: Add new template function book_vars to access book specific variables set by custom actions (using chain_loop.set_book_vars). They are no longer accessible from the globals template function, to provide consistent behavior that enables set_globals to work the same everywhere.
Fix: Formulas: Bug with mean value when fed an empty list or a list with no numerical values. It now handles it by returning 0.

Version 1.2.2 - 19 February 2021
Fix: Formulas: Give the template processor access to the chain_vars.
Update: Formulas functions available as part of template_functions and can be accessed from any other action in the plugin.

Version 1.2.1 - 15 February 2021
Minor bug fix.

Version 1.2.0 - 13 February 2021
Fix: Selection modifier: make sure to temporarily turn of search highlighting (if turned on by the user), to allow for the selection of all books in current search only.

Version 1.1.1 - 12 February 2021
Update: Single Field Edit: Setting template output to empty string deletes the column value for all datatypes.

Version 1.1.0 - 12 February 2021
Fix: Single Field Edit: Don't update column value if template returns a value identical to the current value.

Version 1.0.0 - 3 February 2021
Update: Allow Nested sub-menus by using ::: as a separator.
Fix: Single Field Edit: Bug checking enum types when applying templates.
Fix: Importing entries should not allow duplicate chain names as it leads to errors when menus are re-built.

Version 0.7.1 - 26 January 2021
Minor bug fix.

Version 0.7.0 - 26 January 2021
Update: Modify TemplateBox, ConditionsEval, FormulaEditor to use the new changes introduced by chaley that allow adding custom widgets to the Template Dialog, and pass functions to the initiator. Now they all inherit from the calibre's TemplateDialog without the need to re-implement any methods. This makes template functions defined by the plugins more integrated as they can be highlighted and also show their own source and documentation in the appropriate places in Template Editor.
Update: Allow hiding menu entries by putting them in a submenu called invisible.

Version 0.6.5 - 20 January 2021
Update: make disabling menu items based on chain conditions optional.
Fix: Bug where chain conditions are unnecessarily tested for actions without their own condition.

Version 0.6.4 - 18 January 2021
Update: add selection_count template function instead of the old way of pre-calculating selection count as a global_var

Version 0.6.3 - 17 January 2021
Update: Prior to running a chain, only validate actions that have no conditions, or those that have conditions that evaluate to true.

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

Version 0.6.1 - 3 January 2021
Update: Add formulas action.

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 when "Show marked books" is selected.

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:	364
Size:	48.8 KB
ID:	183718   Click image for larger version

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

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

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

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

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

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

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

Name:	9.png
Views:	270
Size:	38.2 KB
ID:	183726  
Attached Files
File Type: zip Action (200.0 KB, 1868 views)

Last edited by capink; 05-22-2021 at 06:50 PM. Reason: version 1.9.0
capink is offline   Reply With Quote