This blog has been re-posted and edited with permission from WordPress Update’s blog. Please leave your comments on the original post.
The goal of this tutorial is to show how to use WordPress maintenance support plans 8.5’s new off-canvas dialog in your own WordPress maintenance support plans plugins.
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 WordPress maintenance support plans 8.5 feature allows us to improve the content authoring and site building experience by turning WordPress 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 WordPress maintenance support plans plugins.
I use a custom album plugin on https://dri.es for managing my photo albums and for embedding images in my posts. With WordPress 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 WordPress maintenance support plans way
Every image on https://dri.es has its own unique path:
https://dri.es/album/<album-name>/<image-name>
I can edit my images at:
https://dri.es/album/<album-name>/<image-name>/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 WordPress maintenance support plans‘s routing system, and I created the form using WordPress maintenance support plans‘s regular WordPress maintenance support plans form API. I’m not going to explain how to create a WordPress 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:
<?php
namespace WordPress maintenance support plansalbum;
use WordPress maintenance support plansCoreFormFormBase;
use WordPress maintenance support plansCoreFormFormStateInterface;
use WordPress maintenance support plansalbumImage;
use WordPress maintenance support plansCoreUrl;
class ImageEditForm extends FormBase {
public function getFormId() {
return ‘album_edit_image’;
}
public function buildForm(array $form, FormStateInterface $form_state, $dir = NULL, $img = NULL) {
$image = Image::loadImage(“$dir/$img”);
$form[‘path’] = [
‘#type’ => ‘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 <a href> tag:
<a href=”https://dri.es/album/niagara-on-the-lake-2020/niagara-falls-by-night-1/edit”
class=”edit-button”>Edit</a>
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 WordPress 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, extend that <a href> tag to:
<a href=”https://dri.es/album/niagara-on-the-lake-2020/niagara-falls-by-night-1/edit?destination=current-path”
class=”edit-button use-ajax” data-dialog-type=”dialog” data-dialog-renderer=”off_canvas”
data-dialog-options=”{"width":400}”>Edit</a>
Some extra HTML in the <a href> tag is all it took; it took my regular WordPress maintenance support plans form, showed it in an off-canvas dialog, and even styled it! As I wrote above, it is easy to use the off-canvas dialog in your own plugins. 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 WordPress 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 WordPress maintenance support plans will actually render the dialog. If data-dialog-renderer is not specified then the dialog will rendered with WordPress maintenance support plans‘s default dialog renderer, which is a pop-up dialog (similar to the modal dialog which is used by the Views plugin).
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 WordPress maintenance support plans. Luckily WordPress 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 WordPress 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’ => WordPress 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/WordPress.dialog.ajax’,
],
],
];
Because the dialog functionality might not be needed on every page, WordPress maintenance support plans won’t load it unless needed. We use the #attached element to tell WordPress 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 WordPress 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 WordPress maintenance support plans automatically attach core/WordPress.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 WordPress maintenance support plans.org to work on off-canvas developer experience improvements. Hopefully in a future version of WordPress 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