OSF for Drupal User Manual

From OSF Wiki
Jump to: navigation, search


OSF for Drupal is a set of Drupal modules used to create Drupal websites using the Open Semantic Framework. This user's manual will walk you through the necessary steps to properly configure an OSF instance using Drupal instance, explaining available features as appropriate.

The user manual is composed of a series of articles that explains how a user can configure and use each of the features:

Contents

Initial Configuration

Introduction

Screencast Tutorial

0.jpg

The OSF for Drupal Configuration manual will drives you all the initial OSF for Drupal configuration steps that you have to do in order to connect it to an operational OSF Web Services instance. It assumes that you just finished to install OSF for Drupal using the OSF Installer and that the OSF instance is running on the same instance (but it can be running from anywhere, as long as the Drupal server as access to it).

The first time you will get to you newly installed Drupal portal, you will see that page appearing:

Initial Drupal page after an installation of OSF for Drupal

Registering the Initial OSF Web Services Endpoint

To register a new OSF Web Services endpoint, you have to click on the top Configuration menu item. Note that this page is the main Drupal page where you can configure all the enabled modules. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Now you get to the main OSF for Drupal configuration page. All the configurations for all the OSF modules are accessible from that page. What you want to make sure is that the DATASET & NETWORKS tab is selected. Then you have to click on the OSF API Endpoints link to get to the page where you will register your new endpoint.

OSF for Drupal main configurations page

Then you get to the form where you have to specify all the information that is required to register a new OSF Web Services endpoint to the OSF for Drupal module. The information you have to provide is:

  • Administrative title
    • This is the title that will be use to refere to this endpoint in the user interface across Drupal
  • URI
    • This is the base URL of the OSF Web Services endpoint. It usally ends with /ws/
  • Application ID
    • This is the application ID that will be used by Drupal to communicate with the OSF instance. If you don't use a default one, you will have to check with the OSF instance administrator such that he can provide one to you.
  • API Key
    • This is the API Key that is linked with the Application ID you provided above. This is required such that the Drupal instance can authenticate all the web service queries that it sends to the OSF instance.
  • Color
    • This is the color that is used to highligth that network in the user interface
  • Default
    • This is used to specify if this OSF endpoint instance is the default one. Depending on the OSF for Drupal module, some of them are only using with the default endpoin, others will all the endpoints. For example, the Search module only works with the default endpoint.

Then you have to click the Save button to register that new endpoint.

Registering the initial OSF Web Services endpoint

Once you saved the OSF Web Services to register, you will see it appearing in the list of available OSF endpoints to that Drupal instance. From that OSF API Endpoints section, you will be able to edit, modify, create and delete all the endpoints.

The newly registered endpoint is now displayed in the list of registered endpoints

Importing a Custom Ontology

Before importing a custom dataset into OSF, you should import all the ontologies that are used to describe the content of these datasets.

To import a new ontology, click the top Ontologies menu item.

Osf ontologies menu.PNG

You will get to the OSF Ontology module page. From there, you can import a new ontology by clicking the Import button. A new importation section will appear at the bottom of the ontologies list. Click the Browse button, select the ontology file to import and click the Import Ontology button.

Osf ontology import.PNG

If you want test your new installation using the Iowa Schools testing dataset in the next section, you should download and import the MUNI ontology file from here.

Importing and Exposing an Initial Dataset

Now that we have successfully registered a OSF instance, the next step is to import a new dataset to test this new installation. What you have to do is to click the + Import Dataset link on the DATASETS & NETWORKS tab.

Import a new dataset

The Import Dataset page will let you import a dataset serialized in one of the following formats:

What you have to specify to import a new dataset is:

  • Dataset file to import
    • Select the RDF file you want to import from your local computer
  • Content type
    • Select the type of RDF file you are trying to import
  • Dataset name
    • Define the name of the Dataset you are importing
  • Dataset description (Optional)
    • Optionally define the description of that dataset
  • Custom Dataset URI (Optional)
    • Define the URI of the dataset. If you don't provide any URI, then OSF for Drupal will create one for you
  • Save dataset on this network
    • Choose on which OSF Web Services endpoint you want to import that dataset
  • Which role should have full permissions on this dataset
Note: you may be limited in term of the size of the dataset file you may want to import. If you want to use the Datasets Management Tool if you want to import bigger datasets into the system.


What you can do to test importing a new dataset, is to use this testing dataset that is composed of a list of Schools that exists in the City of Iowa. You can download it from here directly on your desktop. And then select it for importation. If you use this dataset file, you will have to select the Content type RDF+N3

Then you only have to click the Import button to start the dataset importation process.

Form for importing a new dataset

At this point, the dataset got created into the OSF instance. Then all the content of the dataset file you imported as been indexed in that newly created dataset.

Once the dataset is imported, you will get redirected to a new page. If you checked the Check attributes and types existence option, then you would be seeing the possible warnings on that page. If you didn't, then the user interface is asking you to click the Expose Imported Dataset button. The only thing you have to do is to click on that button to get redirected to the form you have to fill to expose the dataset to Drupal.

Exposing the newly imported dataset in Drupal

The last step is to expose the dataset you just imported into the OSF instance to Drupal. If you skip this step, then the dataset will be on the OSF instance, but it won't be usable to any OSF for Drupal module.

  • Administrative title
    • This is the name you want to give to this dataset. This name is local to this Drupal instance. It will be used to refer to the dataset within the user interface of this Drupal portal
  • Dataset is searchable
    • This specifies if you want to have this dataset searchable by the OSF SearchAPI module. If this option is unchecked then the content of this dataset won't participate into the seaches performed by the OSF SearchAPI module

Once you are done, you simply have to click the Save button to expose this newly imported dataset to Drupal.

Form for exposing the new dataset

Now you can see the newly imported dataset in the list of accessible datasets.

The new dataset appears into the list of available datasets

Changing Permissions for the Initial Dataset

One of the last thing you may want to do is to properly setup the permissions of the dataset you just imported. You can read more about the dataset permissions on the Manage Permissions page that explains everything related to these dataset permissions.

If you want to make the content of that new dataset readable by everybody, then you first have to get to the page where you can setup these permissions. On the page that list all the datasets, click the Edit link. Then click the Permissions link.

Then you will get to the page where you can change the permissions of the dataset. Since we want to make the dataset readable to everybody, then we will make sure that all the checkboxes of the Read line are checked. What we are specifying here is that we want all these roles (which includes anonymous users) to be able to read content from that dataset.

Finally you have to scroll down that permissions page, and click the Save button to save the newly configured permissions.

Changing the role permissions for that dataset

Finally, let's browse and search for the records we just imported. You can access an administrative browse & search tool by clicking on the top Resources menu item. Once you click on that menu item, you will get redirected to the page below.

From that page, you can browse the entire content of the datasets that have been exposed to Drupal. You can also search & filter by datasets and types. Additionally, you will be able to perform different operations such as editing, deleting and viewing these records.

If you want to know how this tool work, you can refer you to the Using OSF Entities and Resource Types page.

Browsing the records in that dataset
Finally you should read the OSF for Drupal User Manual to be aware of all the features proposed by the complete set of modules.

Managing Namespaces

In a OSF instance (in RDF) everything is/has a URI. A URI is normally a long string of characters that most often looks like a web URL. However, because of the complexity of these identifiers, most of the time we want to shorter them using prefixes. What this configuration section does is to define all the prefixes that we are expecting to use in Drupal. That list of prefixes will be use internally by Drupal's RDF core features. It will also be used by OSF Entities and other OSF for Drupal modules to use them to simplify the data that is exchanged.

Click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Then click the Entities Connector tab. Now you will see all the configuration options.

To configure the index of prefixes, you have to click the Manage RDF Namespaces button.

OSF Entities configuration options

You will then get redirected to a user interface that list all the namespaces used in conStruct. You will see the prefix and the URI that it refers to. You will be able to delete a prefix by clicking the delete link at the right of each prefix:

Osf entities manage rdf namespaces 1.png
Osf entities manage rdf namespaces 2.png

If required, you will be able to add new prefixes to this index by using the Add a new namespace section as shown here:

Osf entities manage rdf namespaces 3.png

Once you defined the prefix, and once you defined the URI that this prefix refers to, then you will only have to click the Add namespace button to add that new prefix to Drupal.

Managing Web Service Endpoints

Introduction

Screencast Tutorial

0.jpg

The goal of an OSF for Drupal instance is to use the OSF Web Services to create, manage, search and utilize all the data that as been indexed into a OSF instance. This means that all the actions performed by OSF for Drupal, all the data it searches and displays, come from remote web service endpoints.

In this section, we will see how we register, and manage, OSF Web Services endpoints.

A OSF for Drupal portal can use multiple endpoints at the same time. This means that different datasets can be hosted on different OSF instances. The only thing we have to do is to register these endpoints, and to expose the datasets we want to expose, and then the user will manage and use all this data without having to care where it is coming from.

Adding a New Instance

Adding a new OSF Web Services instance is really easy. What you have to do is to click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Then make sure is that the DATASET & NETWORKS tab that

is selected. Then you have to click on the OSF API Endpoints link to get to the page where you will register your new endpoint.

OSF for Drupal main configurations page

Then you get to the form where you have to specify all the information that is required to register a new OSF Web Services endpoint to the OSF for Drupal module. The information you have to provide is:

  • Administrative title
    • This is the title that will be use to refere to this endpoint in the user interface across Drupal
  • URI
    • This is the base URL of the OSF Web Services endpoint. It usally ends with /ws/
  • Application ID
    • This is the application ID that will be used by Drupal to communicate with the OSF instance. If you don't use a default one, you will have to check with the OSF instance administrator such that he can provide one to you.
  • API Key
    • This is the API Key that is linked with the Application ID you provided above. This is required such that the Drupal instance can authenticate all the web service queries that it sends to the OSF instance.
  • Color
    • This is the color that is used to highligth that network in the user interface
  • Default
    • This is used to specify if this OSF endpoint instance is the default one. Depending on the OSF for Drupal module, some of them are only using with the default endpoin, others will all the endpoints. For example, the Search module only works with the default endpoint.

Then you have to click the Save button to register that new endpoint.

Registering the initial OSF Web Services endpoint

Once you saved the OSF Web Services to register, you will see it appearing in the list of available OSF endpoints to that Drupal instance. From that OSF API Endpoints section, you will be able to edit, modify, create and delete all the endpoints.

The newly registered endpoint is now displayed in the list of registered endpoints

The information you have in this list of endpoints is:

  • Endpoint
    • This is the name you specified for this endpoint
      • If the name starts with "Active Default:", then it means that in that list, this is the dataset that is considered to be the default dataset.
  • URI
    • This is the base URL where the web services queries will be directed to
  • Operations
  • Configuration Status
    • The ctools configuration status

Default Endpoint

A OSF for Drupal instance can have multiple OSF Web Services endpoints. One of these registered endpoints will be the default endpoint. Depending on the OSF for Drupal module, it will only work on the default endpoint, while others will be querying all of the endpoints until it gets the answer it is looking for. For example, the following modules/functionalities works on the default endpoint:

  • OSF Ontology
  • OSF QueryBuilder
  • OSF SconesField
  • Creating new Classes/Properties using OSF Entities

Deleting an Existing Instance

What you have to do is to click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Then make sure is that the DATASET & NETWORKS tab that is selected. Then you have to click on the OSF API Endpoints link to get to the page that list all the registered endpoints.

OSF for Drupal main configurations page

Then you will get to the list of endpoints. What you have to do from here is to click the down arrow left to the Edit link of the endpoint you want to delete. Then click the Delete link to delete it. Once you clicked on that link, you will be prompted a new page that will ask you to make sure that you want to delete that endpoint from this Drupal instance.

Unregistering OSF endpoint

Changing the Default Endpoint

What you have to do is to click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Then make sure is that the DATASET & NETWORKS tab that is selected. Then you have to click on the OSF API Endpoints link to get to the page that list all the registered endpoints.

OSF for Drupal main configurations page

Then you will get to the list of endpoints. What you have to do from here is to click the Edit link of the endpoint you want to make default.

Edit OSF endpoint

Finally, what you have to do is to make sure the Default checkbox is checked, and click the Save button.

OSF endpoint configuration page

Once you saved that endpoint, it will become the default OSF endpoint of that OSF for Drupal instance.

Managing Datasets

Introduction

Screencast Tutorial

0.jpg

A dataset is a set of data records (or a set of entities in Drupal parlance) that define access permissions to the data it indexes. Every time you create, read, update or delete an entity, you are creating it, reading it, updating it or deleting it from a dataset where you have the CRUD permissions to perform these actions.

This section shows you how you can manage the datasets on Drupal.

Creating a Dataset

There are two ways to create a dataset:

  1. Importing a dataset using a file where it got serialized
  2. Creating a new, empty, dataset

This section shows you how these two methods can be used on Drupal.

Importing a Dataset

Click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

To import a dataset, you simply have to click the + Import Dataset link on the DATASETS & NETWORKS tab.

Import a new dataset

The Import Dataset page will let you import a dataset serialized in one of the following formats:

What you have to specify to import a new dataset is:

  • Dataset file to import
    • Select the RDF file you want to import from your local computer
  • Content type
    • Select the type of RDF file you are trying to import
  • Dataset name
    • Define the name of the Dataset you are importing
  • Dataset description (Optional)
    • Optionally define the description of that dataset
  • Custom Dataset URI (Optional)
    • Define the URI of the dataset. If you don't provide any URI, then OSF for Drupal will create one for you
  • Save dataset on this network
    • Choose on which OSF Web Services endpoint you want to import that dataset
  • Which role should have full permissions on this dataset
Note: you may be limited in term of the size of the dataset file you may want to import. If you want to use the Datasets Management Tool if you want to import bigger datasets into the system.


Then you only have to click the Import button to start the dataset importation process.

Form for importing a new dataset

At this point, the dataset got created into the OSF instance. All the content of the dataset file you imported as been indexed in that newly created dataset.

Once the dataset is imported, you will get redirected to a new page. If you checked the Check attributes and types existence option, then you would be seeing the possible warnings on that page. If you didn't, then the user interface is asking you to click the Expose Imported Dataset button. The only thing you have to do is to click on that button to get redirected to the form you have to fill to expose the dataset to Drupal.

Exposing the newly imported dataset in Drupal

The last step is to expose the dataset you just imported into the OSF instance to Drupal. If you skip this step, then the dataset will be on the OSF instance, but it won't be usable to any OSF for Drupal module.

  • Administrative title
    • This is the name you want to give to this dataset. This name is local to this Drupal instance. It will be used to refer to the dataset within the user interface of this Drupal portal
  • Dataset is searchable
    • This specifies if you want to have this dataset searchable by the OSF SearchAPI module. If this option is unchecked then the content of this dataset won't participate into the seaches performed by the OSF SearchAPI module

Once you are done, you simply have to click the Save button to expose this newly imported dataset to Drupal.

Form for exposing the new dataset

Now you can see the newly imported dataset in the list of accessible datasets.

The new dataset appears into the list of available datasets

Creating a New Empty Dataset

Click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

To create a new empty dataset, you have to click the + Create New Dataset link from the Dataset & Networks tab.

Creating a new empty dataset

Then you have to specify some important information to create that new dataset:

  • Administrative title
    • This is the title of the dataset that you will use in the OSF instance, and locally on Drupal
  • URI
    • This is the URI that you want to use to identify this new dataset
  • Endpoint
    • This is the OSF Web Services endpoint where you want to create that new dataset. Note that this list of endpoints come from the list of registered OSF Web Services endpoints
  • Role access
  • Dataset is searchable
    • This specifies if you want to have this dataset searchable by the OSF SearchAPI module. If this option is unchecked then the content of this dataset won't participate into the seaches performed by the OSF SearchAPI module

Then once you are done, click the Save button to create the new dataset.

Creating a new empty dataset

Once you created this new empty dataset, it will be created in the OSF Web Services endpoint you selected. It will also be automatically exposed in Drupal. However, it will be completely empty.

