Differences

This shows you the differences between two versions of the page.

--- covers:integration-guide [2026/07/17 01:51]
jposeika
+++ covers:integration-guide [2026/07/17 04:46] (current)
jposeika
@@ Line 14: / Line 14: @@
   * URL: ''https://content.chilifresh.com/''
   * Method: //GET//
-  * Available both over plain HTTP and SSL
   * Output: GIF image
@@ Line 32: / Line 31: @@
 ^ Parameter ^ Type (size) ^ Mandatory ^ Description ^
-| ''isbn'' | Variable characters | Yes (at least one identifier) | Item's ISBN (ISBN-10 or ISBN-13). Multiple ISBNs can be passed as a comma-separated list — processed in order, first existing cover is returned |
+| ''isbn'' | Variable characters | Yes (at least one identifier) | Item's ISBN (ISBN-10 or ISBN-13) |
 | ''upc'' | Variable characters | ::: | Item's UPC |
 | ''oclc'' | Variable characters | ::: | Item's OCLC number, with the ''%%(OCoLC)%%'' prefix (not case sensitive), as it appears in the bibliographic record |
@@ Line 41: / Line 40: @@
 | ''showerror'' | Boolean | No | Default //false//: if no image is returned, the output is a blank 1x1 px GIF. Set ''showerror=true'' to return an HTTP 404 error instead |
-At least one identifier parameter (''isbn'', ''upc'', ''oclc'', ''lccn'' or ''issn'') must be present. Several identifier parameters can be combined in one request — see below.
+At least one identifier parameter (''isbn'', ''upc'', ''oclc'', ''lccn'' or ''issn'') must be present. **Any identifier parameter accepts multiple values as a comma-separated list**, and several identifier parameters can be combined in one request — see below.
 ==== Supported identifiers ====
@@ Line 48: / Line 47: @@
 ^ Parameter ^ Identifier ^ Notes ^
-| ''isbn'' | ISBN | ISBN-10 or ISBN-13. Multiple ISBNs can be passed as a **comma-separated list** |
+| ''isbn'' | ISBN | ISBN-10 or ISBN-13 |
 | ''upc'' | UPC | |
 | ''oclc'' | OCLC number | Currently expected **with the ''%%(OCoLC)%%'' prefix** (not case sensitive), exactly as the number appears in the bibliographic record — including any ''ocm''/''ocn''/''on'' prefixes if present. See examples below |
 | ''lccn'' | LCCN | |
 | ''issn'' | ISSN | |
+Each identifier parameter accepts either a single value or **multiple values as a comma-separated list**.
 **Provide multiple identifiers at once** — pass all identifiers you have on the bibliographic record in a single request:
@@ Line 62: / Line 63: @@
 Identifiers are processed in the order provided and the **first existing cover image** is returned. Supplying every identifier you have (ISBN, UPC, OCLC, …) maximizes the chance of retrieving a cover.
-The same applies to multiple values of the same identifier type: pass several ISBNs from one record as a comma-separated list — they are processed in order and the first match is returned:
+The same applies to multiple values of the same identifier type: pass them as a comma-separated list — they are processed in order and the first match is returned. Example with several ISBNs from one record:
 <code>
@@ Line 112: / Line 113: @@
 | OCLC number | ''%%https://content.chilifresh.com/?oclc=(OCoLC)ocm50035236&size=M%%'' |
 | No generic image, 404 on miss | ''%%https://content.chilifresh.com/?isbn=9780578033440&generic=false&showerror=true%%'' |
