PHP API

The dmBridge PHP API is a high-level, object-oriented API for CONTENTdm® that goes far beyond the CONTENTdm® PHP API. It expedites development by making CONTENTdm® objects easy to work with:

<?php
$col
= new dmCollection('/uw');
$obj = new dmObject($col, 5);

echo
$obj->getMetadata('title');
echo
$obj->getThumbnailURL();

if (
$obj->isCompound()) {
   echo
"Page 1 is titled: " . $obj->getChild(0)->getTitle();
   echo
"It's in this collection: "
     
. $obj->getChild(0)->getCollection()->getName();
}
?>

The API is fully documented and quite stable. The documentation is not hosted here; it is included with the templating engine module in your dm/objects/doc folder.

The PHP API is provided by the template engine and is available automatically within the page templates. (The Draw class and its subclasses are actually part of it, although they only work inside the templates.) It can also be included by other PHP scripts on the same server with code like the following:

<?php
include_once('/path/to/dm/objects/api.php');
?>

If you have been poking around, you may have noticed that similar classes exist in the dmapi and dmctrl folders. These are not part of the PHP API and should not be used.

How to read the API documentation

In the left frame, expand the "Data Structures" menu. Click on dmCollection. This is one of the many classes that the dmBridge API provides. Near the top, there are two sections: "public member functions" and "static public member functions." (A deep explanation of what these mean will not be provided here; please flip to the "object orientation" chapter of your favorite PHP book.)

dmBridge is all about giving objects intelligent behavior. If you want to know a collection's name, you ask it, by calling its getName() method:

<?php
// Create a dmCollection object
$col = dmCollection::instantiate('/uw');

// Get its name
echo $col->getName();
?>

What if you want a list of all collections to which you currently have access? You wouldn't ask a single collection, because it doesn't know; it only knows about itself. But the dmCollection class itself knows:

<?php
print_r
(dmCollection::getAuthorized());
?>

It returns the list as an array of dmCollection objects. You can loop through that array, ask each collection its name, ask it how many objects it contains, ask it what metadata fields it uses, ask each of those fields whether they are full-text-enabled, and so on.

In terms of trying to accomplish your goals with the dmBridge PHP API, think in terms of what CONTENTdm® entities are involved in the task. Objects? Collections, Metadata fields? Comments? Each one of these has its own class in the API, with lots of methods already written for interfacing with them. And like any other class, they can be extended by your own classes.

The API documentation provides a list of all methods that are publicly available in all classes. Most you will never have any reason to work with. But classes like dmObject,
dmCollection, dmComment, etc. may offer some interesting functionality if you need it.

The class you will probably work with the most in the templates is Draw and its subclasses. For a list of methods available in these classes, consult the API documentation. Also, check out the sample templates for working examples of these methods in action.

Using the PHP API in the templates

Digital collections websites perform a lot of common tasks: they display objects, render a paginated results list, etc. The Draw class exists to make a lot of this common functionality as close to automatic as possible, to spare you from having to get involved with the inner workings of dmBridge yourself. For example, by leveraging ResultsDraw::pageLinks(), you can do what would ordinarily take 100 lines of code with just one line. And if we ever update the way pageLinks() works, all of your templates that call it will use the upgraded functionality automatically. (We will try, of course, not to make major changes to the output HTML structure that might break your CSS rules.)

As the class diagram in the PHP API documentation depicts, Draw has several subclasses, each one of which is meant to correspond to a particular view. The child classes are essentially all supersets of Draw; they share all of its functionality, and add more of their own.

All superclass methods can be accessed via any subclass; so, for example, Draw::loginLink() and ResultsDraw::loginLink() are both valid because ResultsDraw is a superset of Draw (where loginLink() lives). But Draw::results() is invalid because Draw knows nothing about ResultsDraw, where results() lives. The idea is that superclasses should contain any functionality that would be used by more than one subclass. So, outside of the templates, where there is no conceptual "view" per se, Draw would be used exclusively, whereas object view could utilize both Draw and ObjectDraw, results view could utilize both Draw and ResultsDraw, etc.

Each view is associated with certain entities. For example, object view is handled by ObjectController::view(). When that method runs, it stores some important information (like the object being viewed) in a temporary location accessible by the templates: in this case, the dmObject class' getCurrent() method. To retrieve the current object from within object view, you would do:

$obj = dmObject::getCurrent();

The naming of these methods should be fairly straightforward. getCurrent() gets the current object in object view; getAllCurrent() returns all current objects in results view; etc. There is no centralized list of these methods, but most of them have the word "current" in them and are associated with the class representing what they are - for example, objects by dmObject, favorites by dmFavorite, queries by dmQuery, etc. Consult the API documentation for a full list of classes and their available methods.