The next step would probably be to start creating new entities into this dataset.

Exposing a Dataset

When you register a new OSF Web Service endpoint to the Drupal instance, you should see appearing a list of new datasets in the list of datasets accessible to that Drupal instance. However, it is not because you registered the new endpoint that all the datasets become automatically usable by Drupal.

What you have to do once you registered a new endpoint, is to expose the datasets to Drupal. Once a dataset is exposed to Drupal, it then become available to all the OSF for Drupal modules.

To expose a dataset to Drupal, you first have to click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Then you will get to the page that list all the exposed/unexposed datasets coming from all the registered endpoints. A dataset that is available on a registered endpoint, but that is not exposed, looks like the dataset below:

Available, unexposed dataset

If a dataset is available, you will see "Available:" in front of its title. Then, you have some more information such as its URI, the type which is Disabled and you also know from which Endpoint this dataset is coming from.

If you want to expose that dataset, you have to click on the Add link.

You will get to the page that will ask you to specify some more configuration options for this dataset that you are about to expose to Drupal:

  • Administrative title
    • This is the name you want to give to this dataset. This name is local to this Drupal instance. It will be used to refer to the dataset within the user interface of this Drupal portal
  • Dataset is searchable
    • This specifies if you want to have this dataset searchable by the OSF SearchAPI module. If this option is unchecked then the content of this dataset won't participate into the seaches performed by the OSF SearchAPI module

Once you are done, you simply have to click the Save button to expose the dataset to Drupal.

Form for exposing the dataset

Now you can see the newly imported dataset in the list of accessible datasets.

Exposed dataset

Exporting a Dataset

Screencast Tutorial

0.jpg

Click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

To export a dataset, look for a dataset to export. Then, click the down arrow at the left of the Edit link. Once the panel of possible operations extends, click the Export link.

Dataset export.PNG

Then you will be redirected to the OSF Export module. What you have to do is to specify the export options:

  • Export format
    • Specify the format you want to use to export the dataset
  • Dataset to export
    • Select the dataset you want to export using the tool
  • Number of records per slice (1-1000)
    • It is not possible to export datasets that have more than 1000 records, in one shot, using this tool. The maximum number of records you can export in one click using this tool is 1000. Here you can specify if you want a smaller number of records per slice
  • Slice number to export
    • If you have more records than the number of records per slice you specified, then you can specify which slice of X number of records you want to export in this operation.
If you want to use more powerful OSF export features, then take a look at the Datasets Management Tool command-line tool.


Finally click the Export button to export the data you requested.

Exporting dataset.PNG

Changing Permissions of a Dataset

This section only focus on changing the permissions of a dataset. You can read more about the dataset permissions on the Manage Permissions page that explains everything related to these dataset permissions.

Click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Now to access the page to change the permissions of that dataset, you have to click the down arrow at the left of the Edit link. Then you have to click on the Permissions link.

Changing dataset permissions.png

To change the permissions of the dataset, you have to check the checkboxes to enable the CRUD permissions for different Drupal Roles.

Finally you have to scroll down that permissions page, and click the Save button to save the newly configured permissions.

Changing the role permissions for that dataset

Managing Permissions

Introduction

This page covers the two major permissions topics related to a OSF for Drupal instance:

  1. Dataset permissions
  2. OSF for Drupal modules permissions

The dataset permissions have to do with accessing and managing the data. The modules permissions have to be with accessing the OSF for Drupal tool into the web portal.

How Dataset Permissions Work

In OSF, all the datasets are governed by a series of access permissions. What these access permissions specify are the CRUD permissions for every group of users that exists in the system.

In OSF for Drupal, everything dataset does have Create, Read, Update and Delete permissions attached to all defined Drupal Roles. This means that all the users that have a specific role will inherit the CRUD permissions associated to that role.

By example, if the History Images Iowa City does define full CRUD permissions to the Contributor role, then it means that all the users that have this role will have full CRUD permissions on that History Images Iowa City dataset.

Managing Datasets Permissions

To change the permissions of a dataset, you have to click the Datasets top menu item.

Datasets menu link.PNG

Then select the dataset for which you want to change the permissions and click the down arrow at the right of the Edit link. Then click on the Permissions link.

Changing dataset permissions.png

Then you will get redirected to the section of the Drupal Permissions page where you will be able to configure the dataset permissions.

Datasets permissions.PNG

Every dataset that has been registered to a Drupal instance will appears in the global Drupal Permissions page. Each of the dataset will be highlighted using a different color. It is very important to understand the layout of that page to be able to properly configure the permissions of a dataset.

In the Permission column, we have each colored dataset outlined. We have their name, the endpoint where they are indexed, and the the access permissions (one per row): Create, Read, Update and Delete.

Then you will have one column per Drupal Role. In a default OSF for Drupal instance, you have the following roles defined:

  • Anonymous user
    • This is the guest user. Everybody that access the Drupal portal without being logged in, will be the Anonymous user
  • Authenticated user
    • This is a Drupal authenticated and logged-in user
  • Administrator
    • This is a system administrator. Administrator users always have full CRUD permissions on all registered datasets
  • Contributor
  • Owner/Curator

Let's take a few examples to understand how the permissions should be configured.

  • You want all the guest users of your Drupal portal to be able to read information about a dataset
    • What will be required is that the Read row be checked for the Anonymous user column. Then you have to make sure that the Create, Update and Delete checkboxes are unchecked.
  • You don't want the guest users of your Drupal portal to be able to read information about a dataset
    • What will be required is that you make sure that the Read row is unchecked for that dataset.
  • You want the Contributor users to be able to Create, Read and Update content, but not to delete it
    • What will be required is that the Create, Read and Update rows be checked for the Contributor column. Then you have to make sure that the Delete checkboxe is unchecked.

OSF for Drupal Modules Permissions

These are all the Drupal modules permissions that are related to OSF for Drupal. In this section, we are describing the impact of each of these configurable permission.

  1. OSF Entities Connector
    1. Administer resource types
      1. Specifies if the role can create, modify and delete resource type entities
    2. View resource
      1. Specifies if the role can view individual resource pages
    3. Edit resource
      1. Specifies if the role can edit individual resource pages. This will show the 'Edit' tab on the resource pages
    4. Export resource
      1. Specifies if the role can export individual resource pages in different exportation formats. This will show the 'Export' tab on the resource pages
    5. Advanced edition of ontologies resource
      1. Specifies if the role can can edit ontologies resources (classes and properties)
    6. Delete resource
      1. Specifies if the role can delete an individual resource page. This will show the 'Delete' tab on the resource pages
    7. Administer OSF for Drupal Entities
      1. Specifies if the role can create, modify and delete resources
    8. Add Resource Entity Records
      1. This displays the + Add link to add a new resource in the resources tab
    9. View revisions of resource entities
      1. Specifies if the role can view the revisions tab for the resources
    10. Revert revisions of resource entities
      1. Specifies if the role can revert revisions of a resource
    11. Delete revisions of resource entities
      1. Specifies if the role can delete revisions of a resource
    12. Unpublish revisions of resource entities
      1. Specifies if the role can unpublish revisions of a resource
    13. Compare revisions of resource entities
      1. Specifies if the role can compare resource revisions
  2. OSF Export
    1. access osf export
      1. Specifies if the role can access the OSF Export module
    2. administer osf export
      1. Specifies if the role can administer the OSF Export module settings
  3. OSF Import
    1. access osf import
      1. Specifies if the role can access the OSF Import module
    2. administer osf import
      1. Specifies if the role can administer the OSF Import module settings
  4. OSF Ontology
    1. access osf ontology
      1. Specifies if the role can access the OSF Ontology module
    2. administer osf ontology
      1. Specifies if the role can administer the OSF Ontology module settings
  5. OSF Query Builder
    1. Access OSF Query Builder
      1. Specifies if the role can access the OSF Query Builder module
  6. OSF Search API Connector
    1. administer osf osf_searchapi
      1. Specifies if the role can access the OSF SearchAPI module
  7. OSF for Drupal Core
    1. access osf
      1. Specifies if the role can access the OSF Core module
    2. administer osf
      1. Specifies if the role can administer the OSF Core module settings
    3. access osf proxy
      1. Specifies if the role can access the OSF for Drupal proxy.
      2. The management of this permission is quite important since all the JavaScript applications that uses Ajax queries to the OSF Web Services are using this proxy.
  8. OSF for Drupal Search Profiles
    1. Administer search profiles
      1. Specifies if the role can administer the OSF SearchProfiles module settings
  9. OSF for Drupal config
    1. Administer OSF for Drupal configurations
      1. Specifies if the role can administer the OSF Configure module settings

Managing Resource Types and Entities

Introduction

Screencast Tutorial

0.jpg

Resource types and entities are Drupal Entities that are created, and managed, by the OSF Entities connector module. They are used to expose dataset contents indexed in a OSF Web Services instance into Drupal. The resource types and entities are available to other Drupal modules via the Entity API.

The OSF Entities module is called a "connector" module because it connects the OSF Web Services endpoints to the internal Drupal Entity API.

This page explains how the OSF Entities module can be used to search and browse for records in a OSF instance and how they can be created, updated, deleted and revisionned from Drupal.

This page is organized in three major sections:

  • How to configure the OSF Entities module
  • How to configure the Bundles and Fields to use in Drupal
  • How to manage resources using OSF Entities

Configuring OSF Entities and Resource Types

Configuring OSF Entities

Screencast Tutorial

0.jpg

Configuring OSF Entities is a process that you have to perform to map the classes and properties used in a remote OSF Web Services instance into internal Drupal bundles and fields. Every classes you want to expose in Drupal will be mapped as a bundle and every properties you want to expose in Drupal will be mapped as a field. Once this process of mapping classes and properties into bundles and fields is done, you will be able to use the OSF Entities module which means that you will be able to manage OSF records content from Drupal. To configure the OSF Entities module, you have to click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Then click the Entities Connector tab. Now you will see all the configuration options.

OSF Entities configuration options

Exposing Ontologies to the Mapping Process

The first configuration step that needs to occur is to select the ontologies that are currently loaded into the OSF Web Services instances and that you want to use in the mapping process.

All the ontologies selected here will be exposed to the mapping process below. This means that all their classes and properties will be searchable in the Select Unused Classes and Select Unused Properties sections.

To access this configuration section, you have to click the Select Ontologies button:

Selecting ontologies

Once you clicked that button, you will be redirected to a new page that will list all the ontologies that are currently loaded in the OSF Web Services instances. The only thing you have to do in this section is to select all the ontologies you want to use in the mapping process by checking the checkboxes at their left.

Then you have to click the Save configuration button to save the configuration settings into Drupal.

OSF Entities select ontologies

Mapping Classes and Properties into Bundles and Fields

This is the crux of the OSF Entities configuration. This section explains how the classes and properties mapping process is working. This is a two step process:

  1. The first step is to select all the classes that you want to expose into Drupal using bundles
  2. The second step is to select all the properties you want to expose into Drupal as field instances of the bundles you created in the previous step

Once this configuration step is completed, you will be able to manipulate the OSF records natively into Drupal using its own internal API and various user interfaces.

To start this mapping process, you have to click the Expose Entities button.

Osf entities configurations expose entities.png

The first step of the process is to select all the classes that you want to expose to Drupal. A OSF Web Services instance is composed of number of datasets that defined hundred of thousands of records and that are defined using tens of classes and properties. However, not all these records and these classes necessarily need to be exposed into a Drupal portal. This is why the initial step is to only select the classes that we really want to expose to the Drupal portal.

All the classes that we will be selecting on this page will create a bundle in Drupal. What that means is that content maintainer will be able to create new records of these types. They will be able to modify existing records of these types, and they will be able to delete records of these types. This means that all the records of these selected classes will be manageable within the Drupal user interface.

This page as two major sections:

  1. Select Used Classes
  2. Select Unused Classes

It is important to understand the distinction between these two sections.

In the Select Used Classes section, what we have there is a list of all the classes that are currently being used to describe record content into the OSF instance. This is a convenient way to say: check these classes, there are a good chance you want to map them since they are currently being used to describe records content into the OSF instance. By selecting classes in this section, you will create a new Drupal bundle for each of them.

Also note that some of the classes are pre-select and disabled (grayed). This means that these classes are always present in Drupal, and that they are core concepts that need to be mapped.

Osf entities used classes.PNG

Then we have the Select Unused Classes section. This section is used to handle a specific usecase: you want to expose a class that is defined in a loaded ontology, however there is currently no record instances using that class in the OSF instance.

The common usecase for that section is that you want to create a new kind of record, in the OSF instance, using the Drupal user interface. Since no records of this type currently exists in the OSF instance, it means that it won't appear in the Select Used Classes section above. It is for that reason that you have to select the class in this section. Just like with the section above, a new bundle will be created from that class.

If you cannot find the class that you are looking for, make sure that you selected the ontology where that class is defined, as explained in the Exposing ontologies to the mapping process section above.


Osf entities expose entities select unused classes.png

Once you are done, you have to click the Next, select properties button which will redirect you to the second page (step) of the mapping process.

Now that you selected the classes you want to map as bundles into Drupal, the next step is to select all the properties you want to map as fields into Drupal. When you create and modify records information in Drupal, you are doing this using conventional HTML forms. Each field of the form is a property and a value that you want to define to describe a specific instance record (a thing). What this property mapping does is to define all the fields that will be presented to the content maintainer in the create/edit forms generated by Drupal.

There is one important thing to know at this point: every field type that will be used for the fields that are created in this process are defined in the ontologies. If you want to know how you can influence the field type selection at this stage, I strongly suggest you to read the Configure Ontologies for Selecting Field Types page.

Here is the list of all supported Field Type and Wiget by OSF Entities:


Field Type Field Type Machine Name Field Type Named Individual
Date date http://purl.org/ontology/drupal#Date
Date (ISO format) datetime http://purl.org/ontology/drupal#DateISO
Date (Unix timestamp) datestamp http://purl.org/ontology/drupal#DateUnixTimestamp
Boolean list_boolean http://purl.org/ontology/drupal#Boolean
Decimal number_decimal http://purl.org/ontology/drupal#Decimal
File file http://purl.org/ontology/drupal#File
Image image http://purl.org/ontology/drupal#Image
Float number_float http://purl.org/ontology/drupal#Float
List (Float) list_float http://purl.org/ontology/drupal#ListFloat
List (Integer) list_integer http://purl.org/ontology/drupal#ListInteger
List (Text) list_text http://purl.org/ontology/drupal#ListText
Link link http://purl.org/ontology/drupal#Link
Long text and summary text_with_summary http://purl.org/ontology/drupal#LongTextAndSummary
Long text text_textarea http://purl.org/ontology/drupal#LongText
Text text http://purl.org/ontology/drupal#Text
Geolocation geolocation_latlng http://purl.org/ontology/drupal#Geolocation

When you first get to that page, you will notice that there is a section for each and every classes you selected from the previous classes mapping step. What we are doing in this section is to select the properties to map for each of these classes you selected. What you have to do is to expend each of these section to make sure that you exposed all the properties you wanted to expose.

Just like with the classes mapping section, for each classes section, you have a Used Properties and Select Unused Properties section. The rational is the same. In the Used Properties section, you get the list of all the properties that are currently used to describe a record of that class type in the OSF instance. Then, if you want to expose another property (that is not currently used), then you have to select it from the Select Unused Properties section.

Osf entities expose properties.PNG

Then, when you are done selecting all the properties for all the classes, the last thing you have to do is to click the Expose button. Depending on how many classes and properties you are mapping, it may take a few minutes to finish loading this process. You shouldn't close your browser's page, nor refresh the page while the page is loading after you click the Expose button.

Osf entities expose classes properties.PNG

Once the next page loaded, you are done with the core of the OSF Entities configuration steps. You will now endup with a series of bundles and fields internally in Drupal. In the following sections we will see the impact of this exposition process, and what this enables you do to.

