Adding New Source

This page will cover adding a new DVF Source plugin, this is where DVF gets the data from and then hands it off to visualisation styles for display

Basics for a new source

For a DVF source plugin to be registered, the following needs to be done at a minimum:

• A PHP class that extends Drupal\dvf\Plugin\Visualisation\Source\VisualisationSourceBase exists in the following directory MY_MODULE/src/Plugin/Visualisaion/Source/
• The class must implement Drupal\dvf\Plugin\Visualisation\VisualisationSourceInterface
• The class comments contain the appropriate annotations for @VisualisationSource

Example

namespace Drupal\my_module\Plugin\Visualisation\Source;

use Drupal\dvf\Plugin\Visualisation\Source\VisualisationSourceBase;
use Drupal\dvf\Plugin\Visualisation\VisualisationSourceInterface;

/**
 * Plugin implementation of the 'dvf_awesome_source' visualisation source.
 *
 * @VisualisationSource(
 *   id = "dvf_awesome_source",
 *   label = @Translation("Awesome Source"),
 *   category = @Translation("AwesomeSource"),
 *   visualisation_types = {
 *     "dvf_file",
 *     "dvf_url"
 *   }
 * )
 */
class AwesomeSource extends VisualisationSourceBase implements VisualisationSourceInterface {
  ...
}

This should be enough for it to appear under "Visualisation source" on the field settings for a DVF field.

DVF Source responsibilities

A DVF source is responsible for retrieving the data records, normalising/parsing records, defining fields, caching and defining any associated settings required to do these tasks. Key methods your class should implement are:

• public function settingsForm(array $form, FormStateInterface $form_state) which returns the settings form required for your source.
• public function getFields() which returns the fields used by visualisations. Eg in a CSV this would be the header row, or in a JSON file, this would be the object properties for each item in the array.
• public function getRecords() Which is responsible for returning a parsed array of records (data) that will be passed to the visualisation style. Eg in a CSV this would be the rows, presented as an array.

Have a look at VisualisationSourceInterface for further documentation these plugin methods.

Examples

If you are developing a new DVF source, we recommend you have a look at the three sources that come bundled with DVF. Each demonstrates different ways data may be retrieved, parsed and cached.

• DVF CSV
• DVF JSON
• DVF CKAN