An open source app for DrupalCon Prague

DrupalCon Prague is approaching fast. In a few days, Drupal folks from all over the world will gather together in Prague to sprint, attend sessions, have fun etc. A few days ago, I was searching to see whether there was a mobile application available and turns out it wasn't. So me and a friend volunteered to create one based on the DrupalCamp app we've created a few weeks ago. They might be basic, but they do the job fine when you quickly want to check the schedule of the whole week.

The apps will be available for Android and iOS. The Android version is available on Play Store, the iOS version is currently in review, so fingers crossed!

Features include:

  • Built with speed in mind: native app
  • Works offline
  • Sessions and speakers
  • Create your schedule
    Note, does not sync with your account.
  • Maps integration when online

Collaborate

The code is available on GitHub, so anyone can easily send in bug reports, interface translations or create pull requests to make the applications even better. You can of course reuse and/or extend the code for future DrupalCons.

Proudly built by @swentel, @TimLeytens and @leenvs.

It's time to create an album

There was a time that I was a tiny rock star. At least in Gent. I played in a band, we even made into Humo's Rock Rally once, but got friendly declined to enter the next round. Then, real life starts and you forget a rehearsal or two, ending up alone again in your room. Just like you were 14 again, practicing chords on your first guitar. Nothing is wrong with that, but one piece is missing: an album.

From today on, I'm taking some months off from working professionally and will start recording songs and try and create my first album. And by the time it's released, I can start a new career. Simple plan right ?

Life after work

I'll be scheduling my time in a practical way so I've got time to help landing the remaining big patches for Drupal 8, together with the awesome Field API team. So don't worry, you will still see me in the queue. I might just paste some partial lyrics. And you'll find me at DrupalCon Prague where I'll be at the core sprints, probably trying out songs now and then while hacking.

Apart from that, I'll be travelling a lot, chilling in the garden reading books that have been waiting for me since ages or following some courses on Coursera. Life is just going to be extremely sweet the next following months.

For now, quoting one my best friends: rock on!

Topics 

music

An open source app for DrupalCamps

On september 14 and 15, Leuven will host the annual Belgium DrupalCamp. During those two days, people come together learning and discussing the open-source content management system Drupal. The program will be available on the website, but we decided to also create an application this year. We've tried to make it abstract as possible, so other Drupal events can easily built from the source code which is available online.

The apps will be available for Android and iOS. As soon as the program is ready, we'll publish them, so keep an eye out for the camp website, twitter or, of course, this article. The Android version is available on Play Store.

Features include:

  • Built with speed in mind: native app
  • Works offline
  • Sessions and speakers
  • Mark your favorite sessions
  • Maps integration when online

Collaborate

The code is freely available on GitHub, so anyone can easily send in bug reports, interface translations or create pull requests to make the applications even better.

Proudly built by @swentel, @TimLeytens and @leenvs.

So, who will make the Windows mobile and Firefox version ?

Drupal 8 Field API series part 2: field widgets

In the first article of the Drupal 8 Field API series, we saw how field formatters are written in Drupal 8. Now it's time for widgets. You might get a déjà vu when reading as a lot resemble to formatters.

Plugins

Creating field widgets in Drupal 7 was done by implementing four hooks. In Drupal 8, widgets are now plugins using the new Plugin API. Hooks are replaced by methods in classes, which means that your module file will be empty if you only provide a widget, unless you also implement one of the (new) widget alter hooks. Being classes, this means that field widgets can now extend on each other. A good example in core is the image field widget extending the file field widget class. Discovery and class instantiation is managed by the new widget plugin manager.

Create a file like '{your_module}/lib/Drupal/{your_module}/Plugin/field/FieldWidget/{NameOfYourWidget}.php. That's a lot of directories right ? Welcome to the world of PSR-0, namespaces and plugins in D8. This is most likely going to change, feel free to read, or even help along in https://drupal.org/node/1971198. Also, plugin managers can control where plugins reside, see https://drupal.org/node/2043379, so we'll probably change this at some point.

In most cases, you will want to extend the WidgetBase class which does most of the heavy lifting for you (holds the code that was in the field_default_*() functions in Drupal 7). Following classes will usually be imported at the top of your file depending on which methods you override:

