Functions
	hook_vocab_storage_info ()

	hook_vocab_import_form ($form, &$form_state)

	hook_vocab_import_form_validate ($form, &$form_state)

	hook_vocab_import_form_submit ($form, &$form_state)

	hook_vocab_get_term ($vocabulary, $accession)

	hook_vocab_get_terms ($vocabulary, $limit=25, $element=0)

	hook_vocab_get_term_children ($vocabulary, $accession)

	hook_vocab_get_root_terms ($vocabulary)

	hook_vocab_get_vocabulary ($vocabulary)

	hook_vocab_get_vocabularies ()

	hook_vocab_add_term ($details)

	tripal_add_term ($details)

	tripal_get_term_details ($vocabulary, $accession)

	tripal_get_vocabulary_root_terms ($vocabulary)

	tripal_get_term_children ($vocabulary, $accession)

	tripal_get_vocabulary_details ($vocabulary)

	tripal_get_vocabulary_terms ($vocabulary, $limit=25, $element=0)

	tripal_get_vocabularies ()

	tripal_get_term_lookup_form (&$form, &$form_state, $default_name='', $title='Vocabulary Term', $description='', $is_required=FALSE, $field_name='', $delta=0, $callback='', $wrapper='', $validate=[], $weight=0)

	tripal_get_term_lookup_form_options_descriptions ($element, &$form_state)

	tripal_get_term_lookup_form_result ($form, $form_state, $field_name='', $delta=0)

	tripal_get_term_lookup_form_ajax_callback ($form, $form_state)

	tripal_chado_semweb_edit_form_options_descriptions ($element, &$form_state)

Detailed Description

Tripal provides an application programming interface (API) for working with controlled vocabulary terms. Tripal v3 is highly dependent on controlled vocabularies for identifying all content types and fields attached to those content types. However, Tripal v3 is also database agnostic. Therefore, controlled vocabularies can be stored in any database back-end. By default the tripal_chado module is used for storing controlled vocabularies. However, if someone wanted to store controlled vocabularies in a database other than Chado they can do so. These API functions provide a convenient wrapper for accession controlled vocabularies no matter where they are stored.

Function Documentation

◆ hook_vocab_add_term()

hook_vocab_add_term ( $details )

Hook used by the default term storage backend to add new terms.

Parameters

$details An array with at least the following keys: -vocabulary : An associative array with the following keys: -name: The short name for the vocabulary (e.g. SO, PATO, etc). -description: The description of this vocabulary. -url: The URL for the vocabulary. -urlprefix: (optional) A URL to which the short_name and term accession can be appended to form a complete URL for a term. If the prefix does not support appending then the exact location for the position of the short_name and the term accession will be specified with the {db} and {accession} tags respectively. -accession : The name unique ID of the term. -url : The URL for the term. -name : The name of the term. -definition : The term's description.

Returns: TRUE if the term was added, FALSE otherwise. If the term already exists it will be updated and the return value will be TRUE.

◆ hook_vocab_get_root_terms()

hook_vocab_get_root_terms ( $vocabulary )

Hook used by the default term storage backend to provide root terms.

This hook is called by the tripal_entity module to retrieve a list of root terms for a given vocabulary from the storage backend. It must return an array of terms where each term contains the same structure as that of the hook_vocab_get_term().

Parameters

$vocabulary The vocabulary of the vocabulary in which the term is found.

Returns: An array of root terms where each term contains the same structure as that of the hook_vocab_get_term(), or an empty array if no children are present.

◆ hook_vocab_get_term()

hook_vocab_get_term	(	$vocabulary,
		$accession
	)

Hook used by the default term storage backend to provide details for a term.

This hook is called by the tripal_entity module to retrieve information about the term from the storage backend. It must return an array with a set of keys.

Parameters

$vocabulary	The vocabulary of the vocabulary in which the term is found.
$accession	The unique identifier (accession) for this term.

