planet

Taking a (Drupal 8) website offline using AppCache

A native mobile application which can cache the data locally is a way to make content available offline. However, not everyone has the time and/or money to create a dedicated app, and frankly, it's not always an additional asset. What if browsers could work without network connection but still serve content: Application Cache and/or Service Workers to the rescue!

For Frontend United 2016, Mathieu and I experimented to see how far we could take AppCache and make the sessions, speakers and some additional content available offline using data from within the Drupal site. There are a couple of pitfalls when implementing this, of which some are nasty (see the list apart link at the bottom for more information). Comes in Drupal which adds another layer of complexity, with its dynamic nature of content and themes. Javascript and css aggregation is also extremely tricky to get right. So after trial and error and a lot of reading, we came up with the following concept:

  1. Only add the manifest attribute to all "offline" pages which are completely separate from "online pages", even though they might serve the same content. In other words, you create a sandboxed version of some content of your site which can live on its own. Another technique is a hidden iframe which loads a page which contains the html tag with the manifest attribute. You can embed this iframe on any page you like. This gives you the option to create a page where you link to as an opt-in to get a site offline. Both techniques give us full control and no side affects so that when network is available the site works normally.
  2. You define the pages which you want to store in the cache. They are served by Drupal, but on a different route than the original (e.g. node/1 becomes offline/node/1) and use different templates. These are twig templates so you can override the defaults to your own needs. Other information like stylesheet and javascript files can be configured too to be included.
  3. The manifest thus contains everything that we need to create the offline version when your device has no network connection. In our case, it contains the list of speakers and sessions, content pages and some assets like javascript, stylesheet, logo and images.

Offline in the browser or on the homescreen

Go to the Offline homepage of Frontend United and wait until the 'The content is now available offline!' message appears, which means you just downloaded 672 kb of data - it is really really small, surprising no? Now switch off your network connection and reload the browser: still there! Click around and you'll be able to check the offline version at any time. If you're on a mobile device, the experience can be even sweeter: you can add this page to your homescreen, making it available as an 'app'. On iOS, you need to open the app once while still being connected to the network. We really do hope safari/iOS fixes this behavior since this is not necessary on Android. After that, turn off your network and launch the app again. Oh, and it works on a watch too if you have a browser on it. If that isn't cool, we don't know what else is! We have a little video to show you how it looks like. Watch (pun intended) and enjoy! Oh, in case we make changes to the pages, you will see a different notification telling you that the content has been updated - if your device has network of course.

Drupal integration

We've created a new project on Drupal.org, called Offline App, available for Drupal 8. The project contains the necessary code and routes for generating the appcache, iframe, pages (nodes and views) and settings to manipulate the manifest content. 3 new regions are exposed in which you can place the content for offline use. Those regions are used in offline-app-page.html.twig - but any region is available if you want to customize. Two additional view modes are created for content types and the read more link can be made available in the 'Offline teaser' mode. Formatters are available for long texts to strip internal links and certain tags (e.g. embed and iframe) and for images that will make sure that 'Link to content' is pointing to the 'Offline path'. Last, but not least, an 'Offline' Views display is available for creating lists. We're still in the process in making everything even more flexible and less error-prone when configuring the application. However, the code that is currently available, is used as is on the Fronted United website right now.

This module does not pretend to be the ultimate solution for offline content, see it as an example to quickly expose a manifest containing URL's from an existing Drupal installation for an offline version of your website. Other Drupal projects are available trying to integrate with AppCache or Service workers, however, some are unsupported or in a very premature state, apart from https://www.drupal.org/project/pwa. Note that I've been in contact with Théodore already and we'll see how we combine our efforts for coming up with one single solution instead of having multiple ones.

What about service workers ?

Not all browsers support the API yet. Even though AppCache is marked deprecated, we wanted to make sure everyone could have the same offline experience. However, we'll start adding support for service workers soon using the same concept.

We're also planning to start experimenting with delivering personal content as well, since that's also possible, yet a little trickier.

Links

Note: closed the comments for now as anti-spam modules are not doing their job nicely

Drupal 8 Field API series part 4: entity (form) displays and display modes

This is part 4 of the Drupal 8 Field API series. We skipped part 3 about field types as the dust hasn't settled yet in terms of API changes. Once we get there, we'll make sure we'll talk about the massive changes that have happened in that area.

In this part, we'll talk about new API's which are, strictly speaking, not part anymore of Field API, they now belong to the Entity Field API. However, the reason the changes exist, directly comes out of a big problem in Drupal 7 in Field API: scattered storage.

Entity display

In Drupal 7, parameters controlling how to render the various "parts" of an entity view in a given view mode were scattered in many separate locations:

  • in $instance['display'] for each individual (Field API) field in the bundle
  • in the 'field_bundle_settings_[entity_type]_[bundle]' variable for the 'extra fields' in the bundle
  • in other places for contrib additions that are not one of the two above (most notably field_group module)

In Drupal 8, all those parameters ("options") for all those parts ("components") are centralised in one single EntityViewDisplay configuration object - which means they can be deployed with CMI - for each entity bundle and view mode. You can access these objects with the entity_get_display() function. All available methods can be found in EntityDisplayInterface.

<?php
entity_get_display
('node', 'article', 'default')
 
// Set 'component_1' to be visible, with weight 1.
 
->setComponent('component_1', array(
   
'weight' => 1,
  ))
 
// Set 'component_2' to be hidden.
 
->removeComponent('component_2')
  ->
save();
?>

Also new in D8 is that all entity and field rendering hooks now receive this EntityDisplay object as a parameter. This means you have direct access to the configuration in your functions, instead of having to figure them out by calling functions to get the definition of field instances, extra fields or other configurations. For the full list of all hooks affected, scroll to the resources part at then end of this article for the change record link.

<?php
function hook_node_view(Node $node, EntityDisplay $display, $view_mode, $langcode) {
  if (
$display->getComponent('mymodule_addition')) {
   
$node->content['mymodule_addition'] = array(
     
'#markup' => mymodule_addition($node),
     
'#theme' => 'mymodule_my_additional_field',
    );
  }
}
?>

Note that currently only Field API fields and extra fields are handled by the EntityViewDisplay object. This is going to change when we introduce component type plugins so everyone will be able to store and access configuration. For more information, follow https://drupal.org/node/1875974.

Entity form display

Just like with the display settings, form settings are scattered all over the place:

  • in $instance['widget'] for each individual (Field API) field in the bundle
  • in the 'field_bundle_settings_[entity_type]_[bundle]' variable for the 'extra fields' in the bundle
  • in other places for contrib additions that are not one of the two above (most notably field_group module)

In Drupal 8, all those parameters ("options") for all those parts ("components") are centralised in one single EntityFormDisplay configuration object for each entity bundle and form mode.This object uses the same EntityDisplayInterface as the EntityViewDisplay object. The consequence of this API is the birth of the counterpart of view modes: form modes.

The direct use case for this was the hacky workaround in Drupal 7 for showing Field API fields on the user registration page. In Drupal 8, you can now configure which fields are available on the user registration page or the edit page. However, more interesting possibilities with this new API will certainly pop up when Drupal 8 is released, most notable inline entity forms.

UI impact

In Drupal 7, the place to manage the fields and control the order in forms is done on the 'manage fields' screen. In Drupal 8, this has has been split out in the 'manage fields' and the 'manage form display' screens. Widget settings are now also managed on this new screen, which allows you to have different widget settings depending on the form mode. The form displays screen also have a 'hidden' region, which allows you to hide certain fields on certain form modes.

Display modes

Drupal 7 has the concept of 'view modes', previously build modes in D6. In D8, we now also have form modes and both of them are configuration entities. Drupal 8 also ships with a UI to manage these display modes. You do not have to rely anymore on contributed modules like 'View modes' or 'Display Suite'.

Resources

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.

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.

Pages

Subscribe to RSS - planet

You are here