Tripal Entities

Functions
	hook_entity_create (&$entity, $entity_type)
	hook_bundle_create (&$bundle, $storage_args)
	hook_bundle_postcreate (&$bundle)
	hook_tripal_cron_notification ()
	hook_bundle_delete ($bundle)
	hook_tripal_default_title_format ($bundle, $available_tokens)
	tripal_load_entity ($entity_type, $ids=FALSE, $reset=FALSE, $field_ids=[], $cache=TRUE)
	tripal_load_term_entity ($values)
	tripal_load_vocab_entity ($values)
	tripal_load_bundle_entity ($values)
	tripal_add_notification ($title, $details, $type, $actions, $submitter_id)
	tripal_create_bundle ($args, $job=NULL)
	tripal_get_content_types ()
	tripal_tripal_cron_notification ()
	tripal_get_content_type ($bundle_name)
	tripal_create_bundle_fields ($bundle, $term)
	tripal_update_bundle_field ($field_name, $field_info, $entity_type_name, $bundle_name)
	tripal_get_bundle_variable ($variable_name, $bundle_id, $default=FALSE)
	tripal_set_bundle_variable ($variable_name, $bundle_id, $value)
	tripal_get_title_format ($bundle)
	tripal_save_title_format ($entity, $format)
	tripal_get_default_title_format ($bundle)
	tripal_get_entity_tokens ($bundle, $options=[])
	tripal_replace_entity_tokens ($string, &$entity, $bundle_entity=NULL)
	theme_token_list ($tokens)
	tripal_entity_label ($entity)
	tripal_get_bundle_details ($bundle_name)
	_tripal_get_bundle_field_element_details ($elements, &$field_details)

Detailed Description

Provides an application programming interface (API) for working with TripalEntity content types (bundles) and their entities.

Bundles (Content Types): Bundles are types of content in a Drupal site. By default, Drupal provides the Basic Page and Article content types, and Drupal allows a site developer to create new content types on-the-fly using the administrative interface–no programming required. Tripal also provides several Content Type by default. During installation of Tripal the Organism, Gene, Project, Analysis and other content types are created automatically. The site developer can then create new content types for different biological data–again, without any programming required.

In order to to assist with data exchange and use of common data formats, Tripal Bundles are defined using a controlled vocabulary term (cvterm). For example, a "Gene" Bundle is defined using the Sequence Ontology term for gene whose term accession is: SO:0000704. This mapping allows Tripal to compare content across Tripal sites, and expose data to computational tools that understand these vocabularies. By default, Tripal uses Chado as its primary data storage back-end.

Entity: An entity is a discrete data record. Entities are most commonly seen as "pages" on a Drupal web site and are instances of a Bundle (i.e content type). When data is published on a Tripal site such as organisms, genes, germplasm, maps, etc., each record is represented by a single entity with an entity ID as its only attribute. All other information that the entity provides is made available via Fields.

For more information please see: http://tripal.info/tutorials/v3.x/developers-handbook/structure

Function Documentation

_tripal_get_bundle_field_element_details()

_tripal_get_bundle_field_element_details	(		$elements,
		&	$field_details
	)

A recursive helper function for the tripal_get_bundle_details.

Parameters

$elementInfo

hook_bundle_create()

hook_bundle_create	(	&	$bundle,
			$storage_args
	)

Allows a module to perform tasks after a TripalBundle object is created.

Parameters

$bundle	The newly created TripalBundle object.
$storage_args	Arguments passed to the storage backend for this bundle. These arguments typically provide details for how to associate this bundle with records in the storage system. Each storage system will have its own set of arguments that it will expect.

hook_bundle_delete()

hook_bundle_delete

(

$bundle

)

Allows a module to perform tasks before a TripalBundle object is deleted.

Parameters

$bundle

The newly created TripalBundle object.

hook_bundle_postcreate()

hook_bundle_postcreate

(

&

$bundle

)

Allows a module to perform tasks after fields are added to a TripalBundle.

Parameters

$bundle

The newly created TripalBundle object.

hook_entity_create()

hook_entity_create	(	&	$entity,
			$entity_type
	)

hook_tripal_cron_notification()

hook_tripal_cron_notification

(

)

Allows a module to add admin notifications to the associated tripal table during the cron run.