+===== JavaScript library =====
+For client-side integrations, ChiliFresh provides a small dependency-free JavaScript library that builds cover URLs, injects the ''<img>'' elements and handles items without covers (hide the element, or show your own placeholder). It uses the direct image retrieval method described above — no extra API calls are made.
+  * Library: [[https://content.chilifresh.com/js/chilifresh-covers.js|https://content.chilifresh.com/js/chilifresh-covers.js]]
+  * Live demo: [[https://content.chilifresh.com/js/demo/|https://content.chilifresh.com/js/demo/]]
+**Remember:** add your catalog/web page hostnames in ChiliFresh Admin panel -> Covered hosts before going live.
+==== Declarative usage ====
+Mark elements with ''data-cf-*'' attributes and include the script with the ''data-cf-auto'' attribute — the library scans the page and inserts the cover images automatically:
+<code html>
+<span data-cf-isbn="9780578033440" data-cf-size="M"></span>
+<script src="https://content.chilifresh.com/js/chilifresh-covers.js" data-cf-auto></script>
+</code>
+Supported element attributes:
+^ Attribute ^ Description ^
+| ''data-cf-isbn'' | Item's ISBN(s). All identifier attributes accept multiple values, comma-separated |
+| ''data-cf-upc'' | Item's UPC(s) |
+| ''data-cf-oclc'' | Item's OCLC number(s), with the ''%%(OCoLC)%%'' prefix |
+| ''data-cf-lccn'' | Item's LCCN(s) |
+| ''data-cf-issn'' | Item's ISSN(s) |
+| ''data-cf-size'' | //S//, //M// or //L// (default //S//) |
+| ''data-cf-generic'' | Set to ''false'' to disable generic title/author placeholder images |
+| ''data-cf-alt'' | Alt text for the inserted image |
+| ''data-cf-class'' | CSS class(es) added to the inserted image |
+| ''data-cf-fallback'' | URL of your own image to display when no cover exists |
+| ''data-cf-hide-on-miss'' | Set to ''false'' to keep the element visible when no cover exists (default: element is hidden) |
+| ''data-cf-detect'' | Miss detection mode: ''error'' (default, uses HTTP 404 via ''showerror=true''), ''pixel'' (detects the blank 1x1 px image; no 404s in the browser console) or ''none'' |
+Several identifier attributes can be combined on one element — one request is made and the first existing cover is returned:
+<code html>
+<span data-cf-isbn="9780578033440,0807282588"
+      data-cf-oclc="(OCoLC)4048055"
+      data-cf-size="M"></span>
+</code>
+==== Programmatic usage ====
+The library exposes a global ''ChiliFreshCovers'' object (also usable as a CommonJS module):
+^ Function ^ Description ^
+| ''ChiliFreshCovers.url(opts)'' | Returns a cover image URL built from the given options. Identifier options (''isbn'', ''upc'', ''oclc'', ''lccn'', ''issn'') accept a string or an array (sent as a comma-separated list); plus ''size'', ''generic'', ''showerror'' |
+| ''ChiliFreshCovers.load(target, opts)'' | Inserts a cover into ''target'' (element or CSS selector; an ''<img>'' element gets its ''src'' set, any other element gets an ''<img>'' appended). Returns a Promise resolving to ''{found, img, url}''. Extra options: ''alt'', ''className'', ''detect'', ''fallbackSrc'', ''hideOnMiss'', ''onMiss'' |
+| ''ChiliFreshCovers.auto(root)'' | Scans ''root'' (default: whole document) for ''data-cf-*'' elements and loads all covers. Useful after rendering search results via AJAX. Returns a Promise |
+Examples:
+<code javascript>
+// Build a URL only
+var url = ChiliFreshCovers.url({ isbn: '9780578033440', size: 'L' });
+// Load a cover, with your own placeholder on miss
+ChiliFreshCovers.load('#cover', {
+  isbn: ['9780578033440', '0807282588'],   // arrays become comma-separated lists
+  oclc: '(OCoLC)4048055',
+  size: 'M',
+  generic: false,
+  fallbackSrc: '/img/no-cover.png'
+}).then(function (result) {
+  console.log('cover found:', result.found);
+});
+// Re-scan the page after AJAX-rendered results
+ChiliFreshCovers.auto(document.getElementById('search-results'));
+</code>
+After each element is processed, the library sets ''data-cf-status="found"'' or ''data-cf-status="miss"'' on it, so miss states can also be styled purely with CSS.
 ===== Covers (RESTful) API =====
@@ Line 143: / Line 219: @@
 Questions about integration, custom placeholder images or white-listing: [[support@chilifresh.com]].

ChiliFresh.com

User Tools

Site Tools

Differences

Page Tools