OCHRE Wiki - Publishing Items

Publishing Items

By Miller Prosser, May 2020; updated March 2021

Considerations BEFORE publishing!

Keep in mind that when you publish an item, a Set, or a Hierarchy, the published data is saved as a static file on the OCHRE publication server. With this in mind, it is a good idea to consider the following options before publishing.

Choose a Creative Commons license

The OCHRE platform and the OCHRE Data Service makes no claim to your data. The decision to publish is entirely in the hands of the project director(s). Likewise, the sharing license is entirely in the hands of the project. Data published from OCHRE can include a Creative Commons license that defines your intentions for how your data may be used by others. Choose your license and configure your project to reflect your choice. Then, when you publish an item, the published view will include a link to the CC license that can be displayed on a website or in an app. For project administrators, go to the Project-level Preferences > Copyright tab and choose your Creative Commons license.

Set Your Website Address

If you wish the published data to include a reference to your homepage, set this before publishing your data. For project administrators, go to the Project-level Preferences > Settings tab and add your homepage URL to the Website field.

Some projects maintain their own website in addition to a data-driven website hosted by the OCHRE Data Service. When you configure your default homepage URL in OCHRE, choose the site you want to appear in the published data from OCHRE. If you choose to list your non-OCHRE website, you risk directing the user away from your data.

If you need to publish a stable project/site URL in a printed book or article, consider publishing the persistent identifier for your entire project, which will then redirect to the website configured in the website field in OCHRE. This approach allows you to change your website URL without leaving the printed reference to your site broken. Contact the OCHRE Data Service with help configuring your project's persistent URL.

To Expose Image URLs or Not

You have the option to include the file URL of images in the published items. Why is this an important decision? If your images are on a secured server, or on a server that you wish to keep hidden from most frontend users, you may wish to keep the server path obscured by not including it in the XML document that is passed to the frontend. However, if your images are on a web server that intended to be entirely open to the world, it may make sense to expose this address to the frontend. For project administrators, go to the Resources > (Hierarchy) > Preferences and choose Allow publication of IRI if you wish to include the server address in the published XML. This defaults to off (IRI is not exposed).

Name format of items

The publication process will respect the Name format as established by the source hierarchies or sets that contain the items being published. Be sure to consider whether you want to adjust the Name format to use Abbreviations, include Aliases, etc. before publishing.

Non-standard file types

OCHRE supports the publication of a wide variety of standard file formats, such as jpg and pdf. File types that are not native to online viewing (such as zip files) can be published via OCHRE. However, these must be configured properly in OCHRE. First, each file URI must contain the file extension of the file in question. (In other words, the file extension cannot be omitted as is sometimes done for hierarchies of images.) Second, the resource hierarchy must also be configured to specify the file type. Therefore, a resource hierarchy cannot contain mixed media. When published, a file like a zip file will be passed to the client browser to be handled by the user's default settings. In most cases, these types of files will simply be downloaded by the user.

How to publish an OCHRE item?

Right-click the item in the left navigation pane, and choose Publish item from the menu.
On a Set or Hierarchy, navigate to the Utilities tab and use one of the Publish buttons.

(Note that this requires User access to these features.)

Publishing a Set

These are the options for publishing a Set from the Utilities tab of the Set:

Publish — this option publishes the Set as a simple list of the Set items, but does not publish the full details of each set item. For each item, only the item name and UUID attribute are included. App developers can use this information to create click-through links for these items. This option will not produce a detailed table from the default XSL stylesheet. In other words, use this option if you plan on writing a script to process the results or want to produce a simple, flat list of items via the default XSL stylesheet.
Publish, From spec — this option allows the user to specify which variables to publish for each item in the Set. However, if you need to publish all the details of every item in the Set, you can choose the "Include all properties" option on the Table Columns/Tags tab. The default online view produced by this option is an HTML table including the properties configured in the specification, as well as the item Name, Description, Context, and Period(s) of each item.
1. - Note that if you want click-through potential on each item in the table, the items need to be published too; use the Publish all items in this set listed below.
  - See the example below from the Leon Levy Expedition to Ashkelon.
Publish, Compact — this option publishes a compact version of the set appropriate for use in R. Contact the OCHRE Data Service for help using this option.
Publish all items in this set — this option does not publish the Set itself, but all the items in the Set.
Publish, Contexts — this option publishes all of the ancestor items of all of the items in the Set. This is intended to help ensure that if "breadcrumb trails" are provided on web pages for published items, the items in the breadcrumb trails will also have been published.
Unpublish — this option unpublishes the Set.
Unpublish all items in this set — this option unpublishes the items in the Set.

SAMPLE: a list of Figurines from Ashkelon published from spec:

https://pi.lib.uchicago.edu/1001/org/ochre/dde334f7-bcb2-4666-bd54-6650a5dcfbe4

On the Format Specification tab, Export/publish options you can choose to "Create download button..." if you want the styled HTML output to include a button that allows the user to download a CSV file of the table.

