Tripal
Public Member Functions | Static Public Member Functions | Static Public Attributes | Protected Member Functions | Protected Attributes | List of all members
TripalImporter Class Reference
Inheritance diagram for TripalImporter:
Inheritance graph
[legend]

Public Member Functions

 __construct (TripalJob $job=NULL)
 
 setJob (TripalJob $job)
 
 create ($run_args, $file_details=[])
 
 load ($import_id)
 
 submitJob ()
 
 prepareFiles ()
 
 cleanFile ()
 
 logMessage ($message, $variables=[], $severity=TRIPAL_INFO)
 
 form ($form, &$form_state)
 
 formSubmit ($form, &$form_state)
 
 formValidate ($form, &$form_state)
 
 run ()
 
 postRun ()
 
 getArguments ()
 

Static Public Member Functions

static byID ($import_id)
 

Static Public Attributes

static $name = 'Tripal Loader'
 
static $machine_name = 'tripal_loader'
 
static $description = 'A base loader for all Tripal loaders'
 
static $file_types = []
 
static $upload_description = ''
 
static $upload_title = 'File Upload'
 
static $use_analysis = TRUE
 
static $require_analysis = TRUE
 
static $button_text = 'Import File'
 
static $use_button = TRUE
 
static $methods
 
static $file_required = TRUE
 
static $argument_list = []
 
static $cardinality = 1
 
static $menu_path = ''
 
static $callback = ''
 
static $callback_module = ''
 
static $callback_path = ''
 

Protected Member Functions

 setTotalItems ($total_items)
 
 addItemsHandled ($num_handled)
 
 setItemsHandled ($total_handled)
 
 setInterval ($interval)
 

Protected Attributes

 $job
 
 $arguments
 
 $import_id
 
 $is_prepared
 
 $reported = 0
 

Constructor & Destructor Documentation

◆ __construct()

TripalImporter::__construct ( TripalJob  $job = NULL)

Instantiates a new TripalImporter object.

Parameters
TripalJob$jobAn optional TripalJob object that this loader is associated with.

Member Function Documentation

◆ addItemsHandled()

TripalImporter::addItemsHandled (   $num_handled)
protected

Adds to the count of the total number of items that have been handled.

Parameters
$num_handled

◆ byID()

static TripalImporter::byID (   $import_id)
static

Instantiates a new TripalImporter object using the import record ID.

This function will automatically instantiate the correct TripalImporter child class that is appropriate for the provided ID.

Parameters
$import_idThe ID of the import recrod.
Returns
An TripalImporter object of the appropriate child class.

◆ cleanFile()

TripalImporter::cleanFile ( )

Cleans up any temporary files that were created by the prepareFile().

This function should be called after a run() to remove any temporary files and keep them from building up on the server.

◆ create()

TripalImporter::create (   $run_args,
  $file_details = [] 
)

Creates a new importer record.

Parameters
$run_argsAn associative array of the arguments needed to run the importer. Each importer will have its own defined set of arguments.
$file_detailsAn associative array with one of the following keys: -fid: provides the Drupal managed File ID for the file. -file_local: provides the full path to the file on the server. -file_remote: provides the remote URL for the file. This argument is optional if the loader does not use the built-in file loader.
Exceptions
Exception

◆ form()

TripalImporter::form (   $form,
$form_state 
)

Provides form elements to be added to the loader form.

These form elements are added after the file uploader section that is automaticaly provided by the TripalImporter.

Returns
A $form array.

Reimplemented in TaxonomyImporter, OBOImporter, NewickImporter, GFF3Importer, and FASTAImporter.

◆ formSubmit()

TripalImporter::formSubmit (   $form,
$form_state 
)

Handles submission of the form elements.

The form elements provided in the implementation of the form() function can be used for special submit if needed.

Reimplemented in OBOImporter.

◆ formValidate()

TripalImporter::formValidate (   $form,
$form_state 
)

Handles validation of the form elements.