This process of exposing classes and properties into Drupal is not static in time. In the future, you will most than likely will have to start manipulating new kind of classes, or to start using new kind of properties for some of the bundles. What you will have to do is to do this process again to select more classes and properties to expose into Drupal.

Other Entities Settings

There is one other feature that can be configured into OSF Entities. This feature call Enable autocompletion fields for datatype properties values is used when you are creating new records, or when you are modifying existing ones. If you enable this configuration option, then it means that when you will create/edit a record using the Drupal user interface, all the fields (properties) that have strings has values will have an autocompletion behavior. What this autocompletion behavior will do is to list all the textual values currently defined in the OSF instance that are referenced by these properties by records of that same type.

This option is disabled by default but can be really powerful depending on the requirements.

Struct entities configurations auto completion 2.png

Configuring OSF Resource Types

Once you clicked the Expose button in the previous classes and properties exposing process above, you then create a series of Drupal Bundles, Fields and Fields Instances. These three things are what will enable you to generate the HTML forms that will be used to create new records and edit existing ones.

What will be discussed in this section is not different to what you do with the Content Types bundles. These are just different kinds of bundles, used to manipulate records information in Drupal but directly into the OSF instance.

Create/Modify/Delete Resource Type Bundles and Fields

To see all the Resource Types bundles you created above, you have to click the Structure top menu item. This will show you the complete list of all the existing type of Drupal bundles. As you can see, there is a Resource Types item that you can click to see the complete list of Resource Types bundles that are currently existing on your Drupal portal.

Osf entities structure.png

Once you clicked on that link, you will see a list of the existing bundles. There are multiple things you can do from that page:

  • You can edit the information about one of the bundle
  • You can manage the fields associated with one of the bundle
  • You can manage the display of the fields (how they get displayed in the generated HTML forms) of one of the bundle
  • You can re-organize the existing resource type (this redirect you to the first step of the exposition process as outlined above)
  • You can add a new resource type (this is a utility user interface that let you create a new class in an ontology, and then to create a bundle for it)
Osf entities structure resource types.png

Edit a Resource Type Bundle

If you click on the Edit operation on the page that list all the existing bundles, you will get to that bundle edition page. What you can do here is to change the display name of that bundle (its Label). You can also add a description.

However, the most important option in this edition page is the Ignore synchronized resource type option. If this option is checked, it means that the exposed class won't be usable to the end user (for editing content of that type, to create new content of that type, etc). However, it will be usable internally by Drupal. If a bundle has this option checked, then you will see Ignored - in front of its label in the list of all the bundles (as you can notice in the screenshot above).

Osf entities structure resource types edit.png

Manage the Fields of a Resource Type Bundle

If you click the Manage fields link from the page that lists all the bundles, then you will get to this section that enable you to edit the fields currently defined for the bundle. What you can do here is to change the field, remove it, change its label, etc. by clicking the different operations.

Osf entities manage fields.PNG
Configuring Field Widgets

Once all the bundles and fields have been created in Drupal using the OSF Entities mapping process, you can continue the configuration process of these fields by specifying the field widgets you want to use for each of them, and then to configure each of these field widgets such that they behave the way you want them to behave.

The first thing to do is to click the field widget's name that appears in the WIDGET column of the list of fields in the bundle you are editing.

Osf entities manage fields widgets.PNG

Then you will be prompted with a list of field widgets that you can use for this field type. Select the one you want to use and save your configuration option. Then Drupal will prompt you with a series of additional configurations that you will be able to configure for that given field widget.

Here is the list of all the field widgets, by field type, that are supported by OSF Entities:


Field Type Field Widget Widget Example
Text Text Field
Img 5.PNG
OSF Entity Reference
Img 20.PNG
OSF Concept Reference (Tagging)
Img 19.PNG
Long text and summary Text area with a summary
Img 17.PNG
Long text Text area (multiple rows)
Img 19.PNG
List (text) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
List (integer) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
List (float) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
Link Link
Img 14.PNG
Integer Text field
Img 5.PNG
Float Text field
Img 5.PNG
Image Image
Img 13.PNG
File File
Img 10.PNG
Entity Reference Select list
Img 7.PNG
Check boxes/radio buttons
Img 6.PNG
Autocomplete
Img 8.PNG
Autocomplete (Tags style)
Img 8.PNG
Decimal Text field
Img 5.PNG
Date (Unix timestamp) Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Date (ISO format) Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Date Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Boolean Check boxes/radio buttons
Img 2.PNG
Single on/off checkbox
Img 1.PNG
Geolocation Latitude/Longitude
Img 11.PNG
Google Map
Img 12.PNG

Manage the Display of Fields for a Resource Type Bundle

If you click the Manage display link from the page that lists all the bundles, then you will get to this section that let you re-order and modify the display of these fields. As you will see in the sections below, all the fields of a bundle will be displayed as an HTML form that the content maintainer will use to create and edit records data in the OSF instance. What you can do is to re-order the fields in that list such that you get the more important fields at the top of the form, etc.

Osf entities manage fields display.PNG

What you can additionally do is to hide some of the fields. What that means that is these fields will still be taken into account, but they won't be displayed in the forms that will be generated by Drupal. To be able to hide such a field, you have to drag-and-drop it into the Hidden section as shown below:

Osf entities manage fields display hidden.PNG

Once you are done modifying the display of the fields, you simply have to click the Save button.

Add a New Resource Type Bundle

At any time you can click the + Add new resource type link to create a new Resource Type. This will redirect you to this form that let you create a new Resource Type.

Osf entities manage create new resource type.PNG

As you know, all the resource type bundles are referring to an ontology class existing in the loaded ontologies in a OSF instance. What this feature does is to bypass the classes mapping workflow as described above to directly create a new class in a selected ontology, and then to create a new bundle for it. What you have to specify is:

  • Name
    • The name of the new Resource Type to create. This name will be used to create the URI of the class in the selected ontology
  • Ontology
    • The ontology where you want to create the new class that will be mapped to the new resource type
  • Description
    • The optional description of that resource type

Once you click the Save resource type button, two things will happen:

  1. A new class will be created in the selected ontology
  2. A new bundle will be created, and referring to that new class
The new class will be created under the Thing top concept of the selected ontology. If you want to re-organize the newly created class elsewhere in the ontologies structure, you should use the OSF Ontology module to position it elsewhere in your ontology.

Using OSF Entities and Resource Types

This section will show you all the features that are enabled on the OSF Entities is configured in a Drupal instance.

Browsing and Searching Resources

Screencast Tutorial

0.jpg

One of the core feature that OSF Entities provide, is a tool that the content authors can use to search, browse and filter all the content they have access to from a OSF instance. What that means is that if a particular user only has access to the datasets X, Y and Z, then he will only see the results from these datasets when he will be using this search, browse and filter tool. Another user that has access to the datasets A, B and C will only see the results from these datasets as well. This means that this same user interface can be used to navigate information from the data sources a user has access to.

To access this section, you have to click the Resource top menu item.

Osf entities resource tab.png

Once you clicked that menu item, you will be redirected to a page that will let you search, browse and filter the information you have access to. The first operation to perform can be a simple search query for the keyword 'iowa'. Once you clicked the Search button, you will get a list of results that match this keyword.

If you want to remove the search keyword, and if you want to re-perform the search without that keyword, you you simply have to click the Remove button.

Osf entities resources search.PNG

Once you started to search for specific records, you can additionally apply different filtering criterias to the search query. There are currently two filtering criterias that you can use to filter your data:

  1. The dataset provenance of the records
  2. The type of the records

If you want to search exclusively within the content of a dataset, then what you will have to do is to select that dataset and click the Filter button. Once you clicked that button, a search will be re-issued by the system, and you will be presented all the records, from that dataset, that match the search keywords.

Then if you want to search only within a specific kind of records, then you can select that type, and click the Refine button. At that point, you will be performing a search that match the search keywords, for the records indexed in that dataset and that use that type.

At any time you can click the Reset button to remove all the filters applied to that search.

Osf entities resources search filter.PNG

Another option you have is to select the columns you want to display on that page. Not all columns are necessary for everybody. By checking the columns and by clicking the Reorganize button, you will be able to show/hide different columns. These settings will persist over time, for the user that you are logged with.

Osf entities resources search columns.PNG

Once you did perform a search, you will get a series of matching records from the OSF instance. Depending on the columns you have selected, you will see:

  1. The preferred label of the record
  2. The URI of the record (hidden by default)
  3. The type of the record
  4. The dataset provenance of the record
  5. The status of the record
  6. Different operations you can perform on the record

When you use this searching tool, you are searching all the records you have access to in the OSF instance. However, it is not necessarily all the record types that have been exposed as bundle in Drupal. This is where the STATUS columns comes into play. You do have two status possible in that column:

  1. Exposed
  2. Available

If the status is Exposed, then it means that the record that is returned to you is currently exposed in Drupal. That means that there exists a bundle for that type of record.

If the status is Available, then it means that the record is accessible to you, but that there is no bundle that expose that type of record to Drupal. This means that this class didn't get exposed to Drupal and so that no bundle exists for that kind of record. If a record is marked as Available, then you will have an option to start exposing that class into Drupal.

The you have 4 different kind of operations possible:

  1. Edit
  2. Delete
  3. Configure dataset for editing
  4. Expose

If the edit link is clicked, then you will be redirected to a page where you will be able to edit all the information related to that record.

If the delete link is clicked, then you will be redirected to a page that ask you if you really want to delete that record.

If the configure dataset for editing link is displayed for a record, that means that this record is indexed in a dataset that you have access to, but that is not currently configured in the OSF for Drupal module. What that means is that this record is no available to any other OSF for Drupal tool since it is not (yet) configured in OSF Configure. Once it get configured in OSF Configure, the available options will change accordingly.

If the expose link is displayed for a record, that means that the record is available, but there is no bundle for its type. If you click on that link, you will be redirected to expose that type class as a bundle in Drupal.

Finally, you have a final filtering option that is available to you check is called Show available records that are not currently exposed in the portal. If this option is checked, and if the Show available button is clicked, then it means that you will start seeing records that have a status of available. By default, these available records are shown. However, you can hide them by using that option.

Osf entities resources search available.PNG

Creating New Resources

One of the core reason why we want the OSF Entities module enabled and configured is to be able to create new records and to index them directly into the OSF instance. That means that the new record would become available to other portals that would use the same OSF instance.

To create a new record, you have to click the top Resource menu item. Then you have to click the + Add resource link.

Osf entities add record.png

Once you clicked that link, you will be redirected to a page that will display all the type of Resource Type records that you can create.

If you edited the created bundles, and if you clicked the option Ignore synchronized resource type then you won't see these bundles appearing in that list.


The next step is to click on one of these link to start creating a new record of these types.

Osf new resource.PNG

Once you clicked on one of these links, then you will be redirected to a page where you will see an HTML form that you will be able to use to populate information about that new record you are about to create. This form is generated by Drupal depending on the way to configured the bundle and its fields in the Configuring Resource Type Bundles and Fields section above.

There are minimally three (3) required fields in that form:

  1. Unique identifier
  2. Dataset
  3. Preferred label

The first thing to determine is what is the unique identifier of the new record you are creating. This unique identifier is a string that as alpha numeric characters, underscores "_", dot "." or dash "-" characters. The unique identifier can be anything. However it is normally related to the preferred label you will choose to define. An example of unique identifier could be "iowa_public_school_a".

The the second thing you have to determine is where the record should be indexed, in which dataset. The user interface will present you a drop-down list of all the datasets where you can create new records.

Finally you will have to write the preferred label of that record.

Once you defined your unique identifier, and once you selected your dataset, you will be defining the complete unique identifier (URI) of the record you are about to create.

Let's say that you defined the unique identifier to be iowa_public_school_a. Then you choose the dataset "Iowa Public Schools". This dataset has the URI http://localhost/datasets/iowa_public_schools/.

What the system will do is to create a final unique identifier by concatenating these two values. This means that the real URI of the record you creating will be:

http://localhost/datasets/iowa_public_schools/iowa_public_school_a


Osf creating new resource.PNG

Finally what you can do is to add values for all the other fields displayed in that HTML form.

Modifying and Revising Resources

Another of the core reason why we want the OSF Entities module enabled and configured is to be able to modify and revision existing records directly into the OSF instance. That means that the changes to a record will become available to other portals that would use the same OSF instance.

If you click on one of the record displayed by the search tool discussed above, you will get to that page below. What this page does is to show you a (generic) view of that record which list all the properties and values that define that record. As you can notice, there are a few tabs at the top of that page. The one that currently interest us is the Edit tab.

Osf entity view.PNG

When you click the Edit tab, you get redirected to a page similar to the one that we saw when we were creating a new record. The main difference is that the fields are pre-populated with the current values that describe that record. The purpose of this user interface is that it let you:

  1. Modify existing information
  2. Remove existing information
  3. Add new information to what already exists for that record
Osf entity edit.PNG

In these forms, there are two different type of fields:

  1. The fields that reference another record/entity
  2. The fields that have a string as value

The fields that reference other records/entities are using the OSF Entity Reference field widget. You should refer to the Configuring and Using the OSF Entity Reference Field Widget page to know how to configure and use that widget. You will only be able to reference entities that currently exists into the OSF instance. The widget will let you search for the entities you want to reference. Depending how the widget is configured, you will be able to select one or multiple entities. All the selected entities will appear in blue boxes like this:

Img 20.PNG

