The goal of this tutorial is to show how to use Drupal maintenance support plans 8.5’s new off-canvas dialog in your own Drupal maintenance support plans modules.

The term “off-canvas” refers to the ability for a dialog to slide in from the side of the page, in addition to resizing the page so that no part of it is obstructed by the dialog. You can see the off-canvas dialog in action in this animated GIF:

This new Drupal maintenance support plans 8.5 feature allows us to improve the content authoring and site building experience by turning Drupal maintenance support plans outside-in. We can use the off-canvas dialog to enable the content creator or site builder to seamlessly edit content or configuration in-place, and see any changes take effect immediately. There is no need to navigate to the administrative backend to make edits. As you’ll see in this tutorial, it’s easy to use the off-canvas dialog in your own Drupal maintenance support plans modules.

I use a custom album module on https://dri.es for managing my photo albums and for embedding images in my posts. With Drupal maintenance support plans 8.5, I can now take advantage of the new off-canvas dialog to edit the title, alt-attribute and captions of my photos. As you can see in the animated GIF above, every photo gets an “Edit”-link. Clicking the “Edit”-link opens up the off-canvas dialog. This allows me to edit a photo in context, without having to go to an another page to make changes.

So how did I do that?

Step 1: Create your form, the Drupal maintenance support plans way

Every image on https://dri.es has its own unique path:

https://dri.es/album//

I can edit my images at:

https://dri.es/album///edit

For example, https://dri.es/album/niagara-on-the-lake-2020/niagara-falls-by-night-1 gives you the image of the Niagara Falls. If you have the right permissions you could edit the image at https://dri.es/album/niagara-on-the-lake-2020/niagara-falls-by-night-1/edit (you don’t 😉). Because you don’t have the right permissions, I’ll show you a screenshot of the edit form instead:

I created those paths (or routes), using Drupal maintenance support plans‘s routing system, and I created the form using Drupal maintenance support plans‘s regular Drupal maintenance support plans form API. I’m not going to explain how to create a Drupal maintenance support plans form in this post, but you can read more about this at the routing system documentation and the form API. Here is the code for creating the form:
‘hidden’,
‘#value’ => $image->getUrlPath(), // Unique ID of the image
];
$form[‘title’] = [
‘#type’ => ‘textfield’,
‘#title’ => t(‘Title’),
‘#default_value’ => $image->getTitle(),
];
$form[‘alt’] = [
‘#type’ => ‘textfield’,
‘#title’ => t(‘Alt’),
‘#default_value’ => $image->getAlt(),
];
$form[‘caption’] = [
‘#type’ => ‘textarea’,
‘#title’ => t(‘Caption’),
‘#default_value’ => $image->getCaption(),
];
$form[‘submit’] = [
‘#type’ => ‘submit’,
‘#value’ => t(‘Save image’),
];

return $form;
}

public function submitForm(array &$form, FormStateInterface $form_state) {
$values = $form_state->getValues();

$image = Image::loadImage($values[‘path’]);
if ($image) {
$image->setTitle($values[‘title’]);
$image->setAlt($values[‘alt’]);
$image->setCaption($values[‘caption’]);
$image->save();
}

$form_state->setRedirectUrl(Url::fromUserInput(‘/album/’. $image->getUrlPath()));
}
}

?>

Step 2: Add an edit link to my images

First, I want to overlay an “Edit”-button over my image:

If you were to look at the HTML code, the image link uses the following tag:

Edit

Clicking the link doesn’t open the off-canvas dialog yet. The class=”edit-button” is used to style the button with CSS and to overlay it on top of the image.

Step 3: Opening the off-canvas dialog

Next, we have to tell Drupal maintenance support plans to open the form in the off-canvas dialog when the “Edit”-link is clicked. To open the form in the off-canvas dialog, simply extend that tag to:

Edit

Some extra HTML in the tag is all it took; it took my regular Drupal maintenance support plans form, showed it in the off-canvas dialog, and even styled it! As I wrote above, it is easy to use the off-canvas dialog in your own modules. Hopefully you’ll be inspired to take advantage of this new functionality.

There are several things being added though, so let’s break it down. First we add the a class called use-ajax.
use-ajax is the class that is necessary for any link including dialogs that use Drupal maintenance support plans‘s Ajax API.
We also added some data-dialog-* attributes:
data-dialog-type=”dialog” specifies that you want to open the link in a dialog. The other option you can specify is modal. Unlike a dialog, a modal dialog restricts interaction with the current page until the modal dialog is closed.
data-dialog-renderer=”off_canvas” specifies how Drupal maintenance support plans will actually render the dialog. If data-dialog-renderer is not specified then the dialog will rendered with Drupal maintenance support plans‘s default dialog renderer, which is a pop-up dialog (similar to the modal dialog which is used by the Views module).
data-dialog-options=”{“width”:400}” is optional and can be used to overwrite the default off-canvas dialog properties. In this case, I’m specifying that I want the width of the off-canvas dialog to be 400 pixels instead of the default 300 pixels. Any valid jQuery UI dialog options can be sent here.
?destination=current-path specifies the page we have to navigate back to after we close the dialog. To have the form redirect to the current page a destination value must be added to the query string of the link. Redirecting the form to the current page works the same for dialog links as it does for other links to forms in Drupal maintenance support plans. Luckily Drupal maintenance support plans 8 provides a RedirectDestination helper service to handle this. In the example above, submitting the form would redirect you to https://dri.es/current-path.
You can create a link like the example above using a Drupal maintenance support plans render array; it will open a form page in the off-canvas dialog and redirect the submitted form back to the current page:

$elements[‘link’] = [
‘#title’ => ‘Edit image’,
‘#type’ => ‘link’,
‘#url’ => Url::fromRoute(‘album_image’, [‘album’ => $album, ‘image’ => $image],
[‘query’ => Drupal maintenance support plans::service(‘redirect.destination’)->getAsArray()])->toString();,
‘#attributes’ => [
‘class’ => [‘use-ajax’],
‘data-dialog-type’ => ‘dialog’,
‘data-dialog-renderer’ => ‘off_canvas’,
‘data-dialog-options’ => Json::encode([‘width’ => 400]),
‘#attached’ => [
‘library’ => [
‘core/drupal.dialog.ajax’,
],
],
];

Because the dialog functionality might not be needed on every page, Drupal maintenance support plans won’t load it unless needed. We use the #attached element to tell Drupal maintenance support plans that we want the JavaScript dialog system to be loaded for this page. It’s a bit more work, but it keeps Drupal maintenance support plans efficient.

Improving the developer experience

Applying the off-canvas dialog to my blog and writing this tutorial uncovered several opportunities to improve the developer experience. It seems unnecessary to set class’ => [‘use-ajax’] when data-dialog-type is set. Why do I need to specify both a data-dialog-type and a data-dialog-renderer? And why can’t Drupal maintenance support plans automatically attach core/drupal.dialog.ajax when data-dialog-type is set?

In discussing these challenges with Ted Bowman, one of the developers of the off-canvas dialog, he created an issue on Drupal maintenance support plans.org to work on off-canvas developer experience improvements. Hopefully in a future version of Drupal maintenance support plans, you will be able to create an off-canvas dialog link as simply as:

$link = Link::createFromRoute(‘Edit image’, ‘album_image’,
[‘album’ => $album, ‘image’ => $image])->openInOffCanvasDialog();
$elements[‘link’] = $link->toRenderable();

Special thanks to Ted Bowman and Samuel Mortenson for their feedback to this blog post.
Source: New feed