Returns: An array with at least the following keys: -vocabulary : An associative array with the following keys: -name: The short name for the vocabulary (e.g. SO, PATO, etc). -description: The description of this vocabulary. -url: The URL for the vocabulary. -urlprefix : (optional) A URL to which the short_name and term accession can be appended to form a complete URL for a term. If the prefix does not support appending then the exact location for the position of the short_name and the term accession will be specified with the {db} and {accession} tags respectively. -accession : The name unique ID of the term. -url : The URL for the term. -name : The name of the term. -definition : The term's description. any other keys may be added as desired. Returns NULL if the term cannot be found.

◆ hook_vocab_get_term_children()

hook_vocab_get_term_children	(	$vocabulary,
		$accession
	)

Hook used by the default term storage backend to provide children for a term.

This hook is called by the tripal_entity module to retrieve a list of children for a term from the storage backend. It must return an array of terms where each term contains the same structure as that of the hook_vocab_get_term().

Parameters

$vocabulary	The vocabulary of the vocabulary in which the term is found.
$accession	The unique identifier (accession) for this term.

Returns: An array of terms where each term contains the same structure as that of the hook_vocab_get_term(), or an empty array if no children are present.

◆ hook_vocab_get_terms()

hook_vocab_get_terms	(	$vocabulary,
		$limit = `25`,
		$element = `0`
	)

Retrieves a paged list of terms from a vocabulary.

Parameters

$vocabulary	The short name of the vocabulary.
$limit	The number of results to return.
$element	The pager element. This is equivalent to the element from the pager_default_initialize() function of Drupal.

◆ hook_vocab_get_vocabularies()

hook_vocab_get_vocabularies ( )

Retrieves the list of vocabularies that are available on the site.

Returns: An array of vocabularies where each entry in the array is compatible with the array returned by the tripal_get_vocabulary_details() function.

◆ hook_vocab_get_vocabulary()

hook_vocab_get_vocabulary ( $vocabulary )

Hook used by the default term storage backend to provide details for a vocab.

This hook is called by the tripal_entity module to retrieve information about the vocabulary from the storage backend. It must return an array with a set of keys.

Parameters

$vocabulary The vocabulary of the vocabulary in which the term is found.

Returns

An array with at least the following keys:

name : The full name of the vocabulary.
short_name : The short name abbreviation for the vocabulary.
description : A brief description of the vocabulary.
url : (optional) A URL for the online resources for the vocabulary.
urlprefix : (optional) A URL to which the short_name and term accession can be appended to form a complete URL for a term. If the prefix does not support appending then the exact location for the position of the short_name and the term accession will be specified with the {db} and {accession} tags respectively.

◆ hook_vocab_import_form()

hook_vocab_import_form	(		$form,
		&	$form_state
	)

Provides a form for importing vocabularies and their terms.

Tripal allows for vocabularies to be stored separately from the biological data. This hook allows the default term storage backend to provide an appropriate form for importing ontologies (either in OBO or OWL format).

Parameters

$form
$form_state

◆ hook_vocab_import_form_submit()

hook_vocab_import_form_submit	(		$form,
		&	$form_state
	)

Submits the hook_vocab_import_form().

Parameters

$form
$form_state

◆ hook_vocab_import_form_validate()

hook_vocab_import_form_validate	(		$form,
		&	$form_state
	)

Validates the hook_vocab_import_form().

Parameters

$form
$form_state

◆ hook_vocab_storage_info()

hook_vocab_storage_info ( )

◆ tripal_add_term()

tripal_add_term ( $details )

Adds a term to the vocabulary storage backend.

Use this function to add new terms dynamically to the vocabulary storage backend. If the term already exists no new term is added.

Parameters

$details An array with at least the following keys: -vocabulary : An associative array with the following keys -name: The short name for the vocabulary (e.g. SO, PATO, etc). -description: The description of this vocabulary. -url: The URL for the vocabulary. -accession : The name unique ID of the term. -url : The URL for the term. -name : The name of the term. -definition : The term's description.