Then the fields that have a string has value (so, all the fields that doesn't reference to another entity) can use a long list of field widgets. Each of these field widgets are different user interfaces that are used to help the user to specify the right value for a given property/field. Here is the list of all these field widget currently supported by OSF Entities, and a screenshot of each of them:


Field Type Field Widget Widget Example
Text Text Field
Img 5.PNG
OSF Entity Reference
Img 20.PNG
OSF Concept Reference (Tagging)
Img 19.PNG
Long text and summary Text area with a summary
Img 17.PNG
Long text Text area (multiple rows)
Img 19.PNG
List (text) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
List (integer) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
List (float) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
Link Link
Img 14.PNG
Integer Text field
Img 5.PNG
Float Text field
Img 5.PNG
Image Image
Img 13.PNG
File File
Img 10.PNG
Entity Reference Select list
Img 7.PNG
Check boxes/radio buttons
Img 6.PNG
Autocomplete
Img 8.PNG
Autocomplete (Tags style)
Img 8.PNG
Decimal Text field
Img 5.PNG
Date (Unix timestamp) Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Date (ISO format) Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Date Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Boolean Check boxes/radio buttons
Img 2.PNG
Single on/off checkbox
Img 1.PNG
Geolocation Latitude/Longitude
Img 11.PNG
Google Map
Img 12.PNG

Finally, before saving a record, you will be asked if you want to moderate the modification you are doing. You have three options:

  1. Modify current resource, no revision, no moderation
    1. If this option is used, then the modifications you did to this record will be directly modified in the OSF instance without creating a revision with the changes. With this option, rollback of the changes is not possible
  2. Create new revision, no moderation
    1. If this option is used, then the modifications you did to this record will be directly modified in the OSF instance, but a new revision record will be create with these changes. With this option, roolback o the changes is possible
  3. Create new revision and moderate
    1. If this option is used, then the modifications you did to this record will not be directly modified in the OSF instance. A new revision will be created with the changes, but the modifications of the record won't be published. These changes will need to be moderated, and then they will eventually be published to the dataset.
Osf entities entity edit revision.png

If you choose one of the two options that create a revision, then you will see appearing a new Revisions tab as shown below.

If you click on that tab, you will be presented a list of revisions that exists for that record. The currently published revision will appear with a yellow background. For each revision, you have three operations:

  1. Visualize the revision by clicking on the date of the revision on the left side of a record line
  2. Publish a revision by clicking the revert link in the Operations column
  3. Delete a revision by clicking the delete link in the Operations column

By visualizing a revision, you see what the record will look like if it would be published.

By publishing a revision, you are in fact re-creating a new revision record, but using this previous status. This means that the published record will become a copy of the revision where you clicked revert.

By deleting a revision, you are simply deleting the revision in the system. This means that you won't be able to rollback the changes you made with that revision.

Osf entities entity edit revision view.png

Another thing you can do with this revisions section, is to compare two revisions. To compare two revisions, you have to click the compare link of one of the revision record. Once you did this, the values of the Compare column will change. Then what you have to do is to click the with link such that you compare the revision you previously selected with that other revision.

Osf entities entity edit revision compare.png

Once you selected the two revisions records that you want to compare, you will be presented a user interface that show you all the modifications that occurred between the two revisions. What you will see in this user interface is:

  • The new properties/values that may have been added on one side or the other
  • All the text, within the values, that may have change (added or removed), one one side or the other
Osf entities entity edit revision compare view.png

Deleting Resources

Another thing you can do with OSF Entities is to delete a record in the OSF instance using the Drupal user interface. What you have to do to delete a record is to:

  • Click the delete link operation in the search user interface as shown above
  • Click the Delete tab when you are viewing a record

Once you did one of these two actions, you will be presented a user interface that ask you if you are really sure to want to remove that record.

When you delete a record, internally, in an OSF instance, it is a soft delete that is performed. What this means is that the record is actually unpublished. However, all the revisions of the record are still existing which means that it could be re-published in the future. However, there is currently no facility in the OSF Entities to detect these records for re-publishing them in the future, this would need to be done by hands directly on the OSF instance. Also, in the future, an option could be presented to use user to know which kind of delete he would like to perform (soft or hard delete).

Osf entities entity delete.png

Exporting Resources

Screencast Tutorial

0.jpg

All and every Resources Entities can be exported. If the permissions are properly configured, an Export tab appears on the individual records pages. By clicking on that tab, you will be redirected to a page that list a series of serialization format that you can use to export the content of that resource page. The supported formats are:

Osf entities entity export.png

Using the SearchAPI

Introduction

Screencast Tutorial

0.jpg

The Drupal SearchAPI is a module that is used to create a search engine for a Drupal website. OSF for Drupal does re-implement the general SearchAPI to be able to communicate with the Search web service endpoint.

Note: it is assumed that you installed OSF for Drupal with the OSF Installer script. This means that the SearchAPI server and index are already configured in your instance. If not, then you will have to create them by hands.


Configuring the Search Engine Server

The first step is to configure the search engine. Even if we consider that the search server is already configured, we will see what are these configurations and how they can eventually be modified.

To access the configuration pages of the search engine, you have to click on the top Configuration menu item. Then you have to search an click on the Search API link.

Searchapi access.PNG

Then you will get to the list of all the configure SearchAPI Servers and Indexes. If you installed OSF for Drupal using the OSF Installer tool, then you should see appearing the OSF Search server and the OSF Search Index index.

Note: If you have to configure them by hands, it is essential that the name of the Server is OSF Search and the name of the index is OSF Search Index. That way, the machine names for this server and this index will be properly generated and usable by the OSF SearchAPI module.


Searchapi servers indexes list.PNG

First, let's edit the OSF Search server by clicking the edit link for that line item.

Searchapi edit server.png

There is one major feature other than the server's name: the OSF Service's endpoint. In the Network options list, you have the list of all the registered OSF Web Services endpoints on that Drupal instance. What you have to do is to select the one you want to use where to send the Search queries.

Once you selected the OSF Web Services endpoint to use, you only have to click Save settings.

Searchapi editing server.PNG

Configuring the Search Page

Once the search server is properly configured, the next step is to configure the search page. The search page is the URL where the search engine will be accessible to the users. By going to that URL, the users will be able to use the search engine we are configuring.

To access the search pages, you have to click the Search Pages tab when you are looking at the list of available servers and indexes.

Searchapi edit search pages.png

This will redirect you to the list of available search pages. If you installed OSF for Drupal using the OSF Installer tool, you should see a search page that has lookup as the path. Then if we want to edit that path, we have to click the edit link.

Searchapi search pages list.PNG

The setting we are interested in in this page is the Path. The path is the URL path where the search engine page will be accessible. If the search page is configured like this, it means that the search engine page will be available to the users that goes to this URL:

Searchapi edit search page.PNG

Configuring Search Facets

Once the search server and the search page are properly configured, one thing that the administrators may want to do is to configure a series of search facets blocks that would be available to the users to facet the information they are searching for.

To configure the facets, you have to click the edit link for the index. Then click the Facets link that will appear.

Searchapi edit index.png

You will then get redirected to the page that list all the available facets to the users (there can be quite a few). All the properties that are used in any available dataset may become a facet in the search engine. In this example, we selected the district and the Dataset facets.

Once you selected all the facets you want to expose, you have to click the Save configuration button.

What happen when you click that button is that a Block will be created for each facet you selected.

Searchapi index facets.PNG

The next step is to configure the facet blocks that you created by selecting the facets to expose. What you have to do is to go to the list of all blocks, and then search for the Facet API: Search service: OSF Search Index: Facet-ABC blocks. These are the blocks that have been created by the previous step. All the facets will be displayed in these blocks.

Searchapi facet blocks.PNG

By default, these blocks are disabled. The next step is to position the blocks in the layout of your theme. Once you positioned them, you have to click to save the configuration of the blocks before configuring the blocks individually.

Searchapi facet blocks positioning.PNG

The last step is to configure the blocks. Beside the positioning of the blocks, the main configuration options for these facets blocks are the visibility settings. There are the settings you will be using to determine where (which page) and who will have access to these facets blocks.

Searchapi facet block configuration.PNG

Using the Search Engine

Once everything is properly configured, you can go to the lookup page to start searching for content that comes from your OSF instance. There are three major areas in a search page:

  1. Search box
  2. Search results
  3. Search facets

If you enter a search keyword in the search box, then all the results will appear below that search box and the facets blocks will appears where they got positioned. Each of the facets that have been exposed will be populated with a series of values that could be used to filter the content of the search resultset. The number of records in each facet is displayed in parenthesis.

It is also possible to theme the results that are returned. Check the Theming OSF SearchAPI results section for more information.

Searchapi search.PNG

If you click on one of the facet, you will be redirected to a new search page where the facet as been applied. The number of results should go down after the facet is applied to the search query. More than one facet can be applied to a single search query. Search facets can be removed by clicking the (-) link.

Searchapi search with facet.PNG

Using Search Profiles

Introduction

A search profile is a predefined search query where its search results are displayed in a block positioned on some Drupal pages. These search profiles are normally used to display list of information that match a search query. Search profiles are also to some extend aware of their context. For example, if the main topic of a page is about cancer and if we have a search profile that displays list of events, then when the search profile is used in the context of that page about cancer, then cancer related events should be displayed. That is one of the core purpose of the search profiles.

Three things needs to happen with search profiles

  1. Initially, the search query to be used in a search profile need to be created using the OSF Query Builder
  2. Then the search profile need to be embedded into a Drupal Block
  3. Finally, the Block need to be positioned in the Drupal portal

Using the Query Builder

The query builder (QB) is a generalized search utility for querying the datasets within a OSF instance. The QB has three purposes:

  1. It is a basis for learning about the structured data within a OSF instance
  2. It is a testbed for exploring the effect of attribute and value boostings on the ranking order of search results sets, and
  3. It is a means to refine queries and then generate query code that can be embedded into Web pages and templates.

General Overview and Operation

The QB consists of a top-line search box, followed below by a series of expand-and-collapse panels. Specialized actions take place within these panels. The operations of each of these panels is described below. Each panel also has a help icon, which when clicked brings up contextual help for that panel.

Upon invoking a search, a results listing appears at the bottom of the standard panels. Please make sure and review the Results Listing section since how results are presented in the query builder is one of its benefits.

The overall screenshot for the query builder is as follows:

Qb main.PNG

Search Box and Input

Any standard site query may be entered into the search box. For legal and available query syntax, see the Search Syntax page.

A search is conducted upon invoking the Search button. The resulting results set is then listed at the bottom of the page in scoring rank order. A Clear causes all settings throughout the QB to be returned to its default (start-up) settings, as if the application were reloaded. The one exception is that if a query had been entered into the top-line search box, it is kept.

Note: these same Search and Clear operations apply when the buttons are encountered on other panels.


The gear icon at far right turns inferencing on or not. By default, inferencing is on. To test the effect of inferencing, conduct the same search with inferencing on or not and select the 'type' attribute in one of the lower panels. When inferencing is on, generally the results set is much larger since matches to related (inferred) concepts are brought into the results.

Note: inferencing is presently limited to the type attribute; an imminent release will expand this to include the subject attribute.


Note: if you do not enter a query within the search entry box, a Search will bring up a results set containing the records of all active datasets.


Dataset Panel

Clicking on the Dataset panel causes it to expand. The panel then shows all datasets available on the default OSF endpoint:

Qb datasets.PNG

Each of the datasets may be included or not in the content basis used by the query builder by checking or unchecking its associated checkbox. Alternatively, all datasets may be selected or not using the global links at the top of the panel.

Each dataset shown also provides a count (in parentheses after the dataset title) for how many records it contains. If a query has already been entered into the top-line search box, these counts pertain to the number of record instances where the search query exists. If there is no query in the search box, the counts shown are for total numbers of records in each dataset.

As datasets are selected, their total number appears in the panel header. Whatever dataset selections are made in this panel remain active during the current QB session or until you actively change them. Upon next startup of the QB, all available datasets are selected as active by default.

Note: for content inspections, make sure to restrict your datasets to the public content, also excluding the underlying ontologies and vocabularies.


Advanced Search Panel

The Advanced Search panel allows quite complicated queries to be built. These extensions are added to whatever query already exists in the top-line search box. If there is no query in that search box, then the specifications in this panel apply on their own.

Like the other panels, clicking on it causes it to expand; clicking on the expanded header causes it to collapse. Also, like all other panels, contextual help is provided via the icon button at the upper right of the panel.

When first expanded, a single line of new query expansion is presented. This line, from left to right, has an operator box, followed by an attribute selection dropdown, and then a means to assign a value to that attribute in the next box. At the end of the line a [+] button allows a new line to be added for additional query expansion. If the [-] button is selected, the current line is removed. The basic aspect of this panel is as shown:

Qb advanced search.png

The operator box enables multiple query expansion lines to be combined together or nested. The available operators are AND, OR or NOT, in combination or not with parentheses if nesting is also desired. They are selected via this dropdown list:

Qb operators.png
Note: the first and last operator boxes shown are limited to the open ("(") and close (")") parentheses, respectively.


Note: an improperly specified or missing operator box will show in red when attempting to invoke a search. The operator must be corrected before the search will be accepted for processing. Here is how this error looks:


Qb bad operator.png

For a single expansion line, no operator needs to be designated in this first operator box. Thereafter, an operator must be specified to "chain together" more query expansion lines.

Once the operator is selected (or not, for a single line), it is next necessary to select one of the available attributes. These appear as a dropdown list in the next box. This attribute box features autocompletion, so beginning to type a few letters will match those same letters in the attribute titles no matter where the matching string may occur (beginning, middle or end of a word). As more letters get typed into the combobox entry, the selections get fewer.

Note: autocompletion typically starts once you place the cursor into the applicable text or combobox.


The available attributes to select from also may be reduced in number based on prior selections or a query already entered into the top-line search box. That is, the attributes available for selection at any given step are limited to those that are active for the query that has been built to that point, with the narrowing occurring each time the 'Search' button is invoked without an intervening 'Clear'.

Note: invoking a 'Search' is necessary to narrow available attribute and value options.


Thus, very complicated query constructions may result in very few attributes being available for further filtering.

The attributes themselves are of two types: There are free text entries and controlled vocabular entries, with these icons appearing in the adjacent values dropdown combobox. For free text entries, any term or string may be entered into this box; for controlled vocabulary entries, you must pick from one of the available options, which are presented to you via a dropddown list, also shown with an autocompletion icon. Like other autocompletion fields, typing more characters causes the possible entries to be narrowed to those that match the string. A good attribute to try this feature with is Subject, since there is a long list of subjects within the available ontologies.

You may construct as many query expansion lines as you would like, again with the caveat that attribute choices will continue to narrow with more filters. If you want to back up a step, you can delete the entire line.

At the bottom of the panel, a search may be invoked via the 'Search' button or all QB settings may be 'Clear' back to original settings. These buttons may be applied here, on this panel, or via the same buttons on the top-line search input.

Attributes Restrictions & Boosting Panel

The Attributes Restrictions and Boosting panel allows you to filter search results by attribute and to change boost values to affect the rankings of the results set. The attribute filters work in conjunction with any other specifications that have been made above, namely simple or advanced search.

Like the other panels, clicking on the Attributes panel causes it to expand; clicking on the expanded header causes it to collapse. Also, like all other panels, contextual help is provided via the icon button at the upper right of the panel. Here is the basic view of this panel:

Qb attributes restrictions.png

The attributes combobox works similarly to what was described for Advanced Search. Via autocompletion and the entry of a few characters, the listing of possible attributes to select from gets narrowed. Further, only those attributes that meet the dataset and query selections made elsewhere appear on this list.

Note: invoking a 'Search' is necessary to narrow available attribute and value options.


Any attribute selected in this panel MUST exist in a given record in order for that result to appear in the results list. Thus, any entry, no matter the boosting weight assigned, must appear for a positive search hit. However, also note that ANY value for that attribute will satisfy the condition and be acceptable. (For actual value filtering, see next section.)

Once a filter is selected, it is then possible to indicate its relative weight in the results set ranking order. You do this by changing the value at the right of the entry line.

Note: by convention, all initial boost weights are set to 1.0. Thus, a value greater than 1.0 means the attribute is to be ranked higher; a value less than 1.0 means the attribute is to be ranked lower than standard.


Note: the actual algorithm to construct a "score" for a given result can be quite complicated in the search function. As a result, it is often hard to see a commensurate change in score via the boost, though a numeric impact will occur and rank order will most likely change.


The plus (+) button allows you to enter another filter or weighting boost. You may add as many of these filters as you wish.

Note: to test the effect of boost differences, first run a search without boost and inspect the resulting search scores as described under Results Listing below. Then, run again with the boosts and inspect score and ranking differences.


At the bottom of the panel, a search may be invoked via the 'Search' button or all QB settings may be 'Clear' back to original settings. These buttons may be applied here, on this panel, or via the same buttons on the top-line search input.

Values Boosting Panel

The Values Boosting panel allows you to boost values to affect the rankings of the results set. It will not act to do any filtering whatsoever; for that purpose, see the Attributes panel above. The values boosts work in conjunction with any other specifications that have been made above, namely simple or advanced search or attribute boosting or filtering.

Like the other panels, clicking on the Values Boosting panel causes it to expand; clicking on the expanded header causes it to collapse. Also, like all other panels, contextual help is provided via the icon button at the upper right of the panel. Here is the basic view of this panel:

Qb values boosting.png

The first combobox presented enables you to select which attribute you want to select for boosting values. The attributes themselves are of two types: There are free text entries and controlled vocabulary entries, with these icons appearing in the adjacent values dropdown combobox. For free text entries, any term or string may be entered into this box; for controlled vocabulary entries, you must pick from one of the available options, which are presented to you via a dropddown list, also shown with an autocompletion icon. Like other autocompletion fields, typing more characters causes the possible entries to be narrowed to those that match the string. A good attribute to try this feature with is Subject, since there is a long list of subjects within the available ontologies.

Once an attribute value is selected, it is then possible to indicate its relative weight in the results set ranking order. You do this by changing the value at the right of the entry line.

Note: by convention, all initial boost weights are set to 1.0. Thus, a value greater than 1.0 means the attribute is to be ranked higher; a value less than 1.0 means the attribute is to be ranked lower than standard.


Note: the actual algorithm to construct a "score" for a given result can be quite complicated in the search function. As a result, it is often hard to see a commensurate change in score via the boost, though a numeric impact will occur and rank order will most likely change.


The plus (+) button allows you to enter another filter or weighting boost. You may add as many of these filters as you wish.

For a given document or result to receive this scoring boost, it must both have the applicable attribute AND the specific value you specified. Without both of those conditions being met, the record receives no scoring boost and its overall score is unaffected. (However, its absolute rank order might be lowered if other records or documents receive the boost causing them to appear higher in the results listing.)

Note: to test the effect of boost differences, first run a search without boost and inspect the resulting search scores as described under Results Listing below. Then, run again with the boosts and inspect score and ranking differences.


At the bottom of the panel, a search may be invoked via the 'Search' button or all QB settings may be 'Clear' back to original settings. These buttons may be applied here, on this panel, or via the same buttons on the top-line search input.

Search Query Code Panel

The Search Query Code panel presents the internal query specification resulting from any of the prior search, dataset selection, filter selection or boosting factors. The code that is presented here may be copied by developers for Web page or layout template use. The code in this panel is also a good way to understand the various components in your queries.

Here is an example screen showing one of these code samples:

Qb search code.PNG

There are two sections available:

  1. OSF-WS-PHP-API Code
    1. This is the OSF-WS-PHP-API code that can be used to query the OSF instance using the Search web service endpoint
  2. Query's JSON Serialized Object
    1. This is an intermediary JSON object representation of the query. This is what is used to create the Search Profiles.

Search Profile

This section let you save the query you created as a OSF for Drupal Search Profile. The only thing you have to do is to define a name for that new search profile, and to click the Save Search Profile button. Once you saved a search profile, it will appears in the list of available search profiles (see below).

Qb search profile.PNG

Results Listing

The results listing appears at the bottom of the expand/collapse panels discussed above. The results listing is one of the major benefits of the query builder in that it provides the full structural detail for each result and also displays its internal search score, which is shown at the upper right of each individual result record.

Note: in an actual results presentation, these structured values may be included or not, snippets might be provided, titles could be made active links, images or maps could be displayed depending on the type of data, etc. The QB merely shows the component building blocks presently available in the datasets for such displays.


The results listing itself begins with a summary of the count for the results set produced by the various filters and query specifications in the query builder. These results are then paginated, in groups of ten, across potentially multiple results pages.

Note: when looking at scoring impacts from boosts, it is often helpful to compare the first and last pages of paginated results.


The basic appearance of the results listing, showing an example first result, appears as follows:

Qb search results.PNG

The results section begins with the standard help icon and the paginator, as well as showing the total number of results for the current query and datasets. Then, each results listing follows a similar display format.

The first line of every result shows the record's title (prefLabel), what type of record it is as shown in italicized parentheses, and its search score at far right. Then, all structured data and metadata are presented below, with the attribute name shown in bold followed by its value. Note that if you mouseover any bolded property label (such as prefLabel) you will see a tooltip showing you the actual URI value for that property.

Most values are string text, but some are URLs, in which case a live link is presented. Some of the attributes or properties, too, also have records within one of the governing ontologies. Subject is a useful property to inspect in this manner. These are shown as a live link as well; clicking on them will take you to a structured data listing.

Saving a Search Profile

To create a search profile, we have to generate the search query that will be used by it. As we saw in the previous sections, the query is created using the OSF Query Builder. Then you have to save it using that same Query Builder. Once the search profile is saved, it will appear in the list of available search profiles as we will discover in the section below.

Creating & Configuring a Search Profile Block

The see the list of all available search profile, you have to click the top menu item Configuration. Then you have the click the Search Profiles link under the Search and Metadata section.

Search profiles.PNG

The Search Profiles page does list all the search profiles you saved using the OSF Query Builder. From that page, you can create new search profiles using the + Create New Search Profile link. This link will redirect you to the OSF Query Builder page.

If you click the Edit link of one of the search profile, you will be be able to edit some information about that search profile.

Search profiles list.PNG

There are three main pieces of information in a search profile:

  1. Name
    1. This is the name of the search profile that appears in the Drupal user interfaces
  2. Description
    1. This is the description of the search profile
  3. Settings
    1. This is the JSON object of the Search query that as been generated by the Query Builder. You can change that query directly in that box. But take care of what you are doing since it could break the search query.
Search profiles edit.PNG

Positioning the Search Profile Block

Now that we have created a search profile, the last step is to add this search profile to a block, and then to position that block on the Drupal portal. To add a search profile as a block, you have to click the Structure top menu item. Then you have to click the Blocks link.

Manage blocks for search profiles.PNG

Then you have to click the + Add search profile. This will will redirect you to the page that you will use to configure how the search profile will be embeded in a new block.

List blocks.PNG

This page will let you create a new block that will embed a search profile. There are several settings that can be configured to make sure the search profile block behave as expected. Here are the different setting options that are available to you:

  1. Machine name
    1. This is unique Drupal identifier. It should be defined using alpha numeric characters and underscores
  2. Box description
    1. This is the description of the block that will be created
  3. Box title
    1. This is the title of the block that will be created
  4. Search Profile
    1. This is the search profile you want to embed in that block. The search profiles listed in that list are the ones that have been created and saved by the OSF QueryBuilder module
  5. Attempt to derive the query from page context
    1. If this option is checked, it means that the block will try to use the context where the block was positioned to generate the search keywords. Here are the steps that will be performed
      1. Will check if topics are related to the page where the block appears. Topics can be added using the hook_osf_searchprofiles_page_topics hook.
        1. If there are more than one topic, they will be ORed
      2. If no topics are found, then the title of the page will be used as the search keywords
  6. Search Profile Block Settings
    1. Number of items
      1. This is the number of results to return in the block
    2. Output type
      1. Two output types are possible:
        1. List of links
          1. With this option, the results will be displayed as a list of links within the block
        2. Fully themed search results
          1. With this option, the results will be fully themed search results. Also, if filter blocks are defined for the OSF Search API module, then they will appear in the page as well except if their blocks have been configured such that they doesn't appear on these specific pages
    3. Query
      1. This is an option search keyword that you can define for the query. This is optional and can remain blank
    4. Hide if empty
      1. Specifies if you want to hide the block if no results were found
  7. Region settings
    1. These are the block settings that let you position the block in the portal
  8. Visibility settings
    1. These are the normal block visibility settings that you can use to make the block visible in different places on the portal and to different users

Once you are done configuring the new search profile block, you can click the Save block button to save that new search profile block.

Add new search profile block.PNG

Then you will be redirected to the list of available blocks of the portal. You can position the new block using the positioning drop-down box.

Editing newly created search profile block.PNG

Once you positioned the block, it will re-appear in the section you selected. At that point, you have to make sure to save that new positioning by clicking the Save blocks button.

Position search profile block.PNG

Finally, if you got to a Drupal page where the block should appear, you will see it appearing and displaying the results of the search query:

Used search profile.PNG

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:

  • $resource
    • This is a StructuredDynamics\osf\framework\Resource class instance that can be used to manipulate the entity's content. The Resource class should be the first choice of the themers since it has been specifically created to make the templates easier to create, maintain and read.
  • $element or $entity
    • This is a ResourceType class instance. All the values of the properties follows the internal Drupal array structure conventions
  • $subject
    • This is a StructuredDynamics\osf\framework\Subject 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.

The main variables for a search template are:

  • $resource
  • $entity
  • $subject

Simple Template Using $resource

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 Entity 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:

  • Resource
  • Property
  • Value

The design of the API focus on these three classes. A Resource is an Entity description. It is composed of:

  • A unique identifier
  • One or multiple types
  • One or multiple Properties

Then a Property is composed of:

  • A unique identifier
  • A type, which is one of:
    • Datatype Property, or
    • Object Property
  • One or multiple Values

Then a Value is composed of:

  • A content (the actual value)
  • An optional language identifer (ISO 639)
  • An optional datatype
  • Optional reification statements (out of the scope of this documentation).

It is as simple as this: a Resource is described using multiple Properties and each of these properties can have one or multiple Values.

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.

Resource Class
Function Description Parameters Returns
uri() Get the full URI of the Resource None Return the full URI of this Resource
property($uri) Get a specific property and all its values
Parameter Description
$uri URI of the property to get. The full URI of the property can be used, or its "prefixed" (abridged) version. Such a prefixed version would be "foaf:name". See the section below that discuss abridged vs. unabridged URIs.
Return the Property instance with all its values. If the property is not existing, then an empty Property is returned. An empty property is a property with an empty URI and an empty set of values
properties() Get the list of all the properties defining this Resource None Return an array of Property() instances that define this Resource
type($id) Get a type of this resource
Parameter Description
$id ID of the type to return. The index start at 1, unlike arrays
Return the full URI of the type available for that index. NULL is returned if there is no type available for this index
types() Get the types of the Resource None Return an array of full URIs that refer to the types of this Resource
setLanguage($language) Specify the language to be used when the user get values from this Resource instance. If a language is specified, then all the functions that returns values will only return values of that language. If the specified language is NULL, then the values of all languages will be returned.

Note that the object properties are not affected by this setting.

Parameter Description
$language ISO 639 language tag
Return the Resource itself.

This means that this function can be chained with other function calls.

isLanguageStrict() Specify if the Resource is using the strict language mode None Return the Resource itself.

This means that this function can be chained with other function calls.

strictLanguage() Enables the strict language mode. If this mode is enabled, it means that only the values tagged with that language will be returned for the Datatype properties values. This means that all values that have a NULL (unspecified) language won't be returned by any functions that return values None Return the Resource itself.

This means that this function can be chained with other function calls.

looseLanguage() Enables the "loose language" mode. If this mode is enabled, it means that the values tagged with that language, and the values without any language defined for them (NULL) will be returned for the Datatype properties values.

This is the default behavior.

None Return the Resource itself.

This means that this function can be chained with other function calls.

Property Class
Function Description Parameters Returns
value($id) Return a value defined for a property. If a language is defined for the Resource then the index is the one of the sub-set of values that is composed of all the values of the language specified for the Resource.
Parameter Description
$id ID of the value to return.

The index start at 1, unlike arrays

Return a Value instance that represents that value. An empty Value instance will be returned if there is no Value for that index
values() Get all the values of that Property. If the property is a Datatype property and if a language is defined for the Resource, then all the values that will be returned are values that have this language None Return an array of Value instances. One for each value of that property
uri() Get the URI of this property None Return the full URI of that property
type() Get the type of tihs property. Can be DATATYPE_PROPERTY or OBJECT_PROPERTY None Return the type of the property. It can be de constant DATATYPE_PROPERTY or the constant OBJECT_PROPERTY
exists() Specify if there are values for that property. If the Resource has a specific language specified for it, and if this is a DATATYPE_PROPERTY then exists will return TRUE only if there is a value with that language None TRUE is there is at least a value for that property. Return FALSE otherwise.
Value Class
Function Description Parameters Returns
content() Get the actual value content of this Value None Return the value content of this Value
display() Display the value

The display is used using the "echo" language construct

None Nothing
language() Get the language of this Value None Return the ISO 639 language code of this value. If NULL is returned it means that no language is specified for this Value (so it is considered language neutral).
type() Get the URI of the datatype of the Value None Return the URI of the datatype of the value. If NULL is returned it means that no specific datatype has been defined for this value

Usage Recipes

This section outline a series of Resource API "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 Resources, Properties and Types. A URI is normally a standard URL, but it can be different. A full URI looks like this:

http://purl.org/ontology/iron#prefLabel

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 iron that stands for the partial URI http://purl.org/ontology/iron#. This means that the prefixed URI version of the full URI we defined above would be:

iron:prefLabel

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 osf_dpm_resource() 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 Resource is pretty easier, the only thing you have to do is to specify the full or the prefixed URI to get using the property() function:

<?
  $label = $resource->property('iron:prefLabel');
?>

Then $label 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 value() function of a Property:

<?
  $labelValue = $resource->property('iron:prefLabel')->value();
?>

If you don't specify any $id for the value() 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:

<?
  $label = $resource->property('iron:prefLabel');
  $labelValue = $label->value();
?>
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 content() function of a Value:

<?
  $actualLabel = $resource->property('iron:prefLabel')->value()->content();
?>

What this does is to return the actual value of the Value 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 display() function of a Value:

  <h2><? $resource->property('iron:prefLabel')->value()->display() ?></h2>

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:

<?
  // Declare all the properties I want to use in my template
  $label = $resource->property('iron:prefLabel')->value();


  // Then I get to the template's code...
?>

  <h2><? $label->display() ?></h2>
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:

<?
  $lat = $resource->property('geo:latitude');
  $long = $resource->property('geo:longitude');
?>


<? if($lat->exists() && $long->exists()) { ?>
  <script type="text/javascript">
    var latlng = new google.maps.LatLng("<? $lat->value->display() ?>", "<? $long->value->display() ?>");
    var myOptions = {zoom: 15,
                     center: latlng,
                     mapTypeId: google.maps.MapTypeId.ROADMAP};
                   
    var map = new google.maps.Map(document.getElementById("map_canvas_'.$id.'"), myOptions);
                   
    var marker = new google.maps.Marker({position: latlng,
                                         map: map});
  </script>
<? } ?>
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:

<?
  $altLabel = $resource->property('iron:altLabel');

  if($altLabel->exists)
  {
    ?>Alternative labels: <?
    foreach($altLabel->values() as $value)
    {
      ?> $value->display() <?
    }
  }  
?>
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 Value. 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 Resource by using the setLanguage() function call on the Resource. Then when you will use any other functions to get the values from that Resource, everything will be in French:

<?
  $resource->setLanguage('fr');
   
  foreach($resource->property('rdfs:label')->values() as $value)
  {
    // Display all the French values of that property
    // This will also display the values that have no language defined for them
    $value->display();
  }  
?>

Remember that by default, the loose language 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 strict language mode:

<?
  $resource->setLanguage('fr')
           ->strictLanguage();
   
  foreach($resource->property('rdfs:label')->values() as $value)
  {
    // Display all the French values of that property
    // This will also display the values that have no language defined for them
    $value->display();
  }  
?>
Working with Object Properties

As we discussed above, a Property can be a DATATYPE_PROPERTY or a OBJECT_PROPERTY. 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 foaf:knows that refer a person entity to another person entity:

<?
  $knows = $resource->property('foaf:knows');

  // Check if our Resource knows someone
  if($knows->exists())
  {
    ?><ul><?
    foreach($knows->values() as $know)
    {
      // Display the name of every person our Resource knows
     
      // First get the description of the entity he knows
      $knownEntity = osf_get_resource($know->content());
     
      // Then display the name of that person
      ?><li><? $knownEntity->property('iron:prefLabel')->value()->display() ?></li><?
    }
    ?></ul><?
  }
?>

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

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 Resource you are manipulating. A type or a property are Resources as well. What this means is that you can use the Resource API 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 Resource that you are templating, in parenthesis in the title of that Resource's page.

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

<?

  // Get the Resource object of the Type of the Resource of that page
  $typeResource = osf_get_resource($resource->type())

  // Then display its preferred label in parenthesis

?>

<h3><? $resource->property('iron:prefLabel')->value()->display() ?> (<? $typeResource->property('iron:prefLabel')->value()->display() ?>)</h3>

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 Resource API:

osf_get_resource($uri)

What the osf_get_resource($uri) 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:

<?
  $knows = $resource->property('foaf:knows');

  // Check if our Resource knows someone
  if($knows->exists())
  {
    ?><ul><?
    foreach($knows->values() as $know)
    {
      // Display the name of every person our Resource knows
     
      // First get the description of the entity he knows
      $knownEntity = osf_get_resource($know->content());
     
      // Then display the name of that person
      ?><li><? $knownEntity->property('iron:prefLabel')->value()->display() ?></li><?
    }
    ?></ul><?
  }
?>
osf_dpm_resource(Resource $resource)

The first thing a template designer has to do when he starts templating a new Entity is to check what are the properties/values available to him. What the osf_dpm_resource() function does is to output the structure of the Resource 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:

<?
  osf_dpm_resource($resource);
?>

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):

