[capink]

The Action chains defines some extra template functions that can be used only within the plugin, to supplement and offer new functionality to calibre's template language. There are two classes of these template functions:

• Functions that are part of the formulas action. You learn more about these functions here. Also note that as of version 1.3.0 these formula functions can be used anywhere in the plugin where you have access to template dialog, not just in the formulas action. Most of these functions are used for mathematical calculations, like sum, mean, min, max ... etc.
  
  Two important functions included in the formulas action (and can also used elsewhere in the plugin); are the from_selection() and from_search() functions. They return a list of values fetched from specified columns. You can see examples of how they work here.
  
  
• Functions defined by the plugin outside the formulas action. These are the following functions:
  1. selection_count()
     This function returns the number of selected books in library view. Can be used anywhere in the plugin, including the conditions evaluator to set conditions of running actions/chains based on number of selected books.
     
  2. containing_folder()
     This functions returns the folder path for the current book.
     
  3. cover_path()
     This functions returns the cover path for the current book.
     
  4. sanitize_path()
     Given a filename, this function will return the same filename after removing illegal characters.
     
  5. set_book_vars()
     This functions allows you to set book specific variables:
     
     

     set_book_vars('my_name', 'my_value')

     This would assign 'my_value' to variable named 'my_name' for current_book.
     
     Note: This function stores variables in a volatile memory that only lasts for the lifetime of the chain. For storing variables persistently, check the set_persistent_vars() function below.
     
  6. book_vars()
     
     Access book specific variables (like those created by set_book_vars)
     

     book_vars('my_name')

     The above would return the value assigned to variable 'my_name' for current_book.
     
     Note: This function only accesses variables stored in a volatile memory that only lasts for the lifetime of the chain. For storing and accessing variables persistently, check the persistent_vars() and set_persistent_vars() functions below.
     
  7. category_items()
     
     This is how to use the new category_items() template function:
     
     

     program:
         category_items('#genre')

     This would return all the #genre tags. You can replace #genre with any other category like tags, authors .... etc
     
     It can also take second optional arg to limit the result to set of book_ids
     
     

     program:
         book_ids = from_selection('id');
         category_items('#genre',book_ids)

     from_selection() can be replaced with from_search() to achieve the same result.
     
     The resulting items are separated by one of the following characters(s):
     1. If the category contains names like the author field, the items are separated with ' & '.
     2. If the category is a field that accepts multiple items like tag, the items are separated with ', '
     3. If the category is a field that only accepts one value like series, the items are separated with ' ::: '. This is necessary because fields like series can contain commas AND/OR ampersands.
  8. last_modified()
     Return the time when database was last modified.
     
     
  9. book_field()
     
     Calls calibre's field() for a given book_id
     
     

     program:
         book_id = 123;
         book_field(book_id, 'title')

  10. book_raw_field()
      
      Calls calibre's raw_field() for a given book_id
      
      

      program:
          book_id = 123;
          book_raw_field(book_id, 'title')