The form elements provided in the implementation of the form() function should be validated using this function.

Reimplemented in TaxonomyImporter, OBOImporter, NewickImporter, GFF3Importer, and FASTAImporter.

◆ getArguments()

TripalImporter::getArguments ( )

Retrieves the list of arguments that were provided to the importer.

Returns
The array of arguments as passed to create function.

◆ load()

TripalImporter::load (   $import_id)

Loads an existing import record into this object.

Parameters
$import_idThe ID of the import record.

◆ logMessage()

TripalImporter::logMessage (   $message,
  $variables = [],
  $severity = TRIPAL_INFO 
)

Logs a message for the importer.

There is no distinction between status messages and error logs. Any message that is intended for the user to review the status of the loading can be provided here. If this importer is associated with a job then the logging is passed on to the job for storage.

Messages that are are of severity TRIPAL_CRITICAL or TRIPAL_ERROR are also logged to the watchdog.

Parameters
$messageThe message to store in the log. Keep $message translatable by not concatenating dynamic values into it! Variables in the message should be added by using placeholder strings alongside the variables argument to declare the value of the placeholders. See t() for documentation on how $message and $variables interact.
$variablesArray of variables to replace in the message on display or NULL if message is already translated or not possible to translate.
$severityThe severity of the message; one of the following values:
  • TRIPAL_CRITICAL: Critical conditions.
  • TRIPAL_ERROR: Error conditions.
  • TRIPAL_WARNING: Warning conditions.
  • TRIPAL_NOTICE: Normal but significant conditions.
  • TRIPAL_INFO: (default) Informational messages.
  • TRIPAL_DEBUG: Debug-level messages.

◆ postRun()

TripalImporter::postRun ( )

Performs the import.

Reimplemented in OBOImporter.

◆ prepareFiles()

TripalImporter::prepareFiles ( )

Prepares the importer files for execution.

This function must be run prior to the run() function to ensure that the import file is ready to go.

◆ run()

TripalImporter::run ( )

Performs the import.

Reimplemented in TaxonomyImporter, OBOImporter, NewickImporter, GFF3Importer, and FASTAImporter.

◆ setInterval()

TripalImporter::setInterval (   $interval)
protected

Updates the percent interval when the job progress is updated.

Updating the job progress incurrs a database write which takes time and if it occurs to frequently can slow down the loader. This should be a value between 0 and 100 to indicate a percent interval (e.g. 1 means update the progress every time the num_handled increases by 1%).

Parameters
$intervalA number between 0 and 100.

◆ setItemsHandled()

TripalImporter::setItemsHandled (   $total_handled)
protected

Sets the number of items that have been processed.

This should be called anytime the loader wants to indicate how many items have been processed. The amount of progress will be calculated using this number. If the amount of items handled exceeds the interval specified then the progress is reported to the user. If this loader is associated with a job then the job progress is also updated.

Parameters
$total_handledThe total number of items that have been processed.

◆ setJob()

TripalImporter::setJob ( TripalJob  $job)

Associate this importer with the Tripal job that is running it.

Associating an import with a job will allow the importer to log messages to the job log.

Parameters
TripalJob$jobAn instance of a TripalJob.

◆ setTotalItems()

TripalImporter::setTotalItems (   $total_items)
protected

Sets the total number if items to be processed.

This should typically be called near the beginning of the loading process to indicate the number of items that must be processed.

Parameters
$total_itemsThe total number of items to process.

◆ submitJob()

TripalImporter::submitJob ( )

Submits the importer for execution as a job.

Returns
The ID of the newly submitted job.

Member Data Documentation

◆ $argument_list

TripalImporter::$argument_list = []
static

The array of arguments used for this loader. Each argument should be a separate array containing a machine_name, name, and description keys. This information is used to build the help text for the loader.

◆ $arguments

TripalImporter::$arguments
protected

The arguments needed for the importer. This is a list of key/value pairs in an associative array.

◆ $button_text

