Search the Internet Plugin Help

Customising the ‘Search the Internet’ Menu

Url Tokens

Custom Image Folder Location

Adding Custom Menu Images

Using a Different Web Browser

Backing Up Your Settings

Known Issues

Further Help

Customising the ‘Search the Internet’ Menu

Each row in the grid in the plugin configuration dialog represents a possible menu item to include in your menu. Included with the plugin are many websites for your convenience to select from, or you can add your own (or edit the existing ones) as required.

The following table details each column in the grid. You can double-click any cell in the grid to edit its value.

Active	Items ticked in this first column will appear in your menu. A small selection of menu items have been ticked as a default selection to get you started.
Menu Text	The name to appear in the menu. Leave this blank if you want a separator row to appear between your menu items (other columns will be ignored). You must have a value in this column before you can edit the later columns. Erasing the value in this column will clear the other columns (as not valid for separator rows)
Submenu	An optional sub-menu name to display this menu item within. If you have many menu items you may find it more manageable to group them within sub-menus. So for instance typing Amazon into this column for all the Amazon rows in the grid will ensure they are displayed within an “Amazon” sub-menu when the “Search the Internet” menu is expanded.
Open Group	You may like to open multiple website links at once automatically with a single click. If this is the case, tick this checkbox for each row in the menu that you would like to include in this special group. If one or more menu items have this ticked then a special “Open Group” menu item will appear near the bottom of the “Search the Internet” menu. Note that if no active menu items have this option ticked, the “Open Group” option does not appear.
Image	The filename of an image icon to display next to your menu item, leave blank for no image. Images for the supplied menu items are included in the plugin zip file. To add your own image files, choose the Add New Image... menu item within the combobox.
URL	The web URL address of the website to launch. Uses the Calibre template language for tokens – examples are {author}, {title}, {publisher}  and {isbn}. These will be substituted from the selected books when you click the menu item. You can also do more complex formulas such as {author:re(\+, )} to pass the author name separated by spaces instead of + signs.
Encoding	The encoding to use when translating title and author names stored in Calibre into a format for passing to the website. Of particular importance to users with foreign language titled books. The default of utf-8 should be sufficient for most websites, however latin-1 is required for Amazon sites at least.
Method	Whether to use HTTP GET (default) or POST to submit the search. For any website that you can query by pasting the url into the browser, you can leave at the default of GET. For some websites (see FictionDB) the data must be submitted from a hidden form via POST. Specify your name/value pairs in your url exactly the same as you would for a querystring .

The buttons available perform the following functions:

• Move Up / Move Down – Change the order the included items will appear in your menu. You can select multiple rows at once to move up and down.
• Add – Adds a blank row for you to create your own website menu link below the currently selected row.
• Delete – Allows you to remove menu items from the list completely. Although this should rarely be necessary as you can just untick an item to not display it.
• Reset to Defaults – Can be used if you want to discard all your changes and return to the plugin default menu. You will be prompted to confirm this action before proceeding, as this will remove any custom menu items or other changes you have made to ordering, shortcuts etc. Should you change your mind after the change you can cancel all changes made in the configuration dialog when you exit.
• Keyboard Shortcuts... – Launches the Calibre shortcuts dialog showing all of the available active menu items that you could apply a keyboard shortcut to along with their current settings.

In addition there is a context menu available within the grid, offering these options:

• Add image – Alternative way to add new images to the Calibre images repository for use by the plugin. Functionally equivalent to that in the dropdown image combo, except that if you add an image it will not change the image name selected in the dropdown values.
• Open images folder – Allows direct access to the Calibre configuration folder for your custom images. If the folder does not yet exist you are prompted if you would like to create it.
• Move active to top –  Moves all of the rows you have checked as active to the top of the grid. You may find this useful to help focus on editing just the menu items of interest to you.
• Test url – Launches the selected website url(s) using the last test data selected using the menu option below it.
• Test url using... – Opens a dialog allowing you to specify which test book data to use and then launch the selected website url(s) without closing the configuration dialog. A number of example books have been included to suit various international websites, the values for each can be overwritten if desired.
• Import... – Allows importing of menu items from a .zip file, created using the Export menu item described below. Can be used to import menu items created by other users, or your own if you use Export to back them up. All menu items imported will be inserted below the currently selected row, along with any images they require.
• Export... – Allows you to export the selected menu item(s) to a .zip file, which is actually a .zip file with a renamed extension. All data for those selected menu items entered will be stored in the .zip file along with any custom images you may have added. This feature could be used to share menu items with other users, or as an alternative way to backup your menu settings.

