This is the documentation for the "Climate Tagger"-module.

Table of contents:

---------------------------------------------------------------------------------------

Documentation for Server Administrators

This area offers documentation for usual tasks of a server administrator using the Climate Tagger module.

Installation of the module

Server requirements

  • cURL needs to be installed on the web server your Drupal-instance runs on.

Module requirements

Install and enable first the modules from the "Requirements"-list above and then the most recent release of the "Climate Tagger"-module (See https://drupal.org/documentation/install/modules-themes/modules-7 for further information.)

---------------------------------------------------------------------------------------


Documentation for Content Management System Administrators

This area offers documentation for usual tasks of a content manager using the Climate Tagger module.

Obtain an API token

To use the Climate Tagger API an API token is required. You can obtain your token in three simple steps:

  1. Go to api.climatetagger.net/register
  2. Register an account for free
  3. Once successfully registered log in and create a project to obtain the associated API token (you can create as many projects as you like but will get one token per project).
    1. Once logged in go to "Implement the API" -> “API Projects”.
    2. Fill in a project name and click on "Add".
    3. The token for the created project will be displayed now.

The following section will describe how to use your obtained token for the Climate Tagger module.


Basic module configuration

The module-configuration can be reached by clicking on "Configuration" --> "Web services" --> "Climate Tagger" in the administration menu.

The module configuration consists out of four sub-areas:

Server

 Server
Here you can insert your previously obtained API token. By clicking on "Health Check" you can check if the API Server can be reached and if your API token is valid.

Project options

 Project options
Depending on the focus of your resources, you can select here a specific sector of the Climate Tagger (Climate Change Adaptation, Energy Efficiency, Renewable Energy or Climate Change Mitigation) or you can use all sectors by selecting the Full Climate Thesaurus.
Further you can link all languages, that are installed inside your Drupal system, with languages that are supported by the Climate Tagger API. Currently supported languages are English, French, German, Portuguese and Spanish. If some content does not have an explicit language, the language selected at "Language neutral" will be used for the tag extraction.
Below you need to select a name for the taxonomy, that will be used to save the extracted tags. If you select a taxonomy name that does not exist yet, it will automatically be created on save.

Global limits

 Global limits
Here you can select the default parameters for the tag extraction. "Concepts" are part of the Climate Thesaurus while "Free terms" are tag suggestions, that seem relevant for the extracted content but are not (yet) included in the Climate Thesaurus.

Batch jobs
Before you can use the bulk tagging, tagging needs to be configured for specific content types. Further information about this area is avaialble here.


Adding a "Climate Tagger Tags" field to your content types

Once you have saved the Climate Tagger module configuration, you can start to configure tagging for specific entities. This example will describe the configuration procedure for nodes, nevertheless users and taxonomy terms are also supported by Climate Tagger.

  1. Click on "Structure --> Content types", select the content type you want to add tagging for and click on "Manage fields".
  2. Scroll down to the form element that says "Add new field" and select "Climate Tagger Tags" as the field type.

    Field Configuration 1
  3. Enter a label for the field and click on the "Save"-button on the bottom of the page.
  4. The upcoming page just states that the Climate Tagger API will get used for tagging. Just click on "Save field settings" here.
  5. The following page has three interesting areas:

    Field Configuration 2
    • Use tags of an existing tags-field as default values: If you already used to tag your content in Drupal before using the Climate Tagger, you can select the regarding tag-field here. If a field gets selected, the already existing tags will be used as the default value for the new "Climate Tagger Tags" field. Old tags will be handled as free terms internally.
    • Concept settings: These settings are the same as in the module configuration and its default values are inherited from there. This selection will only affect the current field and therefore the current content type.
    • Fields to extract tags from: Select all field that should be included in the tag extraction here. Supported field types are "Text", "Long text", "Long text and summary" and "File". Supported editors are CKEditor and tinyMCE. Supported file types are Word, Excel, Powerpoint, PDF and Open document.

    A static default value for the Climate Tagger tags field can also be set here in case it is required for your use case, generally the default value textarea can be left empty.

  6. Click on "Save settings" on the bottom of the page.

That's it, your content is ready to be tagged now.


Displaying a "Climate Tagger Tags" field to the users

Adding the Climate Tagger Tags field to a content type is not enough to display the tags of the content to your website users, there is one thing left to do:

  1. Click on "Structure --> Content types", select the content type you want to add tagging for and click on "Manage display". There you should see a list like this one:

    Manage Display
  2. Search for the "Climate Tagger Tags" field and use the handle to the left of the field title to pull the field to any region and position you like.

That's it, tagged content will be displayed with a list of Climate Tagger tags now.


Bulk tagging

To automatically tag all content of one content type with one call you can use the bulk tagging feature of the Climate Tagger. To use this feature to the module configuration and open the tab "Batch jobs".

Bulk Tagging

  • Entity types to be included in the batch process: From all the "Climate Tagger Tags"-fields you have configured so far, you have to select at least one here.
  • Skip already tagged content: If some of the content was already tagged with the Climate Tagger before, you can choose between skipping that content during the bulk tagging process by selecting "No" or deleting previous tags and retagging this content by selecting "Yes".
  • Entities per request: This options controls the number of entities, that get processed during one HTTP request. (Allowed value range: 1 - 100). The higher this number is, the less HTTP requests have to be sent to the server until the batch finished tagging ALL your entities, what results in a shorter duration of the bulk tagging process. Numbers too high can result in a timeout, which will break the whole bulk tagging process. If entities are configured to get tagged with uploaded files, a value of 5 or below is recommended.

By clicking on "Index" you will start the batch job. Do NOT close your browser while the progress bar has not reached 100% in order to successfully finish the process. You will be informed about the result of the bulk tagging process as soon as it is finished.

---------------------------------------------------------------------------------------


Documentation for Authors / Editors of the System

This area offers documentation for usual tasks of a content editor using the Climate Tagger module.

Tagging content

If you add new content or edit existing content of a content type, that includes a correctly configured "Climate Tagger Tags" field (like explained above), you should now be able to see a field like this one:

Climate Tagger UI 1

  1. As soon as you click on "Get tags" the content of the configured fields will be sent to the Climate Tagger API, which will return one list of matching concepts and freeterms for all the form field data and one list for each file that is part of the extraction. The automatically created suggestion will use the tags with the highest scores out of all the extracted lists to offer you a first tag selection.

    Climate Tagger UI 2
  2. If you want to remove tags from the tag selected or add extracted tags, that were not added to the selection list, one simple click on the tag is enough.
  3. If you want to add a tag manually you can do so in the correspondent textbox. (it does not need to exist in the Climate thesaurus, you can use any tag you like)
  4. Save your content as usual and you are done.