tripal_chado.pub_importers.inc File Reference

Functions
	tripal_pub_importers_list ()
	tripal_pub_importer_setup_page ($action='new', $pub_import_id=NULL)
	tripal_pub_importer_setup_form ($form, &$form_state=NULL, $pub_import_id=NULL, $action='new')
	tripal_pub_importer_ncbi_api_key_form ($form, $form_state)
	tripal_pub_importer_set_ncbi_api_key ($form, $form_state)
	tripal_pub_importer_setup_add_criteria_fields (&$form, &$form_state, $num_criteria, $criteria)
	tripal_pub_setup_form_ajax_button_validate ($form, &$form_state)
	tripal_pub_setup_form_ajax_button_submit ($form, &$form_state)
	tripal_pub_importer_setup_form_validate ($form, &$form_state)
	tripal_pub_importer_setup_form_submit ($form, &$form_state)
	tripal_pubs_setup_form_ajax_update ($form, $form_state)
	theme_tripal_pub_importer_setup_form_elements ($variables)
	tripal_pub_importer_submit_job ($import_id)
	tripal_pub_importer_delete ($import_id)
	tripal_pub_add_publications ($pubs, $do_contact, $update=FALSE, $job=NULL)
	tripal_pub_add_publication ($pub_details, &$action, $do_contact=FALSE, $update_if_exists=FALSE, $job=NULL)
	tripal_pub_add_authors ($pub_id, $authors, $do_contact)
	tripal_pub_get_publication_array ($pub_id, $skip_existing=TRUE)
	tripal_get_remote_pub ($dbxref)
	tripal_get_remote_pubs ($remote_db, $search_array, $num_to_retrieve, $page=0)
	tripal_pub_citation_form ($form, &$form_state)
	tripal_pub_citation_form_submit (&$form_state)

Detailed Description

Management of importers

Function Documentation

theme_tripal_pub_importer_setup_form_elements()

theme_tripal_pub_importer_setup_form_elements

(

$variables

)

Theme the tripal_pub_importer_setup_form form.

tripal_get_remote_pub()

tripal_get_remote_pub

(

$dbxref

)

This function is used to perfom a query using one of the supported databases and return the raw query results. This may be XML or some other format as provided by the database.

Parameters

$dbxref

The unique database ID for the record to retrieve. This value must be of the format DB_NAME:ACCESSION where DB_NAME is the name of the database (e.g. PMID or AGL) and the ACCESSION is the unique identifier for the record in the database.

Returns

Returns the publication array or FALSE if a problem occurs

tripal_get_remote_pubs()

tripal_get_remote_pubs	(		$remote_db,
			$search_array,
			$num_to_retrieve,
			$page = 0
	)

Retrieves a list of publications as an associated array where keys correspond directly with Tripal Pub CV terms.

Parameters

remote_db

The name of the remote publication database to query. These names should match the name of the databases in the Chado 'db' table. Currently supported databass include 'PMID': PubMed

search_array

An associate array containing the search criteria. The following key are expected 'remote_db': Specifies the name of the remote publication database 'num_criteria': Specifies the number of criteria present in the search array 'days': The number of days to include in the search starting from today 'criteria': An associate array containing the search critiera. There should be no less than 'num_criteria' elements in this array.

The following keys are expected in the 'criteria' array 'search_terms': A list of terms to search on, separated by spaces. 'scope': The fields to search in the remote database. Valid values include: 'title', 'abstract', 'author' and 'any' 'operation': The logical operation to use for this criteria. Valid values include: 'AND', 'OR' and 'NOT'.

Parameters

$num_to_retrieve	The number of records to retrieve. In cases with large numbers of records to retrieve, the remote database may limit the size of each retrieval.
$page	Optional. If this function is called where the page for the pager cannot be set using the $_GET variable, use this argument to specify the page to retrieve.

Returns

Returns an array of pubs where each element is an associative array where the keys are Tripal Pub CV terms.

tripal_pub_add_authors()

tripal_pub_add_authors	(		$pub_id,
			$authors,
			$do_contact
	)

Add one or more authors to a publication

Parameters

$pub_id	The publication ID of the pub in Chado.
$authors	An array of authors. Each author should have a set of keys/value pairs describing the author.
$do_contact	Optional. Set to TRUE if a contact entry should be added to the Chado contact table for authors of the publication.

tripal_pub_add_publication()

tripal_pub_add_publication	(		$pub_details,
		&	$action,
			$do_contact = FALSE,
			$update_if_exists = FALSE,
			$job = NULL
	)

Adds a new publication to Chado.

In addition, all properties and database cross-references. If the publication does not already exist in Chado then it is added. If it does exist nothing is done. If the $update parameter is TRUE then the publication is updated if it exists.

Parameters

$pub_details	An associative array containing all of the details about the publication.
$action	This variable will get set to a text value indicating the action that was performed. The values include 'skipped', 'inserted', 'updated' or 'error'.
$do_contact	Optional. Set to TRUE if a contact entry should be added to the Chado contact table for authors of the publication.
$update_if_exists	Optional. If the publication already exists then this function will return without adding a new publication. However, set this value to TRUE to force the function to pudate the publication using the $pub_details that are provided.
$job	The jobs management object for the job if this function is run as a job. This argument is added by Tripal during a job run and is not needed if this function is run directly.

Returns

If the publication already exists, is inserted or updated then the publication ID is returned, otherwise FALSE is returned. If the publication already exists and $update_if_exists is not TRUE then the $action variable is set to 'skipped'. If the publication already exists and $update_if_exists is TRUE and if the update was successful then $action is set to 'updated'. Otherwise on successful insert the $action variable is set to 'inserted'. If the function fails then the $action variable is set to 'error'

tripal_pub_add_publications()

tripal_pub_add_publications	(		$pubs,
			$do_contact,
			$update = FALSE,
			$job = NULL
	)

Adds publications that have been retrieved from a remote database and consolidated into an array of details.

Parameters

$pubs	An array containing a list of publications to add to Chado. The array contains a set of details for the publication.
$do_contact	Set to TRUE if authors should automatically have a contact record added to Chado.
$update	If set to TRUE then publications that already exist in the Chado database will be updated, whereas if FALSE only new publications will be added
$job	The jobs management object for the job if this function is run as a job. This argument is added by Tripal during a job run and is not needed if this function is run directly.

Returns

Returns an array containing the number of publications that were inserted, updated, skipped and which had an error during import.

tripal_pub_citation_form()

tripal_pub_citation_form	(		$form,
		&	$form_state
	)

The admin form for submitting job to create citations

Parameters

$form_state

tripal_pub_citation_form_submit()

tripal_pub_citation_form_submit

(

&

$form_state

)

Submit form. Create Tripal job for citations

Parameters

$form_state

tripal_pub_get_publication_array()

tripal_pub_get_publication_array	(		$pub_id,
			$skip_existing = TRUE
	)

This function generates an array suitable for use with the tripal_pub_create_citation function for any publication already stored in the Chado tables.

Parameters

$pub_id	The publication ID
$skip_existing	Set to TRUE to skip publications that already have a citation in the pubprop table. Set to FALSE to generate a citation regardless if the citation already exists.

Returns

An array suitable for the trpial_pub_create_citation function. On failure returns FALSE.

tripal_pub_importer_delete()

tripal_pub_importer_delete

(

$import_id

)

Deletes a publication importer.

tripal_pub_importer_ncbi_api_key_form()

tripal_pub_importer_ncbi_api_key_form	(		$form,
			$form_state
	)

The form used for setting the optional NCBI API key.

Parameters

$form	The form element to be populated.
$form_state	The state of the form element to be populated.

Returns

array The populated form element.

tripal_pub_importer_set_ncbi_api_key()

tripal_pub_importer_set_ncbi_api_key	(		$form,
			$form_state
	)

This function saves the NCBI API key to the database.

It is called when the user makes a change to the NCBI API key field and then moves their cursor out of the field.

Parameters

$form	The new form element.
$form_state	The state of the new form element.

Returns

array The new api key field.

tripal_pub_importer_setup_add_criteria_fields()

tripal_pub_importer_setup_add_criteria_fields	(	&	$form,
		&	$form_state,
			$num_criteria,
			$criteria
	)

A helper function for the importer setup form that adds the criteria to the form that belong to the importer.

Parameters

$form	The form
$form_state	The form state
$num_criteria	The number of criteria that exist for the importer
$criteria	An array containing the criteria

Returns

A form array

tripal_pub_importer_setup_form()

tripal_pub_importer_setup_form	(		$form,
		&	$form_state = NULL,
			$pub_import_id = NULL,
			$action = 'new'
	)

The form used for creating publication importers.

Parameters

$form	The Drupal form
$form_state	The form state
$pub_import_id	The publication importer ID
$action	The action to perform

Returns

A form array

tripal_pub_importer_setup_form_submit()

tripal_pub_importer_setup_form_submit	(		$form,
		&	$form_state
	)

Submit the tripal_pub_importer_setup_form form

tripal_pub_importer_setup_form_validate()

tripal_pub_importer_setup_form_validate	(		$form,
		&	$form_state
	)

Validate the tripal_pub_importer_setup_form form

tripal_pub_importer_setup_page()

tripal_pub_importer_setup_page	(		$action = 'new',
			$pub_import_id = NULL
	)

Creates the page that contains the publication importer setup form and test results.

Parameters

$action	The action to perform
$pub_import_id	The importer ID

Returns

The HTML for the importer setup page

tripal_pub_importer_submit_job()

tripal_pub_importer_submit_job

(

$import_id

)

Add a job to import publications

Parameters

$pub_importer_id

The id of the importer to submit a job to update

tripal_pub_importers_list()

tripal_pub_importers_list

(

)

A function to generate a table containing the list of publication importers

tripal_pub_setup_form_ajax_button_submit()

tripal_pub_setup_form_ajax_button_submit	(		$form,
		&	$form_state
	)

This function is just a dummy to override the default form submit on ajax calls for buttons

tripal_pub_setup_form_ajax_button_validate()

tripal_pub_setup_form_ajax_button_validate	(		$form,
		&	$form_state
	)

This function is used to rebuild the form if an ajax call is made vai a button. The button causes the form to be submitted. We don't want this so we override the validate and submit routines on the form button. Therefore, this function only needs to tell Drupal to rebuild the form

tripal_pubs_setup_form_ajax_update()

tripal_pubs_setup_form_ajax_update	(		$form,
			$form_state
	)

AJAX callback for updating the form.