The final option on this screen allows you to specify a keyboard shortcut for the Open Group menu item to open multiple website links at once. As mentioned above this menu item only appears in your menu if you have checked the Open Group column for one or more menu items that also have Active checked.

Url Tokens

The following tokens are examples of those supported for substitution at run-time using data from the selected book. Most should be self explanatory. Note that as of version 1.5 this plugin uses the Calibre template language so more complex formulas or other metadata fields are possible.

Note that for all fields that their values are encoded for safely passing as part of a URL, such as replacing spaces with + signs. So if you apply a formula it will be with the encoded version of the value.

{author}	The author of the book (first if there are multiple). If your authors are stored in LN, FN format, the name will be flipped in an attempt to always pass the name in FN LN format. For querystring purposes, any spaces are replaced with + signs, so it will be generated as FN+LN
{title}	The title of the book.
{publisher}	The publisher of the book
{isbn}	The 13-digit ISBN number of the book.

Adding Custom Menu Images

You have several choices for how you add custom .png images for your menu items.

The easiest way is to expand the Image column dropdown on the configuration dialog for the plugin and select the Add New Image... menu option. This will show a configuration dialog allowing you to source the image:

• From web domain favicon - Use this option to download the image file that you see in your browser location bar/bookmarks when you navigate to the website. It uses a google service (http://www.google.com/s2/favicons?domain=xxx) which returns the image as a png file for you to save. You just need to type the top level domain name such as www.google.com or www.amazon.com along with the name to save it as.
• From .png file - Allows you to copy a .png file from your local drives to the correct Calibre location for you.

Alternatively if you want to place them manually these should be placed in a \resources\images folder within the Calibre configuration folder as described in the Calibre help. You can find this directory by using:

    Preferences -> Miscellaneous -> Open calibre configuration directory

You can also use the Open images folder context menu option available in the menu items grid on the configuration dialog for this plugin.

It is quite probable as a first time user you do not already have the required resource subfolder. If that is the case create the \resources\images subdirectories yourself.

Using a Different Web Browser

The behaviour of this plugin is to display web pages using the system configured default web browser, opening each page in a new tab.

If you wish to use a different web browser than your system default, then you can do this by modifying the environment variables for while Calibre is running (such as using a batch file to launch Calibre). The help file for webbrowser.py states the following:

“If the environment variable BROWSER exists, it is interpreted to override the platform default list of browsers, as a os.pathsep-separated list of browsers to try in order. When the value of a list part contains the string %s, then it is interpreted as a literal browser command line to be used with the argument URL substituted for %s; if the part does not contain %s, it is simply interpreted as the name of the browser to launch.”

Backing Up Your Settings

Menu items are persisted into a “Search The Internet.json” file located within the calibre configuration directory for plugins (see above). So if you backup your Calibre configuration directory these settings will be included. Along with all your other Calibre preferences.

You may also chose to use the Export... right click feature to save your settings in a .zip file that can be re-imported at any time.

Known Issues

• Calibre decides on startup whether to scan the resources\images folder for custom images only if that folder exists at that time. The very first time you add a custom image using this plugin it will create this directory for you if it does not exist. However in that one scenario you will need to restart Calibre before any custom images you add will be displayed within Calibre. If the directory already exists when Calibre starts, then any new images you add will be displayed immediately. This limitation is by design for performance reasons.
• Retrieving the favicon for a website using Google’s service (as done underneath the covers by this plugin) will lose any transparency for the image. If the icon is a 16x16 coloured square this is unimportant, however icons that are “shaped” with a transparent background will instead have a white background. If this is important to you either edit the downloaded .png manually to erase the background or download it by looking at the web page source code.

Further Help

For any problems, issues or obtaining the latest version of this plugin, please refer to the MobileRead Forums Search The Internet thread.