Theming

Introduction
Drupal sit on top of a really powerful theming engine. Nearly anything can be templated and themed before being displayed to the end users. What we will focus on in this page are the things in OSF for Drupal that can be themed. There are two kind of templates that can be created:
 * Templates that will be used to theme specific individual resources' pages based on their type
 * Templates that will be used to theme search results based on their type

Creating Templates
Creating a template for a ResourceType entity is not different than creating a template for any other type of Drupal Entities. The same API, methodologies and concepts can be used.

When you create a template, different pre-populated variables are accessible to the person that will create the theme. The main variables in a non-search template are: The main variables for a search template are:
 * or
 * This is a  class instance. All the values of the properties follows the internal Drupal array structure conventions
 * This is a  class instance that can be used to manipulate the entity's content. The Subject class does have a complete API that is available to the developer to help them manipulating the content of an entity.
 * This is a  class instance that can be used to manipulate the entity's content. The Subject class does have a complete API that is available to the developer to help them manipulating the content of an entity.

Simple Template Using $entity
Here is a simple template that uses the $entity variable to display information about an entity.

Once the template is processed, the output of such a simple template would be:



Simple Template Using $subject
Here is a simple template that uses the $subject variable to display information about an entity.

Subject Class API
In this section, we cover the relevant API functions that can be used on a $subject variable.

$subject->getAltLabels
Get all the alternative labels of this subject.

Returns an array of alternative labels. Returns an empty array is there is none.

$subject->getDataPropertyUri
Get the URI of all the data properties that describes this subject.

Returns an array of all the URI of the datatype properties that describe this subject.

$subject->getDataPropertyValues($propertyUri)
Get the values of a data property.

Return an array of values for the input property URI.

The returned array follow the following conventions:

$subject->getDescription
Get the description of this subject

Returns the description. Returns an empty string if there is none.

$subject->getObjectPropertiesUri
Get the URI of all the object properties that describes this subject

Returns an array of all the URI of the object properties that describe this subject.

$subject->getObjectPropertyValues($propertyUri)
Get the values of an object property.

Return an array of values for the input property URI.

The returned array follow the following conventions:

$subject->getPrefLabel($force = TRUE)
Get the preferred label of this subject

Can force a preferred to be returned. If the  parameter is TRUE (default) then in the worsecase,   will return the subject's URI fragment as the pref label if nothing else is defined for it.

Returns the preferred label. Returns an empty string if there is none and if  is FALSE.

$subject->getPrefURL
Get the preferred URL of this subject

Returns the preferred URL. Returns an empty string if there is none.

$subject->getSubject
Get the array description of the Subject object.

$subject->getTypes
Get all the types of this subject.

Returns an array of types URIs. Returns an empty array if there is none.

$subject->getUri
Get the URI of the subject

Templates Selection
In OSF for Drupal, everything that are manipulated are [resource] entities. Any entity has at least one or multiple types. These types are defined, and hierarchized in an ontology. It is these types that will determine which template will be used by Drupal to theme and display one of these entities.

Let's use this simple, fictive, classes hierarchy that as been defined in one of the loaded ontology to show how the templates are selected by OSF for Drupal:

Now let's assume that we have a the following template files that have been created, and that are located in the  folder of the default theme:

The [resource] entities template selection engine works as follow:
 * 1) Check the types of the entity to display
 * 2) Check if there exist a template for one of its types
 * 3) If a template exists, then the system will select it to theme the content of that entity. The selection process stops there
 * 4) If no template exists for one of its types, then the system check if there exist a template for one of the parent class of one of the types of the entity
 * 5) If a template exists, then the system will select it to theme the content of that entity. The selection process stops there
 * 6) In the case that no template exists, then the default [generic]   template will be used to theme the content of the entity

Given this heuristic, here are the templates that would be loaded depending on the type of the entities that would be selected for all the types of the simple ontology:



First Example: foaf:Organization
Now let's assume that a user is accessing an entity page of type. If we check the classes hierarchy that is currently present in OSF, and if we check the templates that are currently available in Drupal and we if follow the templates selection heuristic defined above, we will see that the  default generic template will be used because there exists no template for that type, and none of its parent classes does have one neither except.

Second Example: foaf:Person
Now let's assume that a user is accessing an entity page of type. If we check the classes hierarchy that is currently present in OSF, and if we check the templates that are currently available in Drupal and we if follow the templates selection heuristic defined above, we will see that the  template will be used because there exists a template for the   class.

Third eExample: foo:PersonByOccupationArtist
Now let's assume that a user is accessing an entity page of type. If we check the classes hierarchy that is currently present in OSF, and if we check the templates that are currently available in Drupal and we if follow the templates selection heuristic defined above, we will see that the  template will be used because there exists a template for a parent class:.

Theming Individual Resource Pages
To theme an individual ResourceType entity, you have to create a template file for the type of entity you want to theme. Then you have to save your template file in one of the following two locations: The name of the template file should follow the following specifications: Here are a few examples of such template names:
 * The name of the file as to be lowercase
 * It should start with the string:
 * It should be followed by a double underscore string to delimit the type of the resource to theme:
 * It should be followed by the prefix of the URI of the class followed by an underscore:
 * It should be followed by the type of the resource:
 * Finally it should ends with:

Theming OSF SearchAPI Results
To theme an individual ResourceType entity as search results, you have to create a template file for the type of entity you want to theme. Then you have to save your template file in one of the following two locations: The name of the template file should follow the following specifications: Here are a few examples of such template names:
 * The name of the file as to be lowercase
 * It should start with the string:
 * It should be followed by a double underscore string to delimit the type of the resource to theme:
 * It should be followed by the prefix of the URI of the class followed by an underscore:
 * It should be followed by the type of the resource:
 * It should be followed by:
 * Finally it should ends with:

Theming OSF SearchProfiles Results
Theming search results that will appears in Search Profiles is exactly the same as theming search results that will appear in normal search results pages. The same templates are used whatever if they are displayed in a search profile or not.

External Drupal Theming Resources

 * Drupal's Core Theming Guide