<?php
// WidgetBase class.
use Drupal\Core\Field\WidgetBase;
// FieldItemListInterface
use Drupal\Core\Field\FieldItemListInterface;
// Symfone violation interface
use Symfony\Component\Validator\ConstraintViolationInterface;
?>

1. hook_field_widget_info() are now annotations

hook_field_widget_info() is replaced by annotation-based plugin discovery, using the \Drupal\field\Annotation\FieldWidget annotation class. As for other plugin types, the accepted properties are documented in the annotation class. Other modules can extend this by implementing hook_field_widget_info_alter(). Note that some property names have changed since Drupal 7 (spaces replaces by underscores). This is how an annotation looks like, which is placed right above the class keyword.

<?php
/**
* Plugin implementation of the 'foo_widget' widget
*
* @FieldWidget(
*   id = "foo_widget",
*   label = @Translation("Foo widget"),
*   field_types = {
*     "text",
*     "text_long"
*   },
*   settings = {
*     "size" = "600",
*   }
* )
*/
class FooWidget extends WidgetBase { }
?>

2. hook_field_widget_settings_form() becomes WidgetInterface::settingsForm()

Next up is to create a settingsForm() method. If you have an old settings form, you can simply move the code to this method. The calling code (typically Field UI) takes care of saving the settings on form submit. Remember to always start with an empty $elements array and not with the $form argument from the function arguments.

Side note: in all methods in the widget class:

  • the settings values currently configured for the widget can be accessed with $this->getSetting('settings_key'), or $this->getSettings()
  • the settings values currently configured for the field on which the widget is being used can be accessed with $this->getSetting('settings_key'), or $this->getSettings(). Those methods return both field level settings and instance level settings, merged.
  • If access to field properties other than field settings is needed, the field definition can be accessed with $this->getFieldDefinition(). This returns an object implementing \Drupal\Core\Entity\Field\FieldDefinitionInterface, which unifies the separate $field and $instance structures D7 coders are familiar with. More details on this will come in a following post.

<?php
 
/**
   * {@inheritdoc}
   */
 
public function settingsForm(array $form, array &$form_state) {
   
$element = array();

   
$element['size'] = array(
     
'#type' => 'number',
     
'#title' => t('Size of textfield'),
     
'#default_value' => $this->getSetting('size'),
     
'#required' => TRUE,
     
'#min' => 1,
    );

    return
$element;
  }
?>

3. hook_field_widget_form becomes WidgetInterface::formElement()

This is where you return the widget form. Also, the methods now receive the field values as a \Drupal\Core\Field\FieldItemListInterface object, rather than an $items array in Drupal 7. More information can be found about Drupal 8 Entity API and the syntax around field values in the handbook. Simply put, FieldInterface objects can be accessed and iterated on like an array of items keyed by delta, and properties in each item can be accessed by simple object syntax.

<?php
 
/**
   * {@inheritdoc}
   */
 
public function formElement(FieldItemListInterface $items, $delta, array $element, array &$form, array &$form_state) {
   
$main_widget = $element + array(
     
'#type' => 'textfield',
     
'#default_value' => isset($items[$delta]->value) ? $items[$delta]->value : NULL,
     
'#size' => $this->getSetting('size'),
     
'#placeholder' => $this->getSetting('placeholder'),
     
'#maxlength' => $this->getSetting('max_length'),
     
'#attributes' => array('class' => array('text-full')),
    );

    if (
$this->getSetting('text_processing')) {
     
$element = $main_widget;
     
$element['#type'] = 'text_format';
     
$element['#format'] = isset($items[$delta]->format) ? $items[$delta]->format : NULL;
     
$element['#base_type'] = $main_widget['#type'];
    }
    else {
     
$element['value'] = $main_widget;
    }

    return
$element;
  }
?>

4. hook_field_widget_error becomes WidgetInterface::errorElement()

The second parameter, $violation, contains the list of constraint violations reported during the validation phase. In Drupal 8, the Sympony contraints class is used to validate objects, whether doing this programmatically or through a form. We won't go deeper into this for now. In the next article, when we'll talk about the field types, this will become much clearer. Just remember for now that validation should not happen in your widgets, but in constraints.

