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.