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.

There is a configuration user interface in OSF for Drupal that you can use to see, and manage, all the namespaces that are available to you. See the Managing Namespaces page for more information.

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  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  you are displaying to the users. To make that check, you have to use the  function of a  :

Get all the Values of a Property
Sometimes it is essential to be able to iterate all the Values of a Property. It can easily be done using the values function of a Property:

Get all French Values of a Property
In a multilingual Drupal instance, you may have to deal with multilingual Resources. These are resources that may use multiple languages to describe the same. This can easily be done with this API. The only thing you have to do is to specify that you want to access French information from the  by using the   function call on the. Then when you will use any other functions to get the values from that, everything will be in French:

Remember that by default, the  mode is activated. That means that the code below will display all the French labels, and the labels that doesn't have any language defined for them. If you want to strictly use the French labels, then you could change that code this way to enable the  mode:

Working with Object Properties
As we discussed above, a  can be a   or a. Datatype properties are properties for which their value is textual. The Object properties' value are always URIs. These URIs refer to other entities that should exists in the system.

In this example, we will consider that we have an object property  that refer a person entity to another person entity:

In this example, we use the  OSF for Drupal function call to get the description of the entity that is referenced from our. That other  that is returned by this function call can be used like any other   that we are manipulating using the.

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.

Drupal Specific Functions
There are two OSF for Drupal functions that exists that are related to the :

What the  call does is to return a Resource instance for the URI you specified as parameter. This function is normally used to get the Resource that describes an entity reference by the Resource being templated. That means that you can template information from related entities to the entity being templated. Like in this code:

The first thing a template designer has to do when he starts templating a new  is to check what are the properties/values available to him. What the  function does is to output the structure of the   being templated such that you the information you can template, and more importantly, the prefixed URI of the properties you can use in your code. If you use that code, anywhere in the template's code:

You will get that output in your browser the next time you will refresh your page (note: it may takes two refreshes depending on the code sequence in Drupal and if it is a search template an a view template):

As you can see, this debugging output will show you all the properties that are defining that. Then for each of these properties, you can see their prefixed URI. These same prefixed URI can be used in your template code like what we were doing in the recipes above. You can click to extends all these sections and see the values for each of these properties.