Returns: TRUE if the term was added, FALSE otherwise. If the term already exists it will be updated and the return value will be TRUE.

◆ tripal_chado_semweb_edit_form_options_descriptions()

tripal_chado_semweb_edit_form_options_descriptions	(		$element,
		&	$form_state
	)

Callback to add a #description to an individual radio in a 'radios' group.

Starting with drupal 8 we can add descriptions to individual elements in a 'radios' form element, but for drupal 7 we need a callback to implement this.

Returns: Updated form element.

◆ tripal_get_term_children()

tripal_get_term_children	(	$vocabulary,
		$accession
	)

Retrieves the immediate children of the given term.

Parameters

$vocabulary	The vocabulary of the vocabulary in which the term is found.
$accession	The unique identifier (accession) for this term.

Returns: Returns an array of terms where each term is compatible with the array returned by the tripal_get_term_details() function.

◆ tripal_get_term_details()

tripal_get_term_details	(	$vocabulary,
		$accession
	)

Retrieves full information about a vocabulary term.

Parameters

$vocabulary	The vocabulary of the vocabulary in which the term is found.
$accession	The unique identifier (accession) for this term.

Returns

An array with at least the following keys:

vocabulary : An array containing the following keys:
- name : The full name of the vocabulary.
- short_name : The short name abbreviation for the vocabulary.
- description : A brief description of the vocabulary.
- url : (optional) A URL for the online resources for the vocabulary.
- urlprefix : (optional) A URL to which the short_name and term accession can be appended to form a complete URL for a term. If the prefix does not support appending then the exact location for the position of the short_name and the term accession will be specified with the {db} and {accession} tags respectively.
accession : The name unique ID of the term.
url : The URL for the term.
name : The name of the term.
definition : The term's description. any other keys may be added as desired. Returns NULL if the term cannot be found.

◆ tripal_get_term_lookup_form()

tripal_get_term_lookup_form	(	&	$form,
		&	$form_state,
			$default_name = `''`,
			$title = `'Vocabulary Term'`,
			$description = `''`,
			$is_required = `FALSE`,
			$field_name = `''`,
			$delta = `0`,
			$callback = `''`,
			$wrapper = `''`,
			$validate = `[]`,
			$weight = `0`
	)

Provides a term lookup form.

It may be necessary at times for a form to provide to the user the ability to lookup and use a controlled vocabulary term. However, a simple text box or auto-lookup is not sufficient because a term name may be identical in multiple vocabularies and the user would need to select the proper term.