TripalImporter::$button_text = 'Import File'
static

Text that should appear on the button at the bottom of the importer form.

◆ $callback

TripalImporter::$callback = ''
static

If your importer requires more flexibility and advanced features than the TripalImporter provides, you can indicate a callback function. If set, the callback will be used to provide the importer interface to the end-user. However, because this bypasses the class infrastructure the run() function will also not be available and your importer must be fully self-sufficient outside of this class. The benefit for using a TripalImporter despite your loader being self-sufficient is that Tripal will treat your loader like all others providing a consistent location in the menu and set of permissions.

Note: use of a callback is discouraged as the importer provides a consistent workflow for all importers. Try your best to fit your importer within the class. Use this if you absolutely cannot fit your importer into TripalImporter implementation.

◆ $callback_module

TripalImporter::$callback_module = ''
static

The name of the module that provides the callback function.

◆ $callback_path

TripalImporter::$callback_path = ''
static

An include path for the callback function. Use a relative path within this scope of this module (e.g. includes/loaders/tripal_chado_pub_importers).

◆ $cardinality

TripalImporter::$cardinality = 1
static

Indicates how many files are allowed to be uploaded. By default this is set to allow only one file. Change to any positive number. A value of zero indicates an unlimited number of uploaded files are allowed.

◆ $description

TripalImporter::$description = 'A base loader for all Tripal loaders'
static

A brief description for this loader. This description will be presented to the site user.

◆ $file_required

TripalImporter::$file_required = TRUE
static

Indicates if the file must be provided. An example when it may not be necessary to require that the user provide a file for uploading if the loader keeps track of previous files and makes those available for selection.

◆ $file_types

TripalImporter::$file_types = []
static

An array containing the extensions of allowed file types.

◆ $import_id

TripalImporter::$import_id
protected

The ID for this import record.

◆ $is_prepared

TripalImporter::$is_prepared
protected

Prior to running an importer it must be prepared to make sure the file is available. Preparing the importer will download all the necessary files. This value is set to TRUE after the importer is prepared for funning.

◆ $job

TripalImporter::$job
protected

The job that this importer is associated with. This is needed for updating the status of the job.

◆ $machine_name

TripalImporter::$machine_name = 'tripal_loader'
static

The machine name for this loader. This name will be used to construct the URL for the loader.

◆ $menu_path

TripalImporter::$menu_path = ''
static

Be default, all loaders are automaticlly added to the Admin > Tripal > Data Loaders menu. However, if this loader should be made available via a different menu path, then set it here. If the value is empty then the path will be the default.

◆ $methods

TripalImporter::$methods
static
Initial value:
= [
'file_upload' => TRUE,
'file_local' => TRUE,
'file_remote' => TRUE,
]

Indicates the methods that the file uploader will support.

◆ $name

TripalImporter::$name = 'Tripal Loader'
static

The name of this loader. This name will be presented to the site user.

◆ $require_analysis

TripalImporter::$require_analysis = TRUE
static

If the $use_analysis value is set above then this value indicates if the analysis should be required.

◆ $upload_description

TripalImporter::$upload_description = ''
static

Provides information to the user about the file upload. Typically this may include a description of the file types allowed.

◆ $upload_title

TripalImporter::$upload_title = 'File Upload'
static

The title that should appear above the upload button.

◆ $use_analysis

TripalImporter::$use_analysis = TRUE
static

If the loader should require an analysis record. To maintain provenance we should always indicate where the data we are uploading comes from. The method that Tripal attempts to use for this by associating upload files with an analysis record. The analysis record provides the details for how the file was created or obtained. Set this to FALSE if the loader should not require an analysis when loading. if $use_analysis is set to true then the form values will have an 'analysis_id' key in the $form_state array on submitted forms.

◆ $use_button

TripalImporter::$use_button = TRUE
static

If the form submit button that is provided by the Importer is not needed (i.e. the child class wants to do something different). Then set this to FALSE.


The documentation for this class was generated from the following file: