In this post, we go over on how to create, handle and display a custom fields in Drupal. In addition, we look on situations when your custom field contains an artifacts that requires an additional care
The hook_field_schema() defines the columns. The table will be only added after an actual field is created(attached to content type). So, if you like to see if the data is being added for the custom field, look into table ‘field_xxx’
The hook_field_shema() needs to be define and declared in the module .install file as following:
function NAME-OF-SCHEMA_field_schema($field) {
$schema = array();
$schema['columns']['class'] = array(
'type' => 'varchar',
'length' => 50,
'not null' => FALSE
);
$schema['columns']['image'] = array(
'description' => 'The {file_managed}.fid being referenced in this field.',
'type' => 'int',
'not null' => FALSE,
'unsigned' => TRUE,
);
$schema['foreign keys'] = array(
'image_fid' => array(
'table' => 'file_managed',
'columns' => array('image' => 'fid'),
),
);
return $schema;
}
In the above example, a schema of 2 fields are created. One of the fields are a file upload, so there is additional foreign constrain defined.
Test from PHP Execute block
$field = field_info_field('field_designssquare_slider_layer');
module_load_install('field_designssquare_slider_layer');
$schema = (array) module_invoke('field_designssquare_slider_layer', 'field_schema', $field);
Look into Watchdog logs for a message. You should see the message if the install was performed
The columns can also be checked in the table ‘field_NAME_OF_FIELD’ in database
Specify Display
You may like to create a display format for the custom field. The field display gives user ability to select display for the field. Developer can take it and create separate layout via custom theme functions wrapped into template file
To declare display:
/**
* Implements hook_field_formatter_info().
*/
function videojs_field_formatter_info() {
return array(
'videojs' => array(
'label' => t('Video.js : HTML5 Video Player'),
'field types' => array('file', 'media', 'link_field'),
'description' => t('Display a video file as an HTML5-compatible with Flash-fallback video player.'),
'settings' => array(
'width' => NULL,
'height' => NULL,
'posterimage_field' => NULL,
'posterimage_style' => NULL,
),
),
);
}
The ‘field types’ specify to which types the display is available. The ‘settings’ is custom parameter passed to the display(will cover later). So, this declares the display available for user to specify from UI. Next, lets implement the display:
/**
* Implements hook_field_formatter_view().
*/
function videojs_field_formatter_view($entity_type, $entity, $field, $instance, $langcode, $items, $display) {
if ($display['type'] !== 'videojs') {
return array();
}
if (empty($items)) {
return array();
}
if ($field['type'] == 'link_field') {
//for field type of 'link_field' do things differently
}
$settings = $display['settings'];
$attributes = array();
if (!empty($settings['width']) && !empty($settings['height'])) {
$attributes['width'] = intval($settings['width']);
$attributes['height'] = intval($settings['height']);
}
list($id, $vid, $bundle) = entity_extract_ids($entity_type, $entity);
return array(
array(
'#theme' => 'videojs',
'#items' => $items,
'#player_id' => 'videojs-' . $id . '-' . str_replace('_', '-', $instance['field_name']),
'#attached' => videojs_add(FALSE),
'#entity' => $entity,
'#entity_type' => $entity_type,
'#attributes' => $attributes,
'#posterimage_style' => !empty($settings['posterimage_style']) ? $settings['posterimage_style'] : NULL,
),
);
}
The display formatter calls a custom function declared as following:
function videojs_theme() {
return array(
'videojs' => array(
'variables' => array('items' => NULL, 'player_id' => NULL, 'attributes' => NULL, 'entity' => NULL, 'entity_type' => NULL, 'posterimage_style' => NULL),
'template' => 'theme/videojs',
),
}
Here, the theme custom function used for rendering display is declared. This theme custom function uses a template file ‘theme/videojs’ to render output, but before that the hook_preprocess_CUSTOM-THEME-FUNC is called, so the variables can be preprocessed.
Render the Display
To render specified display as following:
$video_render_array = field_view_field(
'node',
$entity,
'field_video_file',
array(
'type' => 'videojs',
'label' => 'hidden',
'settings' => array(
'width' => '300',
'height' => '400',
'posterimage_field' => NULL,
'posterimage_style' => NULL,
),
)
);
$content = render($video_render_array);
Here the field ‘field_video_file’ uses a display ‘jw_player’ that takes one parameter jwplayer_preset. Afterwards, the renderable array returned from the display is being rendered.
Create Custom Field Type
To declare custom field type use hook_field_info() as following:
function MODULE-NAME_field_info() {
return array(
'OUR_CUSTOM_FIELD_NAME' => array(
'label' => t('Slide Layer'),
'description' => t('field containing info about one of the layers part of the Rev Slider'),
'settings' => array('max_length' => 255),
'instance_settings' => array(
'text_processing' => 0,
),
'default_widget' => 'OUR_CUSTOM_FIELD_NAME_widget',
'default_formatter' => 'OUR_CUSTOM_FIELD_NAME_formatter',
),
);
}
Besides name and description, the default widget and formatter is specified. Next, lets declare and implement the widget for this field type :
/**
* Implements hook_field_widget_info().
* Expose Field API widget types.
*/
function MODULE-NAME_field_widget_info() {
return array(
'OUR_CUSTOM_WIdGET_NAME' => array(
'label' => t('Revolution Slide Layer'),
'field types' => array('OUR_CUSTOM_FIELD_NAME'),
),
);
}
The widget name is given and assigned to our custom field type – OUR_CUSTOM_FIELD_NAME via ‘field types’. After declaring the widget, lets specify the form for user to enter values:
/**
* Implements hook_field_widget_form().
*/
function MODULE-NAME_field_widget_form(&$form, &$form_state, $field, $instance, $langcode, $items, $delta, $element) {
$element += array(
'#type' => $instance['widget']['type'],
'#default_value' => isset($items[$delta]) ? $items[$delta] : '',
);
return $element;
}
/**
* Implements hook_element_info().
* Declare the field Form API element types and specify their default values.
*/
function MODULE-NAME_element_info() {
$elements = array();
$elements['OUR_CUSTOM_WIdGET_NAME'] = array(
'#input' => TRUE,
'#process' => array('designssquare_rev_slider_layer_field_process')
);
return $elements;
}
In the function hook_field_widget_form(), it specifies the widget type, so we can use hook_element_info for specifying form. Afterwards, the hook_element_info() is used to specify function returning the renderable array with columns of the schema from the .install file
At last, the widget form is specified:
function designssquare_rev_slider_layer_field_process($element, $form_state, $complete_form) {
$element['layer_header'] = array(
'layer_header' => array(
'#type' => 'markup',
'#weight' => 0,
'#markup' => '<p>' . t('Slide Layer '.($element['#delta'] + 1)) . '</p>',
),
);
$element['image'] = array(
'#title' => t('Image'),
'#type' => 'managed_file',
'#weight' => 8,
'#description' => t('Upload a file, allowed extensions: jpg, jpeg, png, gif'),
'#default_value' => isset($element['#value']['image']) ? $element['#value']['image'] : '',
'#upload_location' => REV_SLIDER_DEST.'/img',
'#states' => array(
'visible' => array(
// ':input[title="content_choice_'.$element['#delta'].'"]' => array('value' => 'image'),
':input[name="content_choice['.$element['#delta'].']"]' => array('value' => 'image'),
),
),
'#upload_validators' => array(
'file_validate_extensions' => array('jpg jpeg png gif'),
// Pass the maximum file size in bytes
'file_validate_size' => array(MAX_SIZE_LIMIT_DS*1024*1024),
),
);
// To prevent an extra required indicator, disable the required flag on the
// base element since all the sub-fields are already required if desired.
$element['#required'] = FALSE;
return $element;
}
We still have to declare and implement hook_field_is_empty($item, $field), so it know when the field is considered to be empty
function MODULE-NAME_field_is_empty($item, $field)
{
return !isset($item);
}
Here, we tell that empty is when no instance of our custom field is present
Validating Custom Field Values
To validate the custom field, we first register our custom validation function via hook_formt_alter():
function MODULE-NAME_form_alter(&$form, &$form_state, $form_id)
{
switch ($form_id) {
case 'OUR-FORM-ID':
//assign validation
$form['#validate'][] = 'some_custom_validate';
//assign submition
$form['#submit'][] = 'some_custom_submit';
break;
}
}
Since this is a general hook, we filter out only the form of our interest. (For finding Form ID, please, see post ‘Forms In Drupal Overview‘). Afterwards, we specify our custom function for validating the form
Next, the validation logic is declared:
function some_custom_validation(){
if(empty($form_state['values']['some_field']['und'])){
form_set_error('some_field[und]', t("error message comes here"));
}
On validation, our custom validation function is being called in which we perform validation for our custom field values
Handling Artifacts For Custom Field
If your custom field contains files, then there is extra care of keeping them permanent as well as removed on deletion. In the above section “Validating Custom Field Values”, we registered our submission processor function. By default all artifacts via file_manage is saved temporary. Next, we ensure the artifacts are permanent on creation and deleted on the remove event:
function some_custom_submit($form, &$form_state)
{
if ((isset($form_state['clicked_button']) && $form_state['clicked_button']['#value'] == "Delete")) {
//custom field needs to be deleted
//remove artifact image
$file = file_load(['values']['our_custom_field']['image']);
if ($file) {
file_delete($file);
file_usage_delete($file, 'MODULE-NAME');
}
} else {
//custom field needs to be added
//make permanent image file
$file = file_load(['values']['our_custom_field']['image']);
if ($file) {
// Change status to permanent.
$file->status = FILE_STATUS_PERMANENT;
//all permanent files needs an entry in the 'file_usage' table
$id = (isset($form_state['node']->nid)) ? $form_state['node']->nid : 0;
file_usage_add($file, 'MODULE-NAME', $form_state['node']->type, $id);
// Save.
file_save($file);
}
}
}
}
First, we check to see if the node is being deleted or created. Afterwards, we load the artifact and make it permanent or remove it if being deleted
See post ‘Handling Assets For Custom Module In Drupal’ for how to automize artifact import/export
Handling Multiple Instances of Custom Field
In case, user chooses your custom field to be more than one time for specific node, then there is module field_remove_item that allows easy for them to remove any of the instance, however. You will have to handle the artifacts again. That easy to do via hook_field_validate()
function MODULE-NAME_field_validate($entity_type, $entity, $field, $instance, $langcode, $items, &$errors)
{
//remove artifacts on 'remove item' bottom
foreach ($items as $key => $item) {
//see if any of the layers is selected to be deleted
if ($item['field_remove_item']) {
//remove image
$file = file_load($item['image']);
if ($file) {
file_delete($file);
file_usage_delete($file, 'MODULE-NAME');
}
}
}
}
Here, we loop through each instance of your custom field since we don’t know exactly which of the one is being removed. The instance with field ‘field_remove_item’ set, is the one we have to remove artifacts, so we have if statement following with standard way of removing asset managed with manage_file
Uninstalling Custom Fields
If you developed a custom field and installed as a separate module than it will create a lock where you will not be able to uninstall the module. There are two solutions that i am aware. The quick and dirty is to update table ‘fields_config’ to remove the dependency. Another solution is to create a separate module for the purpose to run uninstall hook during which it removes the field, thus, removing the lock so it becomes available to be uninstalled. Lets look at the last solution
Here is the hook_uninstall() for uninstalling the custom module:
function MODULE-NAME_uninstall()
{
//remove fields from content types
foreach(_get_bundles_for_field_type('CUSTOM-FIELD-TYPE') as $bundle){
field_attach_delete_bundle('node', $bundle);
drupal_set_message('uninstalled field for bundle:'.$bundle);
}
//remove tables
drupal_uninstall_schema('CUSTOM-FIELD-SCHEMA');
// remove variables
db_query("DELETE FROM {variable} WHERE name LIKE 'CUSTOM-FIELD-SCHEMA_%'");
// Remove assets.
// file_unmanaged_delete_recursive(file_default_scheme() . '://slider');
// Clear the cache.
field_info_cache_clear();
}
The function ‘_get_bundles_for_field_type’ returns all the bundles referencing the custom field. Afterwards, we use field_attach_delete_bundle API To remove our custom field type as well as all of its instances. Next the schema is removed, the variables deleted and files removed. At last, we clear the cache
Here is the implementation of _get_bundles_for_field_type():
//returns all the bundles of entity instances that references a field instance with a given type
function _get_bundles_for_field_type($field_type)
{
$field_map = field_info_field_map();
$bundles = array();
foreach ($field_map as $field_name => $item) {
if ($item['type'] == $field_type) {
foreach ($item['bundles'] as $bundle_list) {
foreach ($bundle_list as $bundle) {
$bundles[] = $bundle;
}
}
}
}
return array_unique($bundles);
}
Render The Field
…
Troubleshooting
1. PDOException: SQLSTATE[23000]: Integrity constraint violation: 1062 Duplicate entry ‘public://some/path/img.jpg’ for key ‘uri’: INSERT INTO {file_managed}
This issue came up when our custom field was a file and by reinstalling the field it created a duplicate entry in the manage_file table. The solution was clean file_manage table when instance with our custom field was delete
//clean file_manage database on field instance delete
function MODULE-NAME_node_delete($node){
if($node->type == 'CERTAIN-TYPE'){
//removes images from file_manage/file_usage tables
$field_instance = field_get_items('node', $node, 'field_FIELED-NAME');
foreach($field_instance as $key => $instance){
$file = file_load($instance['image']);
file_delete($file);
file_usage_delete($file, 'MODULE-NAME');
...
}
The hook-node_delete($node) is called when any node is being deleted. Here, in line 5, we look up our custom fields for the node being deleted and then clean the file entry in file_manage and file_usage tables.
This also removes the images from Drupal public directory(by default sites/default/files). We did made files being copied when module is being enabled:
function MODULE-NAME_uuid_node_features_rebuild_alter(&$node, $module){
...
$source = _get_source_file($final_file->uri);
file_unmanaged_copy($source, $final_file->uri);
...
}
function _get_source_file($uri){
$source = drupal_get_path('module','MODULE-NAME').'/imports/public/'.substr($uri, 9);
if(!file_exists($source)){
watchdog(WATCHDOG_NOTICE, 'MODULE-NAME Import: Image does not exists at '.$source);
}
return $source;
}
The hook_uuid_node_features_rebuild_alter is covered in the article Make Custom Field With File Exportable In Drupal Features. We just extend it with file transfer when module feature is being enabled. In highlighted line, we copy from predefined location to a Drupal public folder.
See also post “Handling Artifacts for Custom Module In Drupal” for solution on handling assets such as images, files
2. Drupal claim “Field type(s) in use”
This message is displayed when you would like to disable the module but Drupal doesn’t permit. To solve problem, go to ‘field_config’ table and update the ‘type’ and ‘module’ text for your custom field. More info on the issue https://drupal.org/node/1284380
Fields pending deletion
This comes up after the custom field is removed but the chrom job run only once which is not sufficient. It needs to run several times.
Reference:
- http://clikfocus.com/blog/how-set-custom-field-type-using-drupal-7-fields-api
- http://drewpull.drupalgardens.com/blog/drupal-7-field-api-sample
- http://drupaltutorial4u.blogspot.com/2011/04/how-to-create-custom-field-for-drupal-7.html
- https://drupal.org/project/examples
- http://drewpull.drupalgardens.com/blog/drupal-7-custom-field-formatter
- http://drupal.stackexchange.com/questions/49958/hook-field-schema-does-not-work
- http://nodesforbreakfast.com/article/2012/02/24/create-custom-form-api-elements-hookelementinfo-drupal-7
- https://api.drupal.org/api/drupal/includes%21database%21schema.inc/group/schemaapi/7
- http://www.slideshare.net/zugec/fields-in-core-how-to-create-a-custom-field