hook_tripal_default_title_format()

hook_tripal_default_title_format	(		$bundle,
			$available_tokens
	)

Implement this hook to define default formats for Tripal Content Types.

Parameters

TripalBundle	$bundle	A tripal content type entity with information to be used for determining the default title format.
array	$available_tokens	An array of available tokens for this particular tripal content type.

Returns

array An array of potential formats. The lightest weighted format suggested by all modules will be chosen. Each array item should consist of a 'weight' and 'format'. See the hook implementation below for examples.

• weight: an integer used to determine priority of suggestions. The smaller/lighter the number the higher the priority. Best practice is to use a weight less than 0 for extension modules. specifically, -2 is a good weight for calculated formats and -5 is a good weight for hard-coded formats specific to a given type.
• format: a string including approved tokens used to determine the title on Tripal content pages.

theme_token_list()

theme_token_list

(

$tokens

)

Formats the tokens for display.

Parameters

array

$tokens

A list of tokens generated via tripal_get_entity_tokens().

Returns

Rendered output describing the available tokens.

tripal_add_notification()

tripal_add_notification	(		$title,
			$details,
			$type,
			$actions,
			$submitter_id
	)

Allows a module to write to the admin notification table.

Parameters

$title	A generic phrase indicating what the notification is for.
$details	A human-readable sentence or two describing the issue.
$type	A one word type indicating the type of notification. Tripal types include: Jobs, Fields. If no type is required please pass NULL.
$actions	A serialized PHP associative array containing the link and URL for each action. If not type is required please pass NULL.
$submitter_id	A unique ID provided by the submitter for checking to make sure that the notification is not added more than once.

tripal_create_bundle()

tripal_create_bundle	(		$args,
			$job = NULL
	)

Creates a new Tripal Entity type (i.e. bundle).

Parameters

$args

An array of arguments that must include the following keys: vocabulary: The abbreviated vocabulary for the vocabulary (e.g. RO, SO, PATO). accession: The unique term ID in the vocabulary $vocabulary (i.e. an accession). term_name: A human-readable name for this term. This will became the name that appears for the content type. In practice, this should be the name of the term. (E.g. the name for SO:0000704 is gene). label: An alternative bundle label. This will be used instead of the term name, for cases where the vocabulary term is not human readable.

$job

The job ID if this is launched via a job.

Returns

The bundle object or FALSE if failure.

tripal_create_bundle_fields()

tripal_create_bundle_fields	(		$bundle,
			$term
	)

Refreshes the bundle such that new fields added by modules will be found.

Parameters

$bundle_name	The name of the bundle to refresh (e.g. bio_data_4).
$term	The term object for the bundle.

Returns

The array of field instance names that were added.

tripal_entity_label()

tripal_entity_label

(

$entity

)

Define the entity label callback. This will return the title.

Parameters

$entity

Returns

mixed

tripal_get_bundle_details()

tripal_get_bundle_details

(

$bundle_name

)

Retrieves details, including attached fields, for a given bundle.

Parameters

$bundle_name

The name of the bundle (e.g. bio_data_xx)

Returns

An array containing the name, label, controlled vocabulary details and a list of fields attached to the bundle. Returns FALSE if the bundle does not exist.

tripal_get_bundle_variable()

tripal_get_bundle_variable	(		$variable_name,
			$bundle_id,
			$default = FALSE
	)

tripal_get_content_type()

tripal_get_content_type

(

$bundle_name

)

Retrieves information about a given content type.

Parameters

$bundle_name

The name of a bundle.

Returns

An object containing information about the bundle.

tripal_get_content_types()

tripal_get_content_types

(

)

Retrieves a list of the content types.

Returns

An array of bundles. Each bundle is an object containing information about that bundle.

tripal_get_default_title_format()

tripal_get_default_title_format

(

$bundle

)

Determine the default title format to use for an entity.

Parameters

TripalBundle

$bundle

The Entity object for the Tripal Bundle that the title format is for.

Returns

string A default title format.

tripal_get_entity_tokens()

tripal_get_entity_tokens	(		$bundle,
			$options = []
	)

Returns an array of tokens based on Tripal Entity Fields.

Parameters

TripalBundle

$bundle

The bundle entity for which you want tokens.