<?php
 
/**
   * {@inheritdoc}
   */
 
public function errorElement(array $element, ConstraintViolationInterface $violation, array $form, array &$form_state) {
    return
$element[$violation->arrayPropertyPath[0]];
  }
?>

5. WidgetInterface::settingsSummary()

This is a new method which resembles FormatterInterface::settingsSummary(). With the introduction of form modes in D8, a given field can be displayed with different widgets in the different form modes used by the entity type. This method is used to output the settings currently configured for the widget in Field UI screens, just like you do with field formatters - try to keep it short :-).

<?php
 
/**
   * {@inheritdoc}
   */
 
public function settingsSummary() {
   
$summary = array();

   
$summary[] = t('Textfield size: !size', array('!size' => $this->getSetting('size')));
   
$placeholder = $this->getSetting('placeholder');
    if (!empty(
$placeholder)) {
     
$summary[] = t('Placeholder: @placeholder', array('@placeholder' => $placeholder));
    }

    return
$summary;
  }
?>

6. WidgetInterface::massageFormValues()

This is a new method which you should only implement if you need todo complex FAPI tricks when a form is submitted. This lets you turn the raw submitted form values produced by your widget into the "regular" format expected for field values. Examples in core are the taxonomy autocomplete widget and the file widget which need todo additional processing when a form is submitted.

Alter hooks

Besides the existing hook_field_widget_info_alter, two new hooks are introduced allowing you to alter widget settings form or summary on Field UI, which behave almost the same like field formatter alter hooks: hook_field_widget_settings_form and hook_field_widget_settings_summary_alter.

Resources

Conclusion

Like formatters, writing and maintaining field widgets for Drupal 8 is not hard. In most cases, when porting, it's simply moving the contents of your old hooks to the methods in a class. In the next part, we will see how you write field type plugins in Drupal 8.

Drupal 8 Field API series part 1: field formatters

The Drupal 8 cycle has entered the API freeze since the 1st of July, which means it's time to start porting modules or simply play around with the API. While there are exceptions to change the API, you can safely assume that 95% (or even more) will remain as it is today.

This is the first article which will be part of a series of changes in Field API for Drupal 8: field formatters. In case there are updates to the API, we will update the articles, but also the change records on drupal.org. Watch out for the next couple of weeks and months and hopefully you're prepared for Drupal 8 and Field API.

Plugins

Creating field formatters in Drupal 7 was done by implementing four hooks. In Drupal 8, formatters are now plugins using the new Plugin API. Hooks are replaced by methods in classes, which means that your module file will be empty if you only provide a formatter (unless you also implement one of the field formatter alter hooks). Being classes, this means that field formatters can now extend on each other. A good example in core is the image field formatter extending the file field formatter class. Discovery and class instantiation is managed by the new formatter plugin manager.

Create a file like '{your_module}/lib/Drupal/{your_module}/Plugin/field/FieldFormatter/{NameOfYourFormatter}.php. That's a lot of directories right ? Welcome to the world of PSR-0, namespaces and plugins in D8. This is most likely going to change, feel free to read, or even help along in https://drupal.org/node/1971198. Also, plugin managers can now control where plugins reside, see https://drupal.org/node/2043379, so we'll probably change this at some point.

In most cases, you will want to extend the FormatterBase class which does most of the heavy lifting for you. Following classes will usually be imported at the top of your file:

<?php
// FormatterBase class.
Drupal\Core\Field\FormatterBase;
// FieldItemInterface
use Drupal\Core\Field\FieldItemListInterface;
?>

1. hook_field_formatter_info() are now annotations

hook_field_formatter_info() is replaced by annotation-based plugin discovery, using the \Drupal\field\Annotation\FieldFormatter annotation class. As for other plugin types, the accepted properties are documented in the annotation class. Other modules can extend this by implementing hook_field_formatter_info_alter(). In core, the edit module adds the edit property so it knows which in-place editor it has to use. Note that some property names have changed since Drupal 7 (spaces replaces by underscores). This is how an annotation looks like, which is placed right above the class keyword.

<?php
/**
* Plugin implementation of the 'foo_formatter' formatter
*
* @FieldFormatter(
*   id = "foo_formatter",
*   label = @Translation("Foo formatter"),
*   field_types = {
*     "text",
*     "text_long"
*   },
*   settings = {
*     "trim_length" = "600",
*   },
*    edit = {
*      "editor" = "form"
*    }
* )
*/
class FooFormatter extends FormatterBase { }
?>

2. hook_field_formatter_settings_form() becomes FormatterInterface::settingsForm()

Next up is to create a settingsForm() method. If you have an old settings form, you can simply move the code to this method. Settings are automatically saved and can be accessed by calling $this->getSetting('settings_key');. Remember to always start with an empty $elements array and not with the $form argument from the function arguments.

<?php
 
/**
   * {@inheritdoc}
   */
 
public function settingsForm(array $form, array &$form_state) {
   
$element = array();

   
$element['trim_length'] = array(
     
'#title' => t('Trim length'),
     
'#type' => 'number',
     
'#default_value' => $this->getSetting('trim_length'),
     
'#min' => 1,
     
'#required' => TRUE,
    );

    return
$element;
  }
?>

3. hook_field_formatter_settings_summary() becomes FormatterInterface::settingsSummary()

Settings are accessed by calling $this->getSetting('settings_key');. Another change is that the summary now needs to return an array instead of a string.

<?php
 
/**
   * {@inheritdoc}
   */
 
public function settingsSummary() {
   
$summary = array();
   
$summary[] = t('Trim length: @trim_length', array('@trim_length' => $this->getSetting('trim_length')));
    return
$summary;
  }
?>

4. hook_field_formatter_prepare_view becomes FormatterInterface::prepareView() and hook_field_formatter_view() becomes FormatterInterface::viewElements()

The first method allows you to add additional information on the items, the second is where the actual formatting happens. Settings are accessed by calling $this->getSetting('settings_key');. Also, the methods now receive the field values as a \Drupal\Core\Field\FieldItemListInterface object, rather than an $items array in Drupal 7. More information can be found about Drupal 8 Entity API and the syntax around field values in the handbook. Simply put, FieldItemListInterface objects can be accessed and iterated on like an array of items keyed by delta, and properties in each item can be accessed by simple object syntax.

<?php
 
/**
   * {@inheritdoc}
   */
 
public function viewElements(FieldItemListInterface $items) {
   
$elements = array();

   
$text_processing = $this->getSetting('text_processing');
    foreach (
$items as $delta => $item) {
      if (
$this->getPluginId() == 'text_summary_or_trimmed' && !empty($item->summary)) {
       
$output = $item->summary_processed;
      }
      else {
       
$output = $item->processed;
       
$output = text_summary($output, $text_processing ? $item->format : NULL, $this->getSetting('trim_length'));
      }
     
$elements[$delta] = array('#markup' => $output);
    }

    return
$elements;
  }
?>

Alter hooks

The alter hooks are still the same for Drupal 8, with one small API change in hook_field_formatter_settings_summary_alter() which is invoked by the Field UI module. The summary is now an array of strings instead of a single string. <br/> will be automatically inserted between the strings when the summary is displayed.

<?php
/**
* Implements hook_field_formatter_settings_summary_alter().
*/
function my_module_field_formatter_settings_summary_alter(&$summary, $context) {
 
// Append a message to the summary when an instance of foo_formatter has
  // mysetting set to TRUE for the current view mode.
 
if ($context['formatter']->getPluginId() == 'foo_formatter') {
    if (
$context['formatter']->getSetting('mysetting')) {
     
$summary[] = t('My setting enabled.');
    }
  }
}
?>

The other two hooks are hook_field_formatter_info_alter() allowing you to make changes to the formatter definitions and hook_field_formatter_settings_form_alter() which is invoked from by the Field UI module when displaying the summary of the formatter settings for a field.

Resources

Conclusion

Writing and maintaining field formatters for Drupal 8 is not hard. In most cases, when porting, it's simply moving the contents of your old hooks to the methods in a class. In the next part, we will see how you write widget plugins in Drupal 8.

Pages

Subscribe to realize.be RSS