Osf dpm resource.PNG

As you can see, this debugging output will show you all the properties that are defining that Resource. 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.

Simple Template Using $entity

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

<?php
 
  echo '<h2>'.$entity->label.'</h2>';
 
  // Display alternative labels only if any are defined
  if(!empty($entity->iron_altlabel))
  {
    echo '<em>(';
   
    foreach(current($entity->iron_altlabel) as $altLabel)
    {
      echo $altLabel['value'].',';
    }
   
    echo '<em>)';
  }
 
  if(!empty($entity->foaf_homepage))
  {
    echo '<a href="'.current($entity->foaf_homepage)[0]['value'].'">Homepage</a>';
  }
 
  if(!empty($entity->foaf_topic))
  {
    echo '<h3>Topics</h3>';
    echo '<ul>';
   
    foreach(current($entity->foaf_topic) as $topic)
    {
      $topicURI = current($entity->foaf_topic)[0]['value'];
     
      // Get the label of the URI that is referenced by this property
      // using the entity_load() function call
      $topicEntity = entity_load('resource_type', array($topicURI));
     
      if(!empty($topicEntity))
      {
        $topicEntity = current($topicEntity);
       
        echo '<li>'.$topicEntity->obj->getPrefLabel().'</li>';
      }
    }
   
    echo '</ul>';
  }
 
