[LibX] Invitation to use the new edition builder

[LibX Project]

We would like to invite everybody interested to use the new edition
builder interface at http://libx.org/editionbuilder to maintain their
editions or build new ones. In this email, we are discussing some
aspects of how to use the edition builder.

Edition maintainers should take the following steps to start
maintaining their editions:

1. Go to libx.org/editionbuilder
2. Register for an account. Provide an email address and choose a password. [1]
3. Select your edition in the All Editions tab and request ownership.
4. Wait until you get an email that ownership was granted.
5. Log off and on again.

The edition builder interface is written using ZK, which is a
framework to build AJAX applications. This means that most of the
graphical user interface is handled on the client side, giving it more
the feel of a local application than that of a traditional web
application. It makes heavy use of JavaScript, so it takes a few
seconds to load, be patient.

First, a word of warning:
For technical reasons we may or may not be able to address, you cannot
use the back button, forward button, or reload button while using the
edition builder. You also cannot do anything that will cause a reload,
such as clicking "unblock popups for this site" if you're using a
popup blocker such as Google or Yahoo toolbar. Fortunately, there
should be no need for you to use these buttons. [2]

In general, we designed the interface to encourage users to "just try
it and see what happens", so don't be afraid to do just that. One
exception: if you have an existing user base, be careful with the
"Make Live" button. Making a revision live will announce this as an
update to your users.

Our hope is that most of the options will be self-explanatory to
somebody who has built a LibX edition before (which most of the
recipient of this email have.) There are small icons with a ? on them
throughout the interface. Hover over them for help.

There is a little bit of new terminology I'd like to briefly discuss.
So far, for each edition, we had two versions: the "live" one and the
"test" one. We have now introduced the concept of revisions instead.
Each edition has revisions that represent versions of that edition.
Revisions are counted 1, 2, 3, and so on. If you have a "live
edition", this will be revision #1 and your "test edition" will be
revision #2.  If you only have a test edition, this will now be
revision #1. Going forward, you create new revisions by making copies
of older revisions (then changing those copies.)

To make changes to your configuration, you must select the latest
revision of your edition. Only the latest revision can be changed.
Once changes are made, save those changes by rebuilding the revision's
.xpi file. This is known as building a revision. You can install and
test the revision as before. If you find that you're satisfied with
all settings, you can make the revision "live". This will announce an
update to your users; it will also freeze the configuration of the
(now tested) revision.

After you have made a revision live, you may have to make further
changes in preparation for the next revision. To do that, you must
create a copy of a revision (typically a copy of the revision you've
just made live.) This revision then becomes the latest revision which
can be changed.

Note that not every small change you make will create a new revision
(nor is it necessary for you to create a new revision when you make a
small change - unless you want your users to see that change.) You can
change as many things as you want in your latest ("test") revision
before you decide it's ready to become live and to be pushed to your
users.

All revisions you create are archived. To restore an old version, you
must select that revision, and copy it forward to make it the latest
revision, then make that one live. (This is similar to how your bank
corrects for wrong bookings: instead of removing the wrong transaction
from the ledger book, a compensatory transaction is entered that
recreates the correct balance.)

Everybody can create one or more editions. All editions that are
public are open to anybody (all editions we've built so far are
public). This means that anybody can clone existing editions and adapt
them for their needs. Such clones are essentially branches - after the
initial copy, they can be developed entirely independently from the
edition from which they were cloned.

Public editions are listed in the "All Editions" list. If you're
creating a new edition from scratch or by cloning an existing edition,
the edition will be initially not public. We encourage you to make it
public after you've tested it successfully, but not before.

Editions now have a checkbox "Endorsed." For statistical purposes, in
particular reporting to grant agency for funding purposes, we'd like
to know how many LibX editions are maintained by librarians for their
institutions vs. how many are created by users with no affiliation (or
by librarians without the endorsement of their library.) Please check
this box if you're acting on your library's behalf.

Editions can be owned (maintained) by one or more registered users.
This allows maintenance responsibilities to be shared. One word of
warning: editions are not locked while one user makes changes to their
configuration. If two maintainers happen to make changes at the same
time, inconsistencies may result. More specifically, the result will
be the result of whoever made the last change; other changes are
discarded. If you decide to share responsibility in this way, please
consult with each other.

For new edition builders, we have integrated a number of features that
should make it easier to build an edition from scratch. First, we
contact OCLC's OpenURL registry for your IP address; if we find an
OpenURL resolver there, we offer to include it. This feature will
obviously only work on campus; however, you can also type the name or
IP address of a machine you want to query for instead.

Second, all created catalogs are shared in a database. You can search
the database by entering the hostname of the catalog. For instance, if
you'd like to include WorldCat, which several of you already have,
simply search for worldcat.org.

Third, the edition builder can try to probe a particular site and
attempt to guess the catalog that's hosted there. This feature can
detect the catalog type in some cases and some parameters for this
catalog. (Note, however, that these parameters may not yield a working
catalog configuration by itself - some adjustment may be required, as
you recall from your efforts getting your LibX edition to work.) We're
continually improving the catalog auto-detection; in particular, we'd
like to eventually offer the option to include any searchable catalog
as a bookmarklet automatically.

The edition builder interface will be the only way to get the IE
version of LibX, which we hope to release soon. When it is released, a
simple rebuild will show a download link for the version. The edition
builder itself should already work with IE6 and IE7, although some
icons may not show properly.

Finally, we have improved the test edition and the live edition
("boilerplate") page we offer to libraries who don't host their own
LibX homepage. A sample of the new test edition page is here:
http://libx.org/editions/libxtestedition.php?edition=vt.3
(This is for the 'vt' edition, revision #3.) Most importantly, you can
now test the desired catalog settings directly on that page, without
having to build and reinstall the entire plugin.)

The new boilerplate page is shown here:
http://libx.org/editions/download.php?edition=exu
Note that we removed the Virginia Tech branding and instead place your
logo wherever edition-specific information is displayed. When you make
an edition live, its homepage will initially be this boiler plate
page. Of course, existing homepages you have created are
grand-fathered in.

Finally, last but not least, do not hesitate to ask questions and give
us feedback. For help with the edition builder, email
libx.editions at gmail.com. For general feedback and comments, email
libx.org at gmail.com.

 - The LibX Team

[1] The password doesn't have to be strong; we recommend using a
password you're not using anywhere else. There is a facility to send a
password reminder if needed. Be aware that we transmit the password in
the clear via email if you request a password reminder.

[2] If you end up reloading the page for whatever reason, you will
have to start over. However, if you are logged on as a registered
user, all of your work will have been saved in this event.