Note: Be careful when designing your published Set to consider the resulting size of the Set and how it will be used in the published presentation. From our experience we have successfully published Sets in OCHRE of up to 20,000 items, and displayed these in the default table format created by our default stylesheet. However, a Set this large may be slow to populate a front-end display.

Reverse Links

When publishing a set from spec, tick the Reverse links box on the Format Specification tab to include a node of reverse links in the published XML. Included in this reverse links node are any relationships established by links on an item's Links tab (e.g. images linked to objects) or relational variable links on the property tab (e.g. associated texts as properties of objects).

</reverseLinks>

Publishing a Hierarchy

Like publishing a set, you can publish a Hierarchy of items. Each hierarchy (a.k.a. tree) has a uuid which can be called using the API. When publishing a hierarchy, you can use the basic Publish option to create a list of items with uuids and names. (There is no Publish, From spec or Publish, Compact option on a hierarchy.) Each item will contain its own nested list of its own child items. The web app developer can use this hierarchical structure to create indexes with click-through to sub-pages, for example, on a web presentation.

As with a Set, you will want to make sure to Publish all items in this hierarchy as well (although see just below for publishing a partial hierarchy).

The parent-child structure of a hierarchy has implications for its publication.

To make context available to web app developers, OCHRE includes basic details of one-level of sub-items with each item's published format. This provides easy access to the immediate child items of a parent item to allow drill-down/click-through links.
In addition, each item contains within its published format the full path-contexts for each hierarchy it which it is contained. This makes it easy for web app developers to leave a bread-crumb-style trail as the user drills down on hierarchically organized content.

Publishing a Partial Hierarchy

For recursive hierarchies, like those in Locations & Objects, where an item can contain other items directly (not within headings), OCHRE lets you Publish or Unpublish a selected branch of the hierarchy. The Preferences tab of such an item has the same options for publishing and unpublishing the items in the hierarchy, but it will include only the items constrained within the current context (branch). Note that an item that is Private can not Publish its sub-items, although it can Unpublish them.

SAMPLE: a hierarchy (with headings) of published resources

https://pi.lib.uchicago.edu/1001/org/ochre/2a120198-7715-49c9-8e80-ff0070342bf2

Publication details

Who can publish items?

Only Project Administrators, or Users who have Insert/Delete access or higher and who have been authorized by checking the option on the User Privileges pane to "Allow this user to save-as-XML or publish an item."

Who can see the published items?

Once published, an item is accessible by an API provided by the OCHRE Data Service. Theoretically, this information becomes available to the world. However, published items are not (yet) indexed by web crawlers and indexers. Essentially, the published item(s) need to be made available as a web page, a link on a page, or a download link. In short, you need to give you audience a way to see the data.

How do I publish corrections?

Make any corrections or additions to your project data as you do normally. By using one of the Publish options outline above, you push these changes to the web, updating the previous version of the published item(s).

What if I want to unpublish an item?

Use one of the Unpublish options above to make the item unavailable to the web.

What if I delete a published item from OCHRE?

OCHRE will prevent the deletion of an item that has been published. That is, the published version of an item is considered a dependency of the item in OCHRE. You must first unpublish the item using one of the options above before it can be deleted.

What about items that are Private?

Items that are marked as Private (on their Preferences pane) cannot be published. Conversely, a published item cannot be made private without first unpublishing it.

If private items are included in a Set to be published, the item will be omitted from the published Set.
If private items are included in a Hierarchy to be published, the private item and all of its sub-items will be omitted from the published Hierarchy.
- If a sub-item's privacy setting is changed, and if its parent item is already published, then that parent item (which includes details of the first-level child items in its published format) will quietly and automatically be republished by OCHRE (either to make the child visible if formerly private, or omitted if formerly public).
For both Sets and Hierarchies, the option to Publish all items in this hierarchy/set will account for items that are private as it reports on publication progress and success, but it will skip items marked as Private, leaving them unpublished.
If a target of a relational (link) Property is private, that property will be omitted from the published version of the item.
If any of the linked items of an Event are private (Agent, Location, Period, Other), those details will be suppressed although the remaining non-private components of the Event will be published.
If any of the Paths (Contexts) of an item are marked as private, that context will be omitted from the published version of the item. E.g. a project may want to keep Inventory paths private.
The Publish, Contexts option will respect the privacy of an ancestor item; if it is private it will be skipped (not published).

What does a published item look like online?

A project can create a customized XSLT transformation and a custom CSS file to transform the published XML into HTML.

See W3C Schools XSLT Tutorial for more information.

The ODS has created a fallback XSLT to transform any data published from OCHRE. The published data is likely to vary greatly from project to project. See Sample XSLT Transformations on the ODS website for examples of published items, hierarchies, and sets.

Please feel free to suggest improvements to our fallback XSLT transformation by contacting us as ochre@ochre.uchicago.edu.

Identity Guidelines

See OCHRE Identity Guidelines for details on how to refer to OCHRE on website, in presentatations, and in print publications.

Google Sites

Report abuse