?>

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

Osf simple template.PNG

Simple Template Using $subject

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

<?php
 
  use \StructuredDynamics\osf\framework\Namespaces;
 
  echo '<h2>'.$subject->getPrefLabel().'</h2>';
 
  // Display alternative labels only if any are defined
  if(count($subject->getAltLabels()) > 0)
  {
    echo '<em>(';
   
    foreach($subject->getAltLabels() as $altLabel)
    {
      echo $altLabel.',';
    }
   
    echo '<em>)';
  }
 
  $homepages = $subject->getDataPropertyValues(Namespaces::$foaf.'homepage');
  if(!empty($homepages))
  {
    echo '<a href="'.$homepages[0]['value'].'">Homepage</a>';
  }
 
  $topics = $subject->getDataPropertyValues(Namespaces::$foaf.'topic');
  if(!empty($topics))
  {
    echo '<h3>Topics</h3>';
    echo '<ul>';
   
    foreach($topics as $topic)
    {
      // Get the label of the URI that is referenced by this property
      // using the entity_load() function call
      $topicEntity = entity_load('resource_type', array($topic['uri']));
     
      if(!empty($topicEntity))
      {
        $topicEntity = current($topicEntity);
       
        echo '<li>'.$topicEntity->obj->getPrefLabel().'</li>';
      }
    }
   
    echo '</ul>';
  }
 
?>

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:

  Array(
    Array(
      "value" => "some value",
      "lang" => "language string of the value",
      "type" => "type of the value"
      "reify" => Array(
         "reification-attribute-uri" => Array("value of the reification statement"),
         "more-reification-attribute-uri" => ...
       ),
    ),
    Array(
      ...
    )
  )
$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:

  Array(
    Array(
      "uri" => "some uri",
      "type" => "optional type of the referenced URI",
      "reify" => Array(
        "reification-attribute-uri" => Array("value of the reification statement"),
        "more-reification-attribute-uri" => ...
      ),
    ),
  )
$subject->getPrefLabel($force = TRUE)

Get the preferred label of this subject

Can force a preferred to be returned. If the $force parameter is TRUE (default) then in the worsecase, getPrefLabel() 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 $force 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:

  • owl:Thing
    • foaf:Agent
      • foaf:Person
        • foo:PersonByOccupationArtist
        • foo:PersonByOccupationDoctor
      • foaf:Organization

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

  • /templates/resource_type.tpl.php
  • /templates/resource_type__foaf_person.tpl.php

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
    1. If a template exists, then the system will select it to theme the content of that entity. The selection process stops there
  3. 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
    1. If a template exists, then the system will select it to theme the content of that entity. The selection process stops there
  4. In the case that no template exists, then the default [generic] resource_type.tpl.php 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:

  • owl:Thing [resource_type.tpl.php]
    • foaf:Agent [resource_type.tpl.php]
      • foaf:Person [resource_type__foaf_person.tpl.php]
        • foo:PersonByOccupationArtist [resource_type__foaf_person.tpl.php]
        • foo:PersonByOccupationDoctor [resource_type__foaf_person.tpl.php]
      • foaf:Organization [resource_type.tpl.php]

A Few Templates Examples

First Example: foaf:Organization

Now let's assume that a user is accessing an entity page of type foaf:Organization. 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 resource_type.tpl.php 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 owl:Thing.

Second Example: foaf:Person

Now let's assume that a user is accessing an entity page of type foaf:Person. 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 resource_type__foaf_person.tpl.php template will be used because there exists a template for the foaf:Person class.

Third eExample: foo:PersonByOccupationArtist

Now let's assume that a user is accessing an entity page of type foaf:PersonByOccupationArtist. 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 resource_type__foaf_person.tpl.php template will be used because there exists a template for a parent class: foaf:Person.

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:

  • /modules/osf/modules/osf_entities/
  • [default-theme-folder]/templates/

The name of the template file should follow the following specifications:

  • The name of the file as to be lowercase
  • It should start with the string: resource_type
  • 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: prefix_
  • It should be followed by the type of the resource: type
  • Finally it should ends with: .tpl.php

Here are a few examples of such template names:

  • resource_type__foaf_person.tpl.php
  • resource_type__owl_thing.tpl.php
  • resource_type__foo_personbyoccupationartist.tpl.php
Note: Every time you add or remove a template, you have to clear the Drupal cache in order to take the modifications into account.


Note 2: You *have to make sure* that the base URI of the class you are templating does have a prefix in the list of namespaces/prefixes.


Theming OSF SearchAPI Results

Screencast Tutorial

0.jpg

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:

  • /modules/osf/modules/osf_entities/
  • [default-theme-folder]/templates/

The name of the template file should follow the following specifications:

  • The name of the file as to be lowercase
  • It should start with the string: resource_type
  • 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: prefix_
  • It should be followed by the type of the resource: type
  • It should be followed by: __search
  • Finally it should ends with: .tpl.php

Here are a few examples of such template names:

  • resource_type__foaf_person__search.tpl.php
  • resource_type__owl_thing__search.tpl.php
  • resource_type__foo_personbyoccupationartist__search.tpl.php
Note: Every time you add or remove a template, you have to clear the Drupal cache in order to take the modifications into account.


Note 2: You *have to make sure* that the base URI of the class you are templating does have a prefix in the list of namespaces/prefixes.


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.

Note: Every time you add or remove a template, you have to clear the Drupal cache in order to take the modifications into account.


Note 2: You *have to make sure* that the base URI of the class you are templating does have a prefix in the list of namespaces/prefixes.


External Drupal Theming Resources

Managing Ontologies

Configuring OSF Ontology

To configure OSF Ontology, you have to do is to click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Then click the the ONTOLOGY tab.

Osf ontology configure.PNG

Multiple configuration options can be configured on this page:

  1. Read mode
    1. Read mode
      1. This option force the read mode of the ontology management tool. All users, including system administrator will only be able to read and export ontologies from this user interface. All the administrative tasks, such as creating, deleting, saving, etc. ontologies will be done using the Ontologies Management Tool command line utility.
  2. General
    1. Enable ontology reasoner by default
      1. This will enable the reasoner by default when a OSF Ontology view page is being opened by a user.
    2. Enable ontology search
      1. This will enable the search feature embedded into the OSF Ontology module. If this option is unchecked, all the search options will be disabled in the module.
    3. Enable ontology export
      1. This will enable the export feature embedded into the OSF Ontology module. If this option is unchecked, the export button won't be displayed to the users.
  3. Ontologies files
    1. Ontologies Files Path folder
      1. This is the path of the folder where ontologies files get saved on the server.
    2. Ontologies Cache Path folder
      1. This is the path of the folder where ontologies cache files get saved on the server. This is used to to save the cache of the ontologies. These caches are used by OSF for Drupal and OSF.
    3. Ontologies ironXML Schema Cache Path folder
      1. This is the path of the folder where ironXML Schemas cache files get saved on the server. This is used to to save the cache of the ontologies in ironXML schemas. These caches are mainly used by the OSF widgets. This folder should be accessible on the web so that any OSF widget has access to them.
    4. Ontologies ironJSON Schema Cache Path folder
      1. This is the path of the folder where ironJSON Schemas cache files get saved on the server. This is used to to save the cache of the ontologies in ironJSON schemas. These caches are normally used by some JavaScript applications. This folder should be accessible on the web so that any applications that uses these JSON schemas has access to them.
Note about Ontologies Files: The ontologies files and paths settings are used in a OSF (Open Semantic Framework) single server instance. These paths tells the OSF Ontology module where to save, load ontologies and where to generate sub-structures. These need to be properly configured when you want to use OSF Ontology to administer ontologies on your server.

Using OSF Ontology

To access the OSF Ontology tool, click the top Ontologies menu item.

Osf ontologies menu.PNG


All of these functions are not available to all users, except viewing available ontologies (if settings allow so). Most options require being at least at a 'curator' or 'admin' level.



Screencast Tutorial

0.jpg

Create, modify, annotate or delete actions on ontologies are the most privileged functions within the system. As a result, most all ontology actions are accessed (if permissions exist) through the broad Ontology tool Ontology icon from the main tools listing, or from privileged positions on a few other screens.

Main Screen

Upon access, you are presented with the main OSF Ontology interface:

StructOntology main.png

The organization of the OSF Ontology application presents all currently available and active ontologies listed in the left panel. These are organized into three categories:

  • Local Ontologies - these are the domain ontologies governing the use of your specific portal. They generally contain the specific "world view" and content organization specific to your problem or domain. Most (but not necessarily all) of your editing and modifications will occur in this section. This is also the basis for the screen examples below
  • Reference Ontologies - these, too, are content ontologies, but generally represent external ontologies that you are re-using in your specific portal for interoperability or sharing purposes
  • Administrative Ontologies - these are internal ontologies that guide and govern the use of widgets, permissions, components and other administrative functions of your site. Most site administrators will have little or no reason to make any changes to ontologies in this category.

The currently active ontology is picked by selecting one of the radio buttons, in which case the selection is highlighted (orange/brown in this example). The active ontology is what is subject to the various button options to the right of the display.

Also, note the Ontology icon StructOntology.png; when selected for any of the ontologies listed, it enables you to update and change that ontology's metadata:

StructOntology metadata.png

Via this choice, you may change the title, description or ontology type (for the listing on the main page). If you need to make more nuanced annotations (such as version number, etc.), you will need to use a third-party ontology editor such as Protégé.

From the main screen you may also search the Active or All ontologies (described further below).

The main screen also offers various user or admin functions, as shown by the button options at the right of the display. Each of these options is described in detail below.

Finally, note that your interaction with the OSF Ontology application is recounted via the "breadcrumbs" listing at the upper left of the application.

View/Annotate Option

The View/Annotate option under the right User/Admin panel is the key one in the application. As such, we will give this option more attention than the others.

Upon invoking the View option, the hierarchical tree for the selected ontology appears on the left; structural and definitions on the right. As we will see, sub-sections below describe this right-hand panel in more detail, since it is the location for most activity and use in the OSF Ontology application:

StructOntology view.png

Later sections describe the various section in the right-hand panels in more detail.

Searching

Searching can take place on the currently active ontology or all loaded (available) ontologies. Note that selection was made above via the radiobutton under the search box.

Also, depending on settings, searching can also take place on only the preferred label, or on alternative labels or descriptions (in fact, all annotations). (This is part of the settings.)

When entering search terms, the system automatically attempts to complete the matching search phrase. A minimum of three entered characters guides this auto-completion functionality:

StructOntology autocomplete.png

When search is initiated, the potential results list also auto-completes for what you have already typed into the search box. Upon selection of one of these items (or completion of the full search phrase), the OSF Ontology system issues a search query to the remote server, which then acts to auto-populate the ontology tree on the left-hand panel. In this case, we have selected 'communitiy facilities':

StructOntology tree results.png

The desired search results then automatically expand the ontology tree. This is really helpful for longer ontologies (the example one shown has about 3000 concepts and about 6000 axioms) and means quicker initial tree loading.

Once completed, the (multiple) occurrences of the search item are shown in highlight throughout the tree.

Note this search is not necessarily restricted to the actual node label. Alternative labels and descriptions may also be used to find the search results. This greatly expands the findability of the search function.

Advanced Searching

OSF Ontology also offers advanced searching, available from the main screen link (actually, as auto-complete works, this link gets hidden):

StructOntology advanced search.png

This functionality is identical to the standard advanced search functionality. See that document for detailed guidance on its filtered search and auto-completion aspects.

Contextual Drag-and-Drop

It is possible to drag items from the left-hand tree panel into the specifications at the right. This is contextual. In this first example, we see an attempt to drop a "class" result (or concept) into the annotation panel, which violates the structure of the system and is therefore not allowed (as shown by the visual red X cues):

StructOntology dragdrop no.png

However, if we drag and drop from the tree in an allowable structural definition, we get the visual green check as a cue the move is legal:

StructOntology dragdrop yes.png

This functionality and feedback means that only allowable assignments can be dropped into a new structural definition.

Tooltips

The tree labels are themselves based on the preferred labels assigned to things. However, if you want to see the actual ontology URI reference, you can do so via the tooltip when mousing over the item:

StructOntology tooltips.png

The tooltip shows the full URI path (unique identifier) of the selected item.

General Operations

These operations all tend to apply to the Classes, Properties and Individuals tabs. Please refer to this section for general use tips.

Note: as you work with ANY tab or individual selection from the left-hand list for that tab, you MUST Save you changes before proceeding to another item or tab. If you move away from the current view, your modifications will be lost if you have not Saved.

Each panel has an expand Arrow down.png and collapse arrow Arrow up.png shown at the upper right of its panel. These causes the panel's individual entries to either be exposed or hidden.

At the right of each entry, new entries can be invoked with the green plus symbol Bullet add.png; existing entries can be deleted with the red minus symbol Bullet delete.png. (See Structural Relationships below.)

Further, some of the fields feature auto-completion, which means there is a URI designation for the field entry, drawn from existing objects in the various ontologies. If applicable, the entry field will include either this spinning symbol Spinning-circle.gif or an alternate designator Green-gear.png. When encountered, you trigger the auto-completion list by entering a minimum of three characters. Then, you must pick one of the entries from the dropdown list. It will then populate the entry field.

In working with each panel, note that each entry also has the search and auto-complete features earlier noted. Drag-and-drop is also contextual into these panels or not, depending on the nature of the item selected in the left-hand panel (tree).

Classes Tab

With this basic overview of the operation and layout of OSF Ontology, we are now ready to focus on the items in the right-hand panel. Again, we are using the main View option.

These right-hand panels include separate sections for:

  • Annotations
  • Structural relationships
  • Instances
  • Linkage to characteristics, and
  • Advanced settings.

Each of these is discussed in turn.

Annotations

Annotations provide the descriptions about the thing at hand and its associated metadata. (These are separately defined under the Properties tab -- see below -- or are as part of the imported ontology specification.)

The available annotations are displayed in this panel when expanded:

StructOntology annotations.png

Entries are simply provided by entering values into the text fields and then Saving.

Structural Relationships

The structural relationships are the means to set parent and child relations between concepts, as well as to instruct disjoint or equivalent class relations. The Structural Relationships panel is the key one for setting the interconnections within the graph structure at the heart of the governing ontology.

StructOntology structure.png

Most of the key structural relationships in OWL are provided by this panel. (However, note there are some additional and rarely used structural specifications in OWL. These must be set via a third-party external application. Such potential interactions are made possible via the flexible import and export options with OSF Ontology -- see further below.)

Instances (Individuals)

Another right-hand panel provides the facility to assign individuals to the classes (or concepts) established under the prior two panels. (These can also be handled directly via the Individuals tab; see below.) In this case, we are looking at some specific 'community facilities' to assign to that concept:

