MobileRead Forums - View Single Post

capink · 04-01-2021, 02:04 PM

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:

You have to set the following attribute:
Code:
```
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.
After setting the above attribute, whenever the action wants to get a list of book_ids to work on, it should call the following:
Code:
```
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.

04-01-2021, 02:04 PM	#484
capink Wizard Posts: 1,185 Karma: 1988646 Join Date: Aug 2015 Device: Kindle	Scopes 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: You have to set the following attribute: Code: 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. After setting the above attribute, whenever the action wants to get a list of book_ids to work on, it should call the following: Code: 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. Last edited by capink; 04-06-2021 at 03:01 PM.