Last updated February 7, 2013. Created by drico on September 30, 2012.
Edited by DeFr, jcisio. Log in to edit this page.
Introduction
The atom reference modules provides a field where atoms can be drag and dropped from the library. This allows the user to make a reference from any entity where the field has been inserted to an atom or a list of atoms. This can per example be used to create a media gallery.
PHP
Core hooks used
hook_field_info() :
Define the field information see api documentation.
hook_field_instance_settings_form() :
Field properties for the form when the field is added to an entity. See api documentation.
hook_field_schema() :
Defines the field database column. We use only one, the atom sid. Please see hook field schema
hook_field_validate() :
We check that the referenced atoms type is in the list of type that is allowed for the field.api documentation
hook_field_is_empty() :
We return an empty value. Check api documentation.
hook_field_formatter_info() :
We define scald display context as formatters for the field. Check api documentation.
hook_field_formatter_view() :
We send the rendering of the element thru the scald core function scald_render, passing the display context. See api documentation.
hook_field_widget_info() :
We expose the widget for the entity form. In our case this is a drop box where atoms will be drag and dropped. api documentation.
hook_field_widget_form() :
We first enable the atom library ( library module ) and then define the field item :
<?php
$return['sid'] = $element;
$return['sid']['#description'] .= $help;
$return['sid']['#type'] = 'textfield';
// $options is an array of the referencable atom types in the field.
$return['sid']['#attributes'] = array('data-types' => implode(',', array_keys($options)));
$return['sid']['#default_value'] = isset($items[$delta]) ? $items[$delta]['sid'] : '';
$return['sid']['#process'][] = 'atom_reference_field_widget_form_process';
// Attach our JS and CSS to the element
$path = drupal_get_path('module', 'atom_reference');
$return['sid']['#attached'] = array(
'css' => array($path . '/atom_reference.css'),
'js' => array($path . '/atom_reference.js')
);
return $return;
?>hook_field_widget_error() :
Set a form_set_error message. api documentation.
Views hook
hook_field_views_data() :
This hook is provided by the views module, see views documentation. This allows us to register the atom reference to views.
Function
atom_reference_field_widget_form_process(&$element) :
This is the actual processing of the field. This is launched by
<?php
$return['sid']['#process'][] = 'atom_reference_field_widget_form_process';
?>We send per default the placeholder of the field or the value of the atom in this display context mode :
<?php
$default = $element['#value'];
if ($default) {
$prefix = '<div class="atom_reference_drop_zone">' . scald_render($default, 'sdl_editor_representation') .'</div>';
}
else {
$placeholder = t('Drop a resource here');
$prefix = '<div class="atom_reference_drop_zone"><em>' . $placeholder . '</em></div>';
}
$element['#field_prefix'] = $prefix;
return $element;
?>Javascript
The javascript is located in atom_reference.js.
We define a namespace in drupal behaviors array : Drupal.behaviors.atom_reference.
We mainly manage the field via javascript, appending in editor display context the atom the necessary HTML. We also manage the deletion of an atom.
javascript to append an atom :
$this
// we add a class to show that it is processed
.addClass('atom_reference_processed')
// drag and drop function
.bind('dragover', function(e) {e.preventDefault();})
.bind('dragenter', function(e) {e.preventDefault();})
// on drop
.bind('drop', function(e) {
var dt = e.originalEvent.dataTransfer.getData('Text').replace(/^\[scald=(\d+).*$/, '$1');
var ret = Drupal.atom_reference.droppable(dt, this);
var $this = $(this);
// the atom is good to be dropped in the field
if (ret.found && ret.keepgoing) {
$this
.empty()
//append atom editor representation html
.append(Drupal.dnd.Atoms[dt].editor)
.closest('div.form-item')
.find('input:text')
// add the sclad sid in the form element
.val(dt)
.end()
.find('input:button')
.show();
}