StructOntology instances.png

As with the prior panels, new instance may be added or discarded ones deleted. Individual instances and their characteristics may also be updated or changes.

Linkage to Characteristics

Another aspect to OSF ontologies is the ability to relate concepts to various metadata characteristics or attributes that might describe that concept's instances. This relationship is done via the dedicates hasCharacteristic property, which is assigned via this right-hand panel:

StructOntology characteristics.png

This option has the specific behavior of allowing one or more properties (characteristics) to be asserted for a given a class (concept).

Advanced Options

Display and widget and other options are set under the Advanced Options panel. One item to note are the widgets that may be assigned for displaying a given information item:

StructOntology advanced.png

The relationship of widgets to information items is a deserving topic in its own right. For more information about this topic, see the OSF widgets category, especially regarding the SCO Ontology.

Properties Tab

Properties -- that is the relations or predicates between items or nodes -- are established in a similar manner to that for Classes. To add a new property or modify an existing one, pick the Properties tab in the left-hand portion of OSF Ontology:

StructOntology properties.png

Note the Properties tab has the same basic layout and operations as the Classes tab, including similar right-hand panels such as annotations or structure.

A key difference is the ability to set domains for properties. When set, this constrains the property to be only applicable to a certain class of nodes as the specifying subject.

Individuals Tab

Individuals are the instance members of classes.

StructOntology individuals.png

Note the Individuals tab has the same basic layout and operations as the Classes tab, including similar right-hand panels such as annotations or structure.

Key uses of this tab are to provide the data and display definitions for specific individuals and indicators. For more information about some of these settings, see the OSF widgets category, especially regarding the SCO Ontology.

Export Option

We are now ready to look at the non-View options in OSF Ontology.

The first of these is the Export button. When invoked, it brings up the save dialog with the ability to assign an ontology file name:

StructOntology export.png

Upon saving, it stores the currently active ontology in RDF/XML format:

StructOntology export xml.png

This file can now be used in an external ontology editor (such as Protégé) or edited directly with a text editor. After those changes are made, generally useful when bulk changes are desired, the updated file can be imported back into the system; see Import below.

Create Option

At all times OSF Ontology also allows you to create a new ontology:

StructOntology create new.png

