Hymnal installation

The hymnal installation process consists of importing the data from a hymnal into the Hymnary. Uploading a hymnal from scratch is usually accomplished by entering the data into a spreadsheet, saving the spreadsheet as XML, and uploading the spreadsheet into a hymnal. The data may also be entered directly into Hymnary by adding new text of new tune.

Remember: entering information from a hymnal is creating a hymn instance. An instance should detail exactly what is on the printed page, even if it is incorrect. That is, if the hymn lists "Dr. Watts" as the text author, you should enter "Dr. Watts" even though you know the author's real name is Isaac Watts. (The instance information will be connected to verified information on an authority page after the hymnal has been installed.)



A hymnal may be indexed by entering its information into the following spreadsheets:

Each of these spreadsheets can be made in Excel and must follow the format specified. This includes the presence of a header row which will be ignored when the data is imported into the Hymnary. Follow the spreadsheet links above for required, recommended and optional columns.

There also are spreadsheets for Media and (Page) Images.

Note that if you already have this information in a database, it may be fairly easy to export it into CSV files matching our needs. Ask your database expert.



ThML is the XML dialect used at www.ccel.org. Hymnals encoded in XML can be installed as books at www.ccel.org, and they can also be imported directly into Hymnary.org. This route may be appropriate for XML experts who want hymnals to appear at CCEL.org as well. There is an introduction to Creating Hymnals in ThML; contact us at ccel@calvin.edu for more information.

Web interface

Individual hymns may be added through the web interface via "hymn text instance" and "hymn tune instance" pages under "Editor Tools," but the hymnal must exist before adding any hymn instances. A new hymnal can be added through the web interface on the Hymnal page; see further instructions in the next section.

Be aware, especially when using the web interface, that when a new authority is added, the information in that authority record comes directly from the instance. If there is a mistake in the instance information or if the instance information is incomplete when the new authority is added, the mistake will show up in the authority and the authority information will be incomplete. Please correct the newly created authorities as well as the instances. There may be information in the instance that is appropriate for the instance but not needed or different than what is wanted in the authority. For instance, a full text does not need to be in the authority, as the text that is seen there comes from an instance; and the copyright information in the authority should be the current copyright and people's names should be the authority name.

Hymnal Set Up

To add a new hymnal, go to Editor Tools in the left side bar (if you are an editor, and logged in), then, Add new...Hymnal. Fill out the form.

  • The hymnal ID should consist of the main initials in the hymnal title and the date of the hymnal. For example the hymnal "Worship and Rejoice" published in 2003 should have an id something like "WAR2003"
  • Use the title that is on the title page of the hymnal, include the sub-title, if there is one. Separate the title and sub-title with a colon. Put edition statements behind the title in parentheses.
  • If you can find a cover image, copy the image to a file, then under Editor Tools--Add new--Media, upload the image to Hymnary; right click on the resulting URL and select "copy"; then paste the URL into the Cover Image URL field.
  • Add the denomination if there is one. Use the denomination that the hymnal states it was produced by or for.
  • If the denomination name does not appear in the drop down menu, then add it from the "Add New" menu on the left side bar. Use the name on the hymnal. Use the Library of Congress Name Authority files (http://authorities.loc.gov) or ARDA (http://www.thearda.com/Denoms/Families/trees.asp) to find the Parent name (such as Baptist, Lutheran, etc.)

Uploading spreadsheets

  • Save the spreadsheets as XML spreadsheets
  • After the hymnal has been added, click on "Editor Tools" in the hymnal, and find "Upload xml...spreadsheet"
  • Click on "Editor Tools" in the hymnal to find "Resolve...authorities." Resolve the people authorities first, then the text authorities, then the tune authorities.

Page Scans

  • Make sure the images are in a zipped file.
  • Use the upload page images link under Editor tools for the hymnal
  • Count how many pages are before page 1, and use the menu to select that number. If images are coming from Internet Archive, also count the cover as a page,as the scanner bed is usually the first image.
  • Use the Attach Page Images link on the hymnal page.
  • Copyrighted material may not be displayed, except Hope Publishing allows their copyrighted material to be displayed with a license agreement and GIA allows their copyrighted material to be displayed as long as a high-resolution page scan is disabled.
  • Use Display Permission: Nobody for copyrighted material and Display Permission: Everybody for Public Domain material.
  • Avoid leaving parts of hymns visible, for example, if a copyrighted hymn carries over onto another page, set both page permissions to Nobody; or, if a public domain hymn carries over onto a page with a copyrighted hymn, set both pages permissions to Nobody. People get confused when only part of a hymn is visible.
  • We know that if the first copyright date is before 1926 that the hymn is in the public domain.

See also

External links

It looks like you are using an ad-blocker. Ad revenue helps keep us running. Please consider white-listing Hymnary.org or subscribing to eliminate ads entirely and help support Hymnary.org.