Creating and Maintaining Templates using the Resource API

The Resource API is a set of PHP classes that have been created specifically to help OSF for Drupal templetes designers to create, maintain and read templates files. The API is mean to be a simple set of classes and functions that can easily be used to display  related information into a Drupal templated page.

Introduction to the Resource API
The Resource API is a set of five classes but only three are used for templating purposes: The design of the API focus on these three classes. A  is an Entity description. It is composed of: Then a  is composed of: Then a  is composed of: It is as simple as this: a  is described using multiple   and each of these properties can have one or multiple.
 * Resource
 * Property
 * Value
 * A unique identifier
 * One or multiple types
 * One or multiple Properties
 * A unique identifier
 * A type, which is one of:
 * Datatype Property, or
 * Object Property
 * One or multiple Values
 * A content (the actual value)
 * An optional language identifer (ISO 639)
 * An optional datatype
 * Optional reification statements (out of the scope of this documentation).

What the Resource API does, is just to expose utility functions to help Drupal template designers to use that entity information in the context of a Drupal template.

Overview of the Resource API
In this section, we will cover the main API functions that are available via this API. Note that this document only focus on the classes and functions that are relevant to Drupal template designers. Other classes and functions exists, but they are not relevant for the job at hands.

Usage Recipes
This section outline a series of  "usage recipes". These are code snippets that covers the most common usage of the API for templating purposes.

Working with URIs
Before starting the list the recipes, we have to cover one of the core concept: URI. URI are unique identifiers that are used to identify,   and. A URI is normally a standard URL, but it can be different. A full URI looks like this:

This unique identifier is not different than any other unique identifiers like a unique number, a hash value, etc. In the recipes below, we will be referring to prefixed URI. A prefixed URI is a URI that his shortened using a prefix. Let's say that we have a prefix called  that stands for the partial URI. This means that the prefixed URI version of the full URI we defined above would be:

Prefixed URIs makes shorter and more human readable URIs. This is perfect in the context of writing templates code since it will make the templates easier to read and maintain and create.

Note that you will be able use the  function when you will be creating new templates to list all the prefixed properties URI that are available for the entity you are templating.

Getting a Property
Getting a reference of one of the property that describes a  is pretty easier, the only thing you have to do is to specify the full or the prefixed URI to get using the   function:

Then  can be used anywhere in your code to display the value(s) of that preferred label.

Getting the First Value of a Property
To get the first value of a property, you have to use the  function of a  :

If you don't specify any for the   function, then the first value will be returned. As you can see in this example, you can chain the function calls to get a property, and then its value. You could have done this too:

Getting the Content of the First Value of a Property
To get the content of the first value of a property, you have to use the  function of a  :

What this does is to return the actual value of the  instance.

Displaying the Content of the First Value of a Property
To display the content of the first value of a property, you have to use the  function of a  :

What this code does is to directly display the value within the H2 HTML code element. If you want to make you code even simpler and cleaner, you could have done this:

Check if a Property Exists in a Resource
Often, you only want to display parts of your template depending if there exists values for some properties of the Resource you are templating. For example, if you have a Resource that may have some latitude/longitude coordinates, than you only want to display a Google Map if there are actual lat/long coordinates for the Resource you are displaying to the users. To make that check, you have to use the exists function of a Property:

Getting Information About Types and Properties
Sometime it may be useful to get information about the type and properties that are used to describe a  you are manipulating. A type or a property are  as well. What this means is that you can use the  to get additional information about these things that you may want to display into the templated page.

Let's take the usecase where you want to display the preferred label for the type of a  that you are templating, in parenthesis in the title of that  's page.

What you have to do is to use the  function to get the description of that type and to display information about that type. Here is how you can do that:

What this code does is really simple: it get additional information from OSF about the type of the entity being processed in the templated page, and use that information to display the preferred label of that type into the templated page.