Developing Scripts basics

ComicRack has built in Python scripting support. This article gives a short introduction on how to write scripts. Further information can be found in the API Reference.

What can scripts do?

With scripts you can batch process eComic books in ComicRack. You can select them and call your script. Scripts can change the following properties of eComic books (Comicrack publishes the 'book' object with these properties):

  1. Textual:
    • Writer
    • Publisher
    • Penciller
    • Inker
    • Series
    • Number
    • AlternateSeries
    • AlternateNumber
    • Title
    • Summary
    • Notes
    • Genre
    • Colorist
    • Editor
    • Letterer
    • CoverArtist
    • Web
    • Imprint
    • Tags
  2. Numeric:
    • Count
    • Year
    • Month
    • Volume
    • AlternateCount
    • Rating

There are also some read only properties like ShadowSeries, ShadowYear, ShadowVolume, ShadowCount and ShadowNumber. These are values taken from the filename of the eComic (these are displayed in light gray in ComicRack)

ComicRack also gives scripts some support objects and methods.

ComicRack.App.AskQuestion(question, buttontext, optiontext)
  • A simple question dialog for the script
ComicRack.App.GetComicPage(book, page)
  • Returns a bitmap with the full page image of the specified book and page (pages start with 0)
  • The handle to the main window of ComicRack. Useful when needing a parent window for displaying dialogs.

Additionally you can write scripts to parse eComic path names for initial values or call methods on some special events (like when an eComic is opened).

Writing Scripts

Scripts are Python files (.py) which contain one or more entry method for ComicRack. Entry methods have the following signature:

def RenumberBooks(books):

with books being a collection of book objects with the above specified properties. Whatever you do in this method will be reflected in ComicRack. Let's say you want a quick shortcut to clear the ratings on all books. The script would look something like this:

  def RenameBookFiles(books):
    for book in books:
      book.Rating = 0

Of course you can also build complex user interfaces in your script. As ComicRack uses the Iron Python implementation of Python, you're free to use all .NET can offer. Look at some samples at the site or at the script that comes with ComicRack.

To make it simpler debugging your script you should start ComicRack with the following command line:

ComicRack.exe -dso -ssc

The meaning of these switches is:

  • -dso is Disable Script Optimization

Scripts are always reloaded when executed. Otherwise they are compiled once during startup.

  • -ssc is Show Script Console

With this you get a look at all your script output (good for debugging messages).

Installing scripts

To tell ComicRack what your script does, which data it needs and where to display it in the ComicRack user interface you have to include the following information:

Hook ...        Place where the script will be put in ComicRack 
Key...          Key used to identify this script
Name ...        Name of the menu entry
Method ...      Name of the python method to call
ScriptFile ...  the actual file containing the script

Hook can be one of the following values

Books ...           Places where books can be selected (popup menu)
BookOpened...       Called when a book is opened
ComicInfoHtml...    Used to create html info panels
ComicInfoUI...      Used to create UI Control info panels
ConfigScript...     For creating configuration scripts. Config button in preferences
CreateBookList...   Used to write smart list scripts
Library ...         Script is put on library level
NetSearch...        Used to add a new search to the internet search engine
NewBooks...         Used to create additional commands in the file menu
ParseComicPath ...  Parses comic paths for proposed values
ReaderResized...    For changing viewer properties  

Definitions are put as special comments above the script method declaration.

An example definition would be:

#@Name  Burn Books...      [Defaults to function name]
#@Key   BurnBooks [Defaults to function name]
#@Image BurnImage.png
#@Hook  Books
def BurnBooks(books)

The minimum spec is a #@Hook comment line above the script method.

Packaging and deploying

To easily install scripts into ComicRack you have to package them.

A package is a ZIP file containing all the needed files and an optional package information file. A folder structure is not supported in the package (it must be flat). The information file must be named Package.ini and can have the following content:

Name        = Name of the package (default: filename without numbers)
Author      = Author of the package (default: nothing)
Version     = Version of the package (default: nothing)
Description = Description of the contents of the package (default: nothing)
Image       = A image file used as the icon (default: a package icon)
HelpLink    = Some URL or file link (default: nothing)

If the file or entry is missing, the described default is used.

A simple example would look like this:

Name        = cYo Script Package
Author      = cYo
Version     = 1.0
Description = A collection of useful scripts
Image       = cyo_util.png
HelpLink    =

Put your python files, auxillary files (images, config files, etc), and the Package.ini into a .zip file, then rename the .zip file to a .crplugin file. For example your file structure could look like the following:

It could also look like the following:

Then, rename to MyAwesomeScript.crplugin

Such packages can be simply installed and removed from the Preferences/Advanced dialog.