The URL (such as http://purl.org/ontology/myont#) becomes the base URI for your new ontology.

The new ontology is created with a basic structure, from which you only need fill in your new concepts or classes and relationships:

StructOntology create new list.png


Note: there is a file on your standard OSF install -- /data/ontologies/files/mew.owl -- that contains the starting basis for this initial ontology framework. Should you wish to create ontologies with a different starting structure, modify this file and save it under the same name. It will then become the starting basis for new created ontologies.

As new items are entered with their relationships, the basic ontology tree also expands and grows:

StructOntology create new tree.png

Once created, this new ontology also now appears on your available local ontologies when first invoking the OSF Ontology application.

Save Option

The Save option saves all modifications on the file, on the server. If you have made local changes that have NOT been saved, your ontology will be annotated on the main screen as shown with the phrase '(modified; not saved)':

StructOntology modified.png

You are advised to Save prior to all export or Generate All options.

Delete Option

The Delete option removes the currently active ontology from your local instance AND from your server hosting the instance. Therefore, use with caution.

Note: as an alternative to Delete you may use the Reload All option to wipe out any local, unsaved options and to restore the starting versions located on your server instance. See below.

Like other options, you invoke Delete from the right-hand options buttons:

StructOntology delete.png

Prior to actual deletion, you are prompted if you want to proceed:

StructOntology delete confirm.png

The Delete option removes the server version. This is the most drastic option since removal means no local instances may again access or use that ontology.

Warning: deletions may NOT be undone. Make sure you keep backups on occasion using the Export option in case you make a deletion mistake !!!

Import Option

OSF Ontology supports all OWL API serializations, specifically RDF/XML, N3, Manchester Syntax, Turtle. When import is invoked, a file open dialog is presented that enables you to find the ontology on your local hard drive:

StructOntology import.png

The Import feature has no file extension limitations; make care to pick and assign the proper types for importation.

Via the Import and Export buttons, it is possible to work locally with OSF Ontology while exporting to more capable third-party tools. Then, once use of those tools is complete, Import provides the ability to re-import the updated ontology back into the local collection.

Note: you are advised to use the inference option at time of import, even though it takes a bit more time to load, since it will build the forward-chain of inferences useful to your system.

Generate All Option

The Generate All option recreates the serializations files created from these ontologies, like the .SRZ files used by OSF Web Service and OSF-Drupal; the ironXML schema used by the OSF widgets, etc. To learn more about these structures, see the Internally Generated Schema document.

The Generate All option should be invoked any time you have made more than minor changes to your underlying ontologies. Frequently, if you have made changes and you do not see them reflected in your portal tools or interfaces, it is because you have neglected to update these structures.

Note: the Generate All option takes quite a bit of time to complete, though it does run in background. It is not unusual for this operation to take 30 min or more. You may work with other aspects of the site, it is just that updates will not be fully reflected until this generation step is complete.

To invoke Generate All, you pick that option from the right-hand buttons listing:

StructOntology update.png

There is a confirmation message presented when the update is successful.

Reload All Option

The Reload All option replaces all ontologies on your local instance with those on the server. So long as you have not done any Saving during your current session, invoking this option is akin to starting over with the same conditions at the start of your session.

Saving Local Content

Introduction

Screencast Tutorial

0.jpg

In Drupal, Content Type entities are by default saved into the default field storage system, which is MySQL. This is what we call "local content". This type of content is "local" to Drupal.

What this page will show, is that it is possible to save the values of some of the [local] Content Types directly into OSF instead of Drupal. This magic is performed by the OSF FieldStorage module which creates a new FieldStorageAPI for Drupal. What this module does is to create a new kind of storage (OSF) to save the values of some of the fields (the ones that have been created using that new storage system).

What that means is that for the same Content Type entity, you may have 2 of its fields that are saved in Drupal (MySQL) and 4 of its other fields saved into OSF. Or you could have all of them in MySQL, or all of them in OSF. Everything depends on how you configure the Content Type entities.

You can read more about the internal mechanism of the OSF Field Storage module by reading the Single Authoring Environment: the OSF FieldStorage Connector page.

Configuring OSF FieldStorage

Before configuring any Content Type entity using the new osf_fieldstorage system we have to configure a few settings in the OSF FieldStorage module. To access these settings, click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Then click the Local Storage tab. Now you will see all the configuration options.

Field storage config.PNG
  • Content Type Default Field Storage System
    • Change the default storage system of the Content Types to use the osf_fieldstorage system by default instead. By selecting this option, all the future field that will be created for the Content Types will be using a OSF instance as field data storage system. This means that the field_sql_storage storage system won't be available anymore when you will be managing your fields.
  • Field RDF Mapping
    • By default, only the field that uses the osf_fieldstorage field storage system will appear in the list of fields to be mapped in RDF under the RDF MAPPING tab. This means that only the mapped fields will be saved into the OSF instance. By enabling this option, you will see all the fields, whatever the field storage system they are using to be mapped in RDF. All the mapped fields will be saved into the OSF. This option could be used when synchronizing existing content on a Drupal instance that is no in OSF but that needs to be there.
  • Local Storage Content Dataset
    • Select the dataset you want to use to save all the local content you are creating from this Drupal instance. The local content is all the Content Types such as the Nodes, Articles, Pages, etc.
Note: It is essential that you select a dataset where to save the local content (the Content Type entities). If none are selected, no information will be saved for the osf_fieldstorage fields.


Configuring Drupal Content Type

Now that the OSF FieldStorage is properly configured, the next step is to configure existing, or new, Content Type entities to use the new osf_fieldstorage system.

To access the Content Types, you have to click the Structure top menu, and then click on the Content types link.

Field storage structure.PNG

What you get is the list of Content Types currently defined in your Drupal portal. From there, you can manage the ones that are created, or create new ones.

The option that particularly interest us is to manage the fields of a Content Type to choose the fields that will be used to describe one of these entity, and more particularly, which FieldStorage system it should be using.

Click the manage fields link to start managing the fields of a Content Type.

Field storage content types.PNG

In the manage fields section of a Content Type, you can see all the fields that are defined for a given Content Type. You can add, remove or edit fields as required. Each field is associated with a field widget. That field widget is a tool that will help the user to find or describe the right value for a field.

Field storage manage fields.PNG

The user interface of the original Content Type manage fields section only slightly changed compared to what you may be familiar with. The changes are:

  • A new Storage Type columns where you can see the FieldStorage type used by the field
  • A new Add new field (using osf_fieldstorage) used to creae a new field that uses the osf_fieldstorage type

With this new user interface in place, you can create a new field that uses the osf_fieldstorage type, or the default field_sql_storage type.

If you want to change the storage type of an existing field, you have no other choices than deleting it and re-creating it with the new type.

Note: If you delete a field_sql_storage field, you will loose all the information associated to it. You should synchronize its information in OSF before deleting it.


Field storage manage fields storage type.PNG

If you want to create a new field that uses the osf_fieldstorage field, then you have to define a name for it, then to select a field type and a field widget. None of this is different than what you were used to with the normal Content Type user interface.

The list of supported Field Type and Wiget is:


Field Type Field Widget Widget Example
Text Text Field
Img 5.PNG
OSF Entity Reference
Img 20.PNG
OSF Concept Reference (Tagging)
Img 19.PNG
Long text and summary Text area with a summary
Img 17.PNG
Long text Text area (multiple rows)
Img 19.PNG
List (text) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
List (integer) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
List (float) Select list
Img 16.PNG
Check boxes/radio buttons
Img 15.PNG
Link Link
Img 14.PNG
Integer Text field
Img 5.PNG
Float Text field
Img 5.PNG
Image Image
Img 13.PNG
File File
Img 10.PNG
Entity Reference Select list
Img 7.PNG
Check boxes/radio buttons
Img 6.PNG
Autocomplete
Img 8.PNG
Autocomplete (Tags style)
Img 8.PNG
Decimal Text field
Img 5.PNG
Date (Unix timestamp) Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Date (ISO format) Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Date Text field
Img 3.PNG
Select list
Img 4.PNG
Pop-up calendar
Boolean Check boxes/radio buttons
Img 2.PNG
Single on/off checkbox
Img 1.PNG
Geolocation Latitude/Longitude
Img 11.PNG
Google Map
Img 12.PNG

When you will click the Save button, you will be redirected to more configuration pages depending which field type and field widget you selected.

Field storage manage adding osf field.PNG

When the new field is created, you will see it appearing in the list of fields with the storage type you selected at the beginning.

Field storage manage field added.PNG

The next essential step is to map the newly created field to a RDF property. It is this mapping that will tell the system how to save the field's information into OSF in RDF. To manage this mapping you should click on the RDF MAPPINGS tab. This section will show you two things:

  1. The type of the content type
  2. All the fields of the content type

Then for each of these things, you will be able to define how it should be mapped in RDF.

If you do not select a type for the content type, then the default internal Drupal mapping will be used, which is sioc:Item. Then you have to map all the fields to different properties that are currently defined in loaded ontologies.

Note: If you do not map a field to a RDF property after you created it, nothing will be saved in OSF. So it is really important to map the new field to a RDF property.


Once you are done mapping the fields, you can click the Save mappings button to save the mapping.

Field storage manage new field rdf mapping.PNG

Creating/Editing Content Type Record

Once you are done with all these steps, you can to do edit an existing Content Type record, or to create a new one and save it. Depending on the field type you choose, the information will be saved in OSF or in MySQL (or any other possible FieldStorage type).

Field storage manage edit content type record.PNG

Using OSF FieldStorage to Synchronize Existing Drupal Local Content to OSF

Sometimes there are situation where you would like to have all your local content type pages be saved into a OSF instance. This section gives you all the steps required to take an existing Drupal portal's content and to synchronize/export it into a OSF instance. This process is particularly helpful if you already have an existing site with dozens of content types and thousands of pages that you want to start managing on OSF (along with other content assets). The procedure explained here can be helpful for other usecases. For example, we already used to to migrate a OSF version 1.1 environment into a OSF 3.0 one. All the local content needed to be part of the new OSF 3.0 instance, and this method has been utilized.

Normally there are at least two reasons why we want to synchronize Drupal local content types into OSF:

  1. Because you want to stop using the FieldStorage, and want to manage all this content directly into OSF using the Entity API
  2. Because you want your local content be searchable with all the other OSF dataset assests via the OSF SearchAPI module

In any case, it is the same procedure that should be utilized.

Configuring the Local Content Synchronization Process

The first thing you have to do before performing the synchronization process is to map all the fields of the content type you want to synchronize in OSF to the classes and properties that you want to use for saving the information in OSF. To perform this mapping, you have to click on the RDF MAPPINGS tab. Then you have to make sure that all the types and properties you want to save in OSF are properly mapped:

Fieldstorage sync 2.PNG

Take note: if you didn't enable the All fields can be mapped into RDF and saved into OSF option in the OSF FieldStorage options, then you will only see the fields that uses the osf_fieldstorage field storage type. If you want to map osf_fieldstorage and field_sql_storage types, then you have to select that option, save it, and then go back to the RDF MAPPINGS tab to do the mappping of these non-osf_fieldstorage fields.

You also have to specify the dataset that will contain all the synchronized local data content. All the synchronized local content will be saved into that single dataset.

Fieldstorage sync 6.PNG

Once the mapping is complete, you have to make sure that you have at least one field that uses the osf_fieldstorage field storage type. It is necessary to have at least one to see the SYNCHRONIZE tab appearing. If you don't need any, then what you should do is to create a dummy field that uses the osf_fieldstorage type and hide it to the users afterward.

Fieldstorage sync 1.PNG

Once everything is properly configured, and that you can see and click the SYNCHRONIZE tab, then you are ready to start the synchronization process. It is as simple as clicking the Synchronize Content Type button.

Fieldstorage sync 3.PNG

Once you clicked the button, you will get into the synchronization process. All the local content will be synchronized into OSF using that process.

Fieldstorage sync 4.PNG

Then when the process ends, you will get a report that everything did go fine, with the number of pages processed.

Fieldstorage sync 5.PNG


At that point, all the data is saved into the local content dataset.

Using OSF Field Widgets

OSF Entity Reference Field Widget

The OSF Entity Reference and the field widget is a specialized field widget that is used to reference OSF entities one between the other. It let users searching for the entities they want to reference. Then it presents the referenced entities in a series of blue boxes below the entities search bar.

Configuring the OSF Entity Reference Field Widget

To configure the field, you have to click the edit link in the list of fields to manage for an existing content type, or an existing resource type.

Osf field 1.PNG

After clicking the link, you will be redirected to the list of configuration options that are available for this field widget. The first setting that is of interest to us is the Datasets to use when searching for an entity to reference option. In that section, you will have a list of all the datasets currently available to you. Then you will have to select all the datasets that you want to make available to the field widget. This means that if you select the datasets A and B, then when the user will try to reference entities using that field widget, he will only search for entities within the datasets A and B.

Additionally you can do that on the list of loaded ontologies in the Drupal portal.

Osf field 2.PNG

The second setting of interest is the Filter setting. This is a convenient setting that you can use to specify the type of the entities to return when the user is searching for resources to refer to.

The third setting that is of interest is the Number of values setting. This setting restrain the number of values (references) that a user can define for that field.

Finally, when you are done configuring the field widget, you have to click the Save settings button to save the settings you just configured.

Osf field 3.PNG

Using the OSF Entity Field Widget

Once the OSF Entity Field Widget is configured, you can start using it by editing one of your content type or resource type entity. The field widget looks like this:

Osf field 4.PNG

You have 2 main sections with this widget:

  1. The top edit box section that is an autocompletion field what will let you find the entity you want to refer to. Once you start typing a single character, you will start seeing entities results appearing. The search is done on the preferred label of the entities (their names)
  2. The bottom section lists all the entities that have been selected using that field widget. All the blue boxes that are checked will be saved in the system. If an entity is unchecked, then it will appear in yellow and it won't be saved into the system.

OSF Concept Reference (Tagging) Field Widget

The OSF Concept Reference (Tagging) and the field widget is a specialized field widget that is used to reference OSF entities to ontological concepts (so classes defined in loaded ontologies in the Drupal portal). This field widget is normally used for tagging purposes: tagging entities with subject concepts. This field has three ways to let the user tag the entity:

  1. It gives the possibility to the user to search the concept to use as a tag
  2. It gives the possibility to the user to automatically tag the entity using the Scones web service endpoint
  3. It gives the possibility to the user to browse the loaded ontologies and select a class directly from OSF Ontology (the ontology browser)

Configuring the OSF Concept Reference (tagging) Field Widget

To configure the field, you have to click the edit link in the list of fields to manage for an existing content type, or an existing resource type.

Osf field 5.PNG

After clicking the link, you will be redirected to the list of configuration options that are available for this field widget.

The first setting is the Fields to include in SCONES lookup option. This setting let you specify the unstructured text fields that is defined for the entity that uses this field widget that should be used for automatically tagging the entity using the Scones web service endpoint. It is the text values of this/these fields that will be sent to scones.

The second setting is the Max number of suggestions option. This setting let you specify the maximum number of suggestions returned by Scones.

The third setting that is of interest to us is the Ontologies datasets to use when searching for a concept to add option. In that section, you will have a list of all the loaded ontologies currently available to you. Then you will have to select all the ontologies that you want to make available to the field widget. This means that if you select the ontologies A and B, then when the user will try to reference entities using that field widget, he will only search for classes concepts within the ontologies A and B.

Osf field 6.PNG

The fourth setting of interest is the Number of values setting. This setting restrain the number of values (references) that a user can define for that field.

Finally, when you are done configuring the field widget, you have to click the Save settings button to save the settings you just configured.

Osf field 7.PNG

Using the OSF Concept Reference (tagging) Field Widget

Once the OSF Concept Reference (tagging) is configured, you can start using it by editing one of your content type or resource type entity. The field widget looks like this:

Osf field 8.PNG

You have 3 main sections with this widget:

  1. The top Browse & add and Recommend from SCONES links.
  2. The top edit box section that is an autocompletion field what will let you find the entity you want to refer to. Once you start typing a single character, you will start seeing classes results appearing. The search is done on the preferred label of the classes (their names)
  3. The bottom section lists all the classes that have been selected using that field widget. All the blue boxes that are checked will be saved in the system. If a class is unchecked, then it will appear in yellow and it won't be saved into the system.

If the user clicks on the Browse & add button, then the OSF Ontology module (the ontologies browser) will appear in a contextual popup window. The the user will be able to select an ontology and then search the class he wants to add into the field type. Once the user found the class to add, he will be able to add it to the field using the Add to node button.

Osf field 9.PNG

Finally if the user clicks on the Recommend from SCONES link, then a query will be sent in background to the Scones web service endpoint, and will add all the suggestions by the endpoint. Then, the user will have to possibility to unselect some of the results returned by scones before saving the entity.

Using Multiple Languages

Setup a Multilingual Drupal Site

The first step for having a multilingual OSF for Drupal site, is to setup the multilingual modules of Drupal. Once Drupal is properly configured as a Drupal multilingual site, then you will be able to use the multilingual capabilities of different OSF for Drupal modules.

In this section, we will cover all the steps to perform to setup the baseline required to have enable the multilingual support of the OSF for Drupal modules.

One of the core set of Drupal Multilingual tutorials has been written by Gábor Hojtsy and is available here.

Enable the Local Module

The first step is to enable the Local module. This module is part of Drupal Core:

Multilingual 1.PNG

Once you checked the checkbox, save the modules settings.

Enable a New Language

The next step is to enable a new language in the Local settings. Go to the Regional and Language settings, and click the Languages link.

Multilingual 2.PNG

Then click the Add langauge link to add a new language that you would like to handle in your OSF for Drupal portal.

Important Note: make sure that the language you are adding in Drupal is supported by OSF. You should read the Multilinguality Capabilities of OSF documentation before continuing with this tutorial.


Multilingual 3.PNG

Once you click the Save configuration button, your Drupal instance will now be aware of the new language you just configured.

Update Language

Now that you handle a new language in Drupal, the next step will be to update the language packages available for this language. The first thing you have to do is to download the l10n_update Drupal module, and to enable it.

Once this module is enabled, you will go to the Configurations, and then click the Translate interface link.

Multilingual 4.PNG

Then you will click the Update tab.

Multilingual 5.PNG

What this section does is to help you adding and updating the language packages of all the modules you currently have on your Drupal instance, with the languages you selected previously. There you will have to choose update options that best fits you needs, and click the Update translations button.

Setup Language Detection

The next step is to choose how you want Drupal to detect the language to use to display the content into generated Drupal pages. There are multiple options to do that. Go to the Languages configuration section:

Multilingual 2.PNG

Then click the DETECT AND SELECTION tab:

Multilingual 6.PNG

Finally choose the mechanism you want to use to do this detection.

Install and Enable the i18n Module

The next step is to download and enable the i18n (internationalization) module. This module gives access to a series of multilingual API functions, and a multiple of user interfaces that will help us properly managing the multilinguality capabilities of Drupal.

Once the internationalization module is enabled, you should also enable the following modules:

  1. Block languages
  2. Field translation
  3. Menu translation
  4. Multilingual support
  5. Multilingual select
  6. Path translation
  7. String translation
  8. Variable translation

Enabling Multilingual Support for Every Content Type

The final step that will be required is to edit all the content type that you currently have on your Drupal portal, and to enable the multilingual capabilities of each of them that you want to translate. What you have to do is to edit one of the content type (the Page content type in this example):

Multilingual 7.PNG

The you have to click the Publishing options vertical tab. Finally you have to enable (with translation) the content type.

Once all these steps are done, you will be able to translate all the content types pages on your Drupal instance. However, this is out of the scope of this article. If you want more information about doing this, we strongly suggest you to read Gábor Hojtsy's series of articles covering these questions in details.

Multilingual Capabilities of OSF Entities

Multilingual capabilities of OSF Entities will only appears to the system administrators and content curators if Drupal's multilingual capabilities are enabled. However, once they are enabled, a series of new features will be available to the users.

Multilingual Implementation in OSF Entities

In this section we will cover how the multilingual capabilities of OSF Entities have been implemented. The translation mechanism that has been implemented for OSF Entities is similar to the Field Translation one in Drupal. This means that we don't create new resources every time we create translate an existing resource in another language. We simply translate the values of the fields, and assign a language for each of the values.

Let's take a Resource Entity. That Resource Entity has been initially described using the English language. This means that multiple fields have been defined for that Entity, and that the literals values of these fields are written in English.

Then when the multilingual capabilities of the module kicks-in, we are able the translate the same Resource Type Entity in other languages. This means that all the fields that accepts literal values can be translated in other languages (the ones enabled in the Drupal portal).

Multilingual 8.PNG

Once an Entity got translated in one or multiple languages, OSF Entities will merge all the translated fields in a Canonical Resource. It is that canonical resource that is saved in OSF.

Translating Resource Type Entities

It is really easy to translate existing Resource Type Entities once the Drupal portal's multilingual capabilities are properly configured. If you edit any Resource Type Entities, then you will see a new TRANSLATE tab.

Multilingual 9.PNG

What you will see in this tab is one row per language configured on the Drupal portal. Then you will have the list of translations for that entity that you are editing. If the TITLE column for one of the language is empty, it means that the entity is not yet translated.

Multilingual 10.PNG

If you click the edit link of any translation of that entity, you will get to a new edit page where you will be able to edit entity using the selected language. Then you will see appearing a message that warn the user that he is currently translating the entity in French (or the selected language from the previous step). Every literal that will have written in that French translation page will be tagged with the French language. Every time that a search will be performed in French, or that this entity will be viewed in French, we will see the translation that has been defined in that page.

Multilingual 11.PNG

Once the user click the Save button, the new translation will be saved into OSF and will be available to all the system that uses that information.

A Word about Revisioning

The multilinguality capabilities of the OSF Entity module has no impact on the revisions capabilities of the module. Every modifications to the entity, in any language, will be accordingly revisioned into OSF. If you click the REVISIONS tab, you will be able to see, compare and manage all the revisions, in any language.

Multilingual Capabilities of OSF FieldStorage

Multilingual capabilities of OSF FieldStorage will only appears to the system administrators and content curators if Drupal's multilingual capabilities are enabled. However, once they are enabled, a series of new features will be available to the users.

Multilingual Implementation in OSF FieldStorage

In this section we will cover how the multilingual capabilities of OSF FieldStorage have been implemented. The translation mechanism that OSF FieldStorage supports is Drupal's Node Translation. Field translation is not currently supported by the osf_fieldstorage field storage type (so, it is not supported by the OSF FieldStorage module). The Node Translation mechanism means that every time you translate a content type page, you are creating a new content type entity that uses this new language.

Multilingual 18.PNG

As you can see, every translation will result in a new resource that will be saved in OSF.

Translating Content Type Entities

For every content type that you want to translate, you have to make sure that its multilingual support is enabled. For every such content type, you have to edit it, and then clicking the Publishing options vertical tab and to select one of the Multilingual support option that are available.

Multilingual 7.PNG

Once this is done, you will be able to change the language of each entity of that content type.

The next step is to edit one of the content type page that you want to translate. Once you found the page to edit, you will see a new option Language appearing in the edit form. From that drop-down box, you have to select the language used for describing that page.

Multilingual 15.PNG

Once you selected a language other than Language neutral, you will see a new TRANSLATE tab appearing in the user interface. If you click on that tab, you will get to the translation page for this entity.

Multilingual 17.PNG

In this translation page, you have multiple options. First you will see the list of languages supported by the Drupal portal. For each of these languages, you will see if it has been already translated or not. It is has been translated, you will see the title of the translated page, otherwise you will see n/a. If there is a language for which you don't have a translation, you will see a add translation link in the operations column. By clicking on that link, you will be redirected to a new edit form that will let you write everything you want, in that selected language, for describing that entity.

Multilingual Capabilities of OSF SearchAPI

The OSF SearchAPI does support multilinguality without having to configure anything. What it does is to detect the language currently used by the user that perform a search query and will use that language to send the Search query.

The only think that is necessary is to make sure that the OSF Search web service endpoint does support that language.

Multilinguality and Search Templates

When will come the time to create the search templates for a multilingual Drupal portal, the Drupal themers will have to take care, and make sure they properly manipulate the entities to use the proper language to display in the search resultset.

Using Pre-Caching

Caching is in integral part of Drupal. How often are you reading "Flush the cache, it should fix you issue". There is a reason for that: nearly everything is caching in a way or another. Caching also has a great impact on a Drupal's site performance depending on certain usecases.

This is for these reasons that we developed a simple set of configuration options in OSF for Drupal to pre-cache Drupal entities. The goal of this feature is to give the possibility to system administrators to populate their cache with all the entities content available on their portal instead of waiting for users to hit a non-cached page to cache it. This may greatly improve the performance of their Drupal portal that is in production.

How does it works?

This feature is really simple. First, it proposes three options to the system administrators:

  1. To pre-cache all entities that exists in specific datasets
  2. To pre-cache all entities that exists in specific ontologies
  3. To pre-cache all entities that exists in specific bundles

Once the system administrator made his choices, then this caching mechanism will get the list of all these entities, and will load all of them using the entity_load() API call. By using this call, all these entities will be cached.

When is it helpful to run this pre-caching mechanism?

It will be helpful to use this pre-caching mechanism for the following scenarios (do not limit yourself to these, there may be others):

  1. When you want to make sure that optimal performances for any pages of your Drupal portal
  2. When you have a Drupal portal that uses multiple field storage systems for a big number of entities
  3. After you flushed all the cache in Drupal
  4. After you reloaded an external caching server like Memcached

Using the pre-caching mechanism

To access the pre-caching features, you have to go to the OSF for Drupal Settings, and then to click on the CACHING tab.

Caching 1.PNG

In that page, you will have two sections: one that deal with OSF Entities caching, and one that deal with Content Type (OSF FieldStorage) caching.

The first section deals with the OSF Entities caching. From that section, you can select the datasets and the ontologies that you would like to pre-cache into Drupal. Once you checked all the things you wanted to pre-cache, you can click the Pre-cache selected datasets entities button. Once you click that button, you will be redirected to a progress page that will show you the progress of the pre-caching process (see below).

Caching 2.PNG

The second section deals with the Content Type caching. From that section, you can select the bundles that you would like to pre-cache into Drupal. Once you checked all the things you wanted to pre-cache, you can click the Pre-cache selected bundles entities button. Once you click that button, you will be redirected to a progress page that will show you the progress of the pre-caching process (see below).

Caching 3.PNG

In the batch pre-caching process, you will be notified of the progress of this batch process. If for any reason you are leaving that progress page, do not worry. All the entities that will be cached won't be re-cached another time if you have to re-run the same process. What is cached remain cached.

Caching 4.PNG

Using Drupal Views

Debugging

Different debugging options are available to the OSF for Drupal administrators and developers. All the debugging options discussed in this article are related to debugging the interaction between OSF for Drupal and OSF Web Services. All actions, all operations of OSF for Drupal modules end-up being web service queries to one of the OSF Web Services.


To access the debugging settings, click on the top Configuration menu item. Then, you have to click the Configure OSF for Drupal modules.

OSF for Drupal configurations

Then click the Debugging tab. Now you will see all the configuration options.

Osf debugging.PNG

The two debugging options that are available are:

  1. Display all the calls being made by OSF for Drupal to OSF instance(s).
    1. This will display all the web service calls that are exchanged between OSF for Drupal modules and OSF Web Services. Every time you load a page, if a call is being made to a web service endpoint (except if it is a call to load an entity, see below), then the query will be displayed at the top of the page.
  2. Display loaded Resource Type entities.
    1. This option will display all the CRUD: Read calls that are used by OSF for Drupal to load Resource Type entities. If you enable this option, you will have many more debugging outputs. Also note that if the entity is cached, then no call will appears. To make them appearing, you will have to clear Drupal's cache.

Once you are done, you only have to click Save configuration to save the settings and start seeing debugging information appearing on the website.

Note: Only the administator users will be able to see the debugging output.


Manual Invocation

It is possible to invoke the debugging output without changing the settings, and this, for any Drupal pages. This method also only apply to administrators. If a non-administrator uses this method, that user won't see any debugging output appearing.

The only thing you have to do is to add the wsf_debug=1 parameter to any URL of the Drupal portal.

Debugging Output

Every time a query is exchanged, a box will appear at the top of the Drupal page that is being loaded. The debug box looks like this:

Osf debug output.PNG

Each of these boxes are individual queries sent to one of the OSF Web Services endpoint. The title of the box shows where the query has been sent (which endpoint, and which web service). Then, a series of information is displayed for each query:

  1. url
    1. This is the same information that is in the title of the output; this is the endpoint URL where the query has been sent
  2. method
    1. This is the HTTP method that has been used to send the query
  3. mime
    1. This is the mime type used to send the query
  4. parameters
    1. These are all the parameters that have been used in the query
  5. execution time
    1. This is the execution time of the query in drupal. What that means is that if the query goes to different kind of proxying servers before hitting the real OSF Web Service endpoint, then this proxying time will be included in the execution time displayed to the user. All the network latency will be included as well.
  6. status
    1. This is the HTTP status ID returned by the endpoint's web server
  7. status message
    1. This is the HTTP status message returned by the endpoint's web server
  8. status description
    1. This is the HTTP status message description returned by the endpoint's web server
  9. data
    1. This is the data returned by the endpoint, for that query.
  10. wsq
    1. This is a serialized version of the WSQ object used to send the query. Many more debugging information may be available in this object.095

Pages in category "OSF for Drupal User Manual"

This category contains only the following page.