This function will add the form elements necessary to provide a lookup form. The form elements should work with a flat form (no #tree set for the form) or with a form in a TripalField.

Use the tripal_get_term_lookup_form_result() function to retrieve the result in a form submit or validate.

Parameters

$form	The form (or $widget form).
$form_state	The form state.
$default_name	The name of a cv term to present as default selection, and optional cvterm_id appended using format "termname [id: 1234]".
$title	The title to give to the field set.
$description	A description for the lookup field element.
$is_required	Indicates if this form element is required.
$field_name	The name of the field, if this form is being added to a field widget.
$delta	The delta value for the field if this form is being added to a field widget.
$callback	Ajax callback function, defaults to 'tripal_get_term_lookup_form_ajax_callback'.
$wrapper	Ajax wrapper ID.
$validate	Widget validation configuration.
$weight	The weight value for the field if this form is being added to a field widget.

◆ tripal_get_term_lookup_form_ajax_callback()

tripal_get_term_lookup_form_ajax_callback	(	$form,
		$form_state
	)

Implements an AJAX callback for the tripal_chado_vocab_select_term_form.

◆ tripal_get_term_lookup_form_options_descriptions()

tripal_get_term_lookup_form_options_descriptions	(		$element,
		&	$form_state
	)

Callback to add a #description to an individual radio in a 'radios' group.

Starting with drupal 8 we can add descriptions to individual elements in a 'radios' form element, but for drupal 7 we need a callback to implement this.

Returns: Updated form element.

◆ tripal_get_term_lookup_form_result()

tripal_get_term_lookup_form_result	(	$form,
		$form_state,
		$field_name = `''`,
		$delta = `0`
	)

Returns the terms selected from the tripal_get_term_lookup_form.

Parameters

$form	The form (or $widget form).
$form_state	The form state.
$field_name	The name of the field, if this form is being added to a field widget.
$delta	The delta value for the field if this form is being added to a field widget.

Returns: An array of term objects for each of the user selected terms.

◆ tripal_get_vocabularies()

tripal_get_vocabularies ( )

Retrieves the list of vocabularies that are available on the site.

Returns: An array of vocabularies where each entry in the array is compatible with the array returned by the tripal_get_vocabulary_details() function.

◆ tripal_get_vocabulary_details()

tripal_get_vocabulary_details ( $vocabulary )

Retrieves full information about a vocabulary.

Vocabularies are stored in a database backend. Tripal has no requirements for how terms are stored. By default, the tripal_chado modules provides storage for vocabularies and terms. This function will call the hook_vocab_get_term() function for the database backend that is housing the vocabularies and allow it to return the details about the term.

Parameters

$vocabulary The vocabulary of the vocabulary in which the term is found.

Returns

An array with at least the following keys:

name: The full name of the vocabulary.
short_name: The short name abbreviation for the vocabulary.
description: A brief description of the vocabulary.
url: A URL for the online resources for the vocabulary.
urlprefix: A URL to which the short_name and term accession can be appended to form a complete URL for a term. If the prefix does not support appending then the exact location for the position of the short_name and the term accession will be specified with the {db} and {accession} tags respectively.
sw_url: The URL for mapping terms via the semantic web.
num_terms: The number of terms loaded in the vocabulary.

◆ tripal_get_vocabulary_root_terms()

tripal_get_vocabulary_root_terms ( $vocabulary )

Retrieves the immediate children of the given term.

Parameters

$vocabulary	The vocabulary of the vocabulary in which the term is found.
$accession	The unique identifier (accession) for this term.

Returns: Returns an array of terms where each term is compatible with the array returned by the tripal_get_term_details() function.

◆ tripal_get_vocabulary_terms()

tripal_get_vocabulary_terms	(	$vocabulary,
		$limit = `25`,
		$element = `0`
	)

Retrieves a paged list of terms from a vocabulary.

Parameters

$vocabulary	The short name of the vocabulary.
$limit	The number of results to return.
$element	The pager element. This is equivalent to the element from the pager_default_initialize() function of Drupal.

Functions

Detailed Description

Function Documentation

◆ hook_vocab_add_term()

◆ hook_vocab_get_root_terms()

◆ hook_vocab_get_term()

◆ hook_vocab_get_term_children()

◆ hook_vocab_get_terms()

◆ hook_vocab_get_vocabularies()

◆ hook_vocab_get_vocabulary()

◆ hook_vocab_import_form()

◆ hook_vocab_import_form_submit()

◆ hook_vocab_import_form_validate()

◆ hook_vocab_storage_info()

◆ tripal_add_term()

◆ tripal_chado_semweb_edit_form_options_descriptions()

◆ tripal_get_term_children()

◆ tripal_get_term_details()

◆ tripal_get_term_lookup_form()

◆ tripal_get_term_lookup_form_ajax_callback()

◆ tripal_get_term_lookup_form_options_descriptions()

◆ tripal_get_term_lookup_form_result()

◆ tripal_get_vocabularies()

◆ tripal_get_vocabulary_details()

◆ tripal_get_vocabulary_root_terms()

◆ tripal_get_vocabulary_terms()