Returns

An array of tokens where the key is the machine_name of the token.

tripal_get_title_format()

tripal_get_title_format

(

$bundle

)

tripal_load_bundle_entity()

tripal_load_bundle_entity

(

$values

)

Retrieves a TripalBundle entity that matches the given arguments.

Parameters

$values

An associative array used to match a bundle. Valid keys may: id: the numeric id of the bundle. name: the bundle name (e.g. 'bio_data_234') label: the bundle label (e.g. 'Organism') term_id: the term ID to which the bundle belongs accession: the full accession for the bundle (e.g. OBI:0100026)

Returns

A TripalBundle entity object or NULL if not found.

tripal_load_entity()

tripal_load_entity	(		$entity_type,
			$ids = FALSE,
			$reset = FALSE,
			$field_ids = [],
			$cache = TRUE
	)

tripal_load_term_entity()

tripal_load_term_entity

(

$values

)

Retrieves a TripalTerm entity that matches the given arguments.

Parameters

$values

An associative array used to match a term. Valid keys may be: vocabulary: Must always be used with accession to uniquely identify a term. accession: Must always be used with vocabulary to uniquely identify a term. term_id: Can be used alone to uniquely identify a term.

Returns

A TripalTerm entity object or NULL if not found.

tripal_load_vocab_entity()

tripal_load_vocab_entity

(

$values

)

Retrieves a TripalVocab entity that matches the given arguments.

Parameters

$values

An associative array used to match a vocabulary. The valid keys are: vocab_id: integer id of the vocabulary. vocabulary: string name of vocabulary.

Returns

A TripalVocab entity object or NULL if not found.

tripal_replace_entity_tokens()

tripal_replace_entity_tokens	(		$string,
		&	$entity,
			$bundle_entity = NULL
	)

Replace all Tripal Tokens in a given string.

NOTE: If there is no value for a token then the token is removed.

Parameters

string	$string	The string containing tokens.
TripalEntity	$entity	The entity with field values used to find values of tokens.
TripalBundle	$bundle_entity	The bundle entity containing special values sometimes needed for token replacement.

Returns

The string will all tokens replaced with values.

tripal_save_title_format()

tripal_save_title_format	(		$entity,
			$format
	)

Save Page Title Format for a given Tripal Entity Type.

Parameters

TripalBundle	$entity	The Entity object for the Tripal Bundle the title format is for.
string	$format	The pattern to be used when generating entity titles for the above type.

tripal_set_bundle_variable()

tripal_set_bundle_variable	(		$variable_name,
			$bundle_id,
			$value
	)

Save the value of a tripal variable for a given bundle.

Parameters

string	$variable_name	The name of the variable as in tripal_variables.name.
int	$bundle_id	The unique identifier for the bundle you want the value for.
	$text	$value The value of the variable for the given bundle.

tripal_tripal_cron_notification()

tripal_tripal_cron_notification

(

)

Refreshes the bundle such that new fields added by modules will be found during cron.

Parameters

$bundle_name

The name of the bundle to refresh (e.g. bio_data_4).

tripal_update_bundle_field()

tripal_update_bundle_field	(		$field_name,
			$field_info,
			$entity_type_name,
			$bundle_name
	)

Updates an existing field and its attached instance to a bundle.

Parameters

$field_name	The name of the field.
$field_info	An associative array containing the field information. The following key/value pairs are supported: field_type: a valid field type. May be any of the Drupal default fields, one created by the tripal_chado module or another custom module. widget_type: a valid widget type. May be any of the Drupal default fields, one created by the tripal_chado module or another custom module. field_settings: an array of settings that are appropriate for the selected field type. widget_settings: an array of settings that are appropriate for the selected widget type. description: a default description for this field. label: a label used as a header for this field. is_required: indicates if the field is required in the edit form. cardinality: indicates the number of values this field can support. the default is 1 (meaning only one value). Use a value of FIELD_CARDINALITY_UNLIMITED for unlimited number of values. default_value: A default value for the field. format: A string indicating the format for the field. Must be specific to the field.
$entity_type_name	The entity type name.
$bundle_name	The bundle name.

Returns

FALSE if the field could not be updated

TODO: this function really shouldn't try to create an instance and attach to a bundle at the same time.