Edition Builder FAQ

On this page, we're listing some issues users encounter when using the edition builder. It will eventually develop into a fully-blown FAQ.
  1. Q. How do I get started?
  2. Q. I can't find the build revision button!
  3. Q. What's the difference between an edition and a revision?
  4. Q. What is the difference between the testing and the live revision?
  5. Q. My catalogs don't work.
  6. Q. My catalogs work on the test page, but xISBN doesn't work.
  7. Q. I'm confused by xISBN, nothing I try seems to work.
  8. Q. Can you detect what OpenURL resolver I use?
  9. Q. Can I reuse catalogs or databases from other editions?
  10. Q. My catalog or database is not listed. Can I still make it work?
  11. Q. How do I express more complex URL templates?
  12. Q. How do I import my institution's icon into my LibX edition?
  13. Q. How do I add the edition I created to the list of public editions?
  14. Q. How do I delete an edition?
  15. Q. How do I configure my "SFX Journal List" resource as a catalog?
  16. Q. I'm trying to import my OCLC profile, but nothing happens.
  17. Q. I'm trying to import my OCLC profile, but it says "No catalog found."
  18. Q. Why is my OpenURL resolver detected multiple times?
  19. Q. How can I change the order of the search fields in the drop-down list in the extension?
  20. Q. I'm getting an error when trying to build a revision.
  21. Q. Can I change my edition id?
  1. Q. How do I get started?

    A. You can start a new edition in two ways: either from scratch, or by cloning someone else's. Suppose you start from scratch. After you click the "Build A New Edition" button, a number of other tabs will appear. First, you're asked to enter a brief description. Do that. (In the edition builder, what you enter is saved automatically if you "tab away" from the current field, or if you use the mouse to click on something else. There are no "Save" or "Submit" buttons to press.)

    For the most basic LibX edition, you must configure at least one catalog. Go to the "Catalogs & Databases" tab to that end. On that tab, you see on the left three boxes, labeled "Auto Detection," "Manual Configuration," and "WorldCat Registry".

    If your library is a member of OCLC, try "WorldCat Registry" first. Type in the name of your library. If you see your library in the hits, try importing its profile. We'll then try to find information about your library's catalog from OCLC. (If you are on a campus of an OCLC institution whose OpenURL resolver is registered with OCLC --- such as most academic institutions in the U.S. --- we may have already performed this probing for you.) If our auto-detection probe succeeds, you should see a message "Found ... catalog" along with a button . Try adding it. You can test your revision (without installing it) anytime by clicking on the link in the status line where it says: edition xxxxxxx rev 1 successfully saved.

    Otherwise, if you know the URL of your OPAC, you can type it in the "Auto Detection" box. If we don't detect it, you may have to manually configure it.

    Once you have at least 1 catalog configured, select the "My Editions" tab and build this revision. To be able to return to the edition builder and maintain your edition(s), you should also register for an account in the "My Edition" tab. Registering for an account will also allow you to request help from the LibX team. If you register while working on a new edition, this edition is automatically added to your editions. Conversely, if you register first and then start a new edition, it'll also be yours. (You can play with the edition builder without registering - but everything you do will be lost once you leave the current windows.)

    After you've registered and built the revision, install it and give it a spin.

    Finally, if you are unsure, look for these help icons and hover over or next to them for explanation.

  2. Q. I can't find the build revision button!

    A. Go to the My Editions tab, select an edition. In the right half of the screen, a button will appear.

  3. Q. What's the difference between an edition and a revision?

    A. Put briefly, an edition is a version of LibX for a library or user community (or even individual user.) An edition has an id. Editions created before July 2007 have an id that usually consists of the prefix to a .edu domain, such as 'vt' or 'mit'. Editions created after July 2007 have an id that's an 8-digit hex number, such as 3B43B44D. The id is only used internally. You cannot change an edition's id once it is created.

    Each edition can have multiple revisions, which are numbered 1, 2, 3, and so on.

    For details, read this post.

  4. Q. What is the difference between the testing and the live revision?

    A. An edition can have 0 or 1 test revisions, 0 or 1 live revisions, and 0 or more archived revisions. Think of test and live revisions as staging and production areas, respectively, with which you may be familiar from your ILS. You can make as many changes to your test revision as you like until you're satisfied (you can rebuilt and install test revisions as often as you wish). Once satisfied, you move the staging area to the production area by making the revision live. Moving it to the production area also freezes it - the downloadable file is built and we will not change it anymore. Your users download and install *exactly* what you tested.

    When you're ready to make further changes, or if you want to pick up a new version of the software, you create a new staging area by copying the live revision forward. In addition, the Edition Builder archives old revisions. You can inspect those by opening them (but only in read-only mode), and you can restore an old revision by copying it forward into the staging area.

    Note that when you open the live revision or an archived revision, the button will read: "Open (Read-Only)". Open will succeed, and you can browse through the settings, but none of the changes you make will be saved. You'll see a warning at the bottom if you try to make changes. [ In the future, we should probably actually disable the controls for better usability. ]

  5. Q. My catalogs don't work.

    A. The most common mistake is that users either copied the URL of their catalog search form into the Catalog URL entry, such as http://mylibrary.edu/mysearchform.html, or that they added a partial search path such as http://mylibrary.edu/search?, or that they forgot the leading http://. LibX requires only the base URL for most of the catalog types it supports, with the http:// prefix, but without a trailing slash. However, some catalog types are exceptions.

    You can see examples of the correct syntax by hovering over the help icon for the Catalog URL entry:

    Here is the information shown there:

  6. Q. My catalogs work on the test page, but xISBN doesn't work.

    A. Check that you didn't forget the http:// prefix for the catalog URL.

  7. Q. I'm confused by xISBN, nothing I try seems to work.

    A. Read the help text for each of the xISBN options carefully.

    In particular, note that some options will not work unless OCLC knows about your catalog.

  8. Q. Can you detect what OpenURL resolver I use?

    A. The edition builder includes an auto detection facility that runs your IP address against OCLC's OpenURL resolver registry. If you're listed there, LibX may offer you the option to import the resolver. If you're connecting to the edition builder from a location that is not recognized (such as from off-campus), you can tell the edition builder the IP address or hostname of a location that's on campus. For many universities, the address www.youruniversity.edu will work since the web server is often located on campus.

  9. Q. Can I reuse catalogs or databases from other editions?

    A. Yes! LibX keeps a database with all configuration settings from all public editions. The catalogs and databases you have set up in your live revision will be automatically added to this database, provided you make your edition public. (And provided, of course, you've made your edition live so it has a live revision.)

    To find the catalogs others have configured, type the hostname into the search field in the catalogs tab. Omit the http:// prefix, and don't enter any path. For instance, to see if anybody has set up Encyclopedia Britannica, type eb.com in that field.

    Follow-Up: How do I add Worldcat to my LibX edition?

    WorldCat is now supported as a specific catalog type. Type "worldcat.org" in the auto-detection box. Before WorldCat was supported as a specific catalog type, it was supported as a Bookmarklet via a URL template. Many libraries had included worldcat.org as a bookmarklet in their editions; you'll see those as well when you auto-detect.

  10. Q. My catalog or database is not listed. Can I still make it work?

    A. Most likely, yes. There are two ways in which new catalogs or databases can be configured. These are referred to as bookmarklets and custom catalogs. Here are the differences:

      Bookmarklet Custom Catalog
    Require external hosting? (That is, you need to upload the javascript file to a server - any public webserver, such as googlepages.com, will do.) No Yes
    Support for http GET/POST GET and POST GET and POST
    JavaScript programming required? (from you, that is) No, a URL template in which the search terms are filled in is used. Yes, but not much.
    Support for advanced (multiple field) searches? Partial Yes

    Please note: Most of you will use bookmarklets. Custom catalogs require JavaScript programming and external hosting of the JavaScript code.

    For details on how to configure bookmarklets, see the Bookmarklets Help blurb. For details on how to configure custom catalogs, read this email and read this one to see an example of how to use POST in a custom catalog. Note that POST is now supported in both Firefox and IE. An example custom catalog that uses POST is shown here. An example custom catalog that uses GET is shown here.

    Currently, cues do not work for POST-only catalogs.

  11. Q. How do I express more complex URL templates?

    A. The comments here apply to bookmarklets, not custom catalogs. Aside: the word 'bookmarklet' is probably a misnomer on our part. Unlike other bookmarklets, our 'bookmarklets' do not involve bookmarked javascript code. Rather, they are more similar to simple templates.

    In the simplest case, a bookmarklet contains a template with embedded %codes in them. Wherever such a %code is found, it is replaced with the user's search terms when a search is made. Which search term replaces which code depends on the mapping of search types to codes. This mapping is apparent from the columns provided in the "Options" dialog in the Edition Builder. Some mappings are built-in, and you may also add your own. For instance, code Y maps to a Keyword search. Mappings apply to an entire edition, rather than individual catalogs. We may remove this restriction in the future.

    If a search field occurs in a template, but the user doesn't provide input for the field's type - say the template contains %t, but the user does not provide any information in a "Title" field - then the %t is replaced with nothing before conducting the search.

    If the user enters multiple search fields of the same type (say two Keyword fields), the information in them is concatenated with a space before substitution.

    In some cases, this simple replacement scheme is not enough. LibX provides two special syntaxes to help in those cases: %SWITCH and %JOIN. %SWITCH is now deprecated; its effect can be accomplished with %JOIN. For documentation on %SWITCH, read here.

    One or more %JOIN statements can occur as part of a URL template, each using the following syntax:

    %JOIN{connector}{type1|value1}{type2|value2}{....}
    
    For example, this template can be used for OCLC FirstSearch search:
    http://firstsearch.oclc.org/dbname=WorldCat;FSIP;query=%JOIN{%20and%20}{Y|kw%3A%Y}{t|ti%3A%t}{a|au%3A%a}
    
    The %JOIN statement is interpreted as follows: each type listed (here: Y, t, and a) is examined. If the user provided input of that type (Keyword, Title, Author), it is replaced with the corresponding value. For instance, if the user provided an author, it is replaced with au:%a. Note that the %3A is the URL-encoded version of :. Subsequently, the %a is replaced with what the user actually entered in the Author field. All entered fields are concatenated. If there is more than one, the value entered in the connector is used to join them. In the OCLC example, the connector is " and " (note the %20 is needed to encode a space character). The end result is as though the user had typed: "kw: .... and au: .... and ti: ...." in the query field, which is the search syntax required by this resource.

    Connector may be empty. If a field was not entered by the user, the %JOIN statement is replaced with nothing. Consequently, the statement can be used to insert content in a URL depending on whether a particular option was selected. For instance:

    %JOIN{}{a|searchtype=author}
    
    will be replaced with searchtype=author if the user provided an "Author" input field, but will resolve to nothing otherwise.

  12. Q. How do I import my institution's icon into my LibX edition?

    A. Many institutions have an icon that users see when they visit the institution's website. For instance, users visiting Virginia Tech's website at http://www.vt.edu will see this icon .

    If your institution has such an icon, you can import this into your edition by instructing the edition builder to download the icon. You would do this in the "File Management" tab. There are two cases.

    1) The icon is named favicon.ico. To check this, simply append favicon.ico to your institution's website URL. For instance, if your institution's website is http://www.vt.edu, try http://www.vt.edu/favicon.ico If you find the icon there, copy and paste the URL into the edition builder.

    2) The second option is that the icon you see is linked from the page. In this case, use Firefox and right-click on the page, then select "View Page Info." In the dialog that opens, select the "Media" tab. Look for a row in which the "Type" column says "Icon." If it exists, right-click and "Copy" the URL, then paste into the LibX edition builder, then select "Download Image From URL." You can use the second technique to import any image into your LibX edition.

    3) Recently, we added the ability to have per-catalog icons. If a catalog is detected, the LibX edition builder may also detect an icon for this catalog. If so, this icon will be added to your edition's files (in the File Management tab). You can then choose the image by selecting it in Options.

  13. Q. How do I add the edition I created to the list of public editions?

    A. Editions are added automatically to the list of public editions if two conditions are met:

    One request: please do not make your edition public until it has been tested successfully. Doing so will clutter the list of public editions with untested or incomplete configurations. Also, if you (accidentally or intentionally) created multiple public editions (when you meant to create a new revision), choose one and uncheck the public checkbox for the others. See also What's the difference between an edition and a revision?

  14. Q. How do I delete an edition?

    A. To delete an edition, use the "Release Ownership" button in the My Editions tab. Editions with shared ownership will be deleted once the last owner relinquishes ownership. The actual files for the edition may persist for some time after on our server; we will eventually garbage-collect them.

    Note that you can delete only entire editions, not individual revisions of an edition.

  15. Q. How do I configure my "SFX Journal List" resource as a catalog?

    A. There are two ways in the catalogs tab. The option "SFX" uses the OpenURL syntax, which may or may not be what you want. If you use this option, provide the base url only. Otherwise, use a bookmarklet.

    For instance, consider the SFX installation at http://bridge.liblink.umn.edu/.

    Option 1: Choose Type SFX, use Options Journal Title (code jt) and ISBN/ISSN (code i), and use URL: http://bridge.liblink.umn.edu/bridge
    See example result.

    Option 2: Choose Type Bookmarklet, use Options Title (code t), and use URL: http://bridge.liblink.umn.edu/bridge/a-z/cc?param_lang_save=eng&param_letter_group_save=&param_perform_save=searchTitle&param_letter_group_script_save=&param_chinese_checkbox_save=0&param_services2filter_save=getHolding&param_services2filter_save=getFullTxt&param_current_view_save=table&param_jumpToPage_save=1&param_type_save=textSearch&param_textSearchType_save=contains&param_type_value=textSearch&param_jumpToPage_value=&param_pattern_value=%t&param_textSearchType_value=contains&x=0&y=0
    See example result.

    Note: do not append 'a-z' if using the SFX form (Option 1).
    Note 2: the Bookmarklet syntax may need to be updated when you upgrade your version of SFX, as it is specific to the system and - unlike Option 1 - does not follow an established standard.

  16. Q. I'm trying to import my OCLC profile, but nothing happens.
  17. Q. I'm trying to import my OCLC profile, but it says "No catalog found."

    A. The LibX Edition Builder takes the search term you entered and searches the Worldcat Registry for matching profiles. It will sort the profiles by relevance (since OCLC doesn't do any sorting of its own), then it will download each profile. (The result window includes links for the profiles, by OCLC number, for you to double-check what we download from OCLC - make sure you keep your Worldcat Registry entry up-to-date for best results.)

    Currently, we examine the profiles only for the base url of your catalog (if it is provided). If it is not provided in your OCLC profile, it'll say something like (profile 10804 does not contain catalog information). In that case, importing the profile wouldn't do anything, so we remove the "Import this profile" button.

    If a base opac url is provided, we will submit this URL to our auto-detection facility if you click "Import this profile". You will then see "probing ... ". This probe may succeed, or it may fail.

    We are continuously expanding our detection heuristics.

    In all cases, we will search the shared database of resources. If your OCLC registry lists a URL that hosts a catalog we can't auto-detect yet, the detection will fail. You'll then have to do what Buck Rogers did and switch to manual control to add your catalog. Also, some OCLC profiles list an alias URL, those aren't detected properly as well.

    Note that - for reasons known only to OCLC - the OCLC profile does not contain all information that would allow us to perform a successful search against your catalog. In particular, it does not contain the type/vendor of the catalog and it does not contain other parameters that may necessary. That's why even under perfect circumstances, the auto-detection may not immediately give a fully functioning catalog setup, though it usually gives a good starting point for further configuration.

  18. Q. Why is my OpenURL resolver detected multiple times?

    A. That's a bug in OCLC's registry. We reported it as of 2007/12/10. Simply ignore the other detected entries or click "No Thanks."

  19. Q. How can I change the order of the search fields in the drop-down list in the extension?

    A. Use drag-n-drop. [ There's now a hint that says that ]

  20. Q. I'm getting an error when trying to build a revision.

    The error looks like this in the status line:

    3:53:04 PM Oct 3, 2007 edition 3B43B44D rev 1 build failed, exit status= 25
    
    If I click on More..., I see this:
    cp: omitting directory `/home/www/libx.org/editions/3B/43/3B43B44D.1//'
    Cannot copy /home/www/libx.org/editions/3B/43/3B43B44D.1//
    tmp2.13595/chrome/libx/skin/libx/ at
    /home/www/libx.org/libx/src/editions/xcreateextension.pl line 222.
    ...
    
    followed by a whole bunch of other messages.

    A. Make sure you don't have empty entries in your File Management tab. Go to File Management, and if there are any empty entries, delete them.
    This error shouldn't occur anymore.

  21. Q. Can I change my edition id?

    A. No. The edition id is used only internally, it's not important to users. We initially assigned edition ids based on the DNS domain, but the edition builder now uses a scheme whereby ids are assigned random but unique 32-bit hexadecimal numbers.