Introduction
Design Sections
Canvas
Table
Toolbar Commands
Commands
Shortcuts
Developers
Shortcut
- Interface
- Init
- Destroy
- Activate
- Keys
- Registration
Command

Shortcut

Do you think a new shortcut would be helpful for your restaurant? You can follow these guidelines to create your own shortcut.

Within this documentation we will treat how to create a shortcut to clone the tables. In case of selected tables, the shortcut will clone these ones, in case of none selection, only the last table will be cloned.

Download from HERE the complete example file.

Interface

A shortcut is represented by an abstract class named UIShortcut, which needs the implementation of a few methods.

class UIShortcut {

	init(canvas) {
		// inherit in children classes
	}

	destroy() {
		// inherit in children classes
	}

	activate(canvas) {
		// inherit in children classes
	}

	getShortcut() {
		// inherit in children classes
	}

}

The name of the class we need to extend must start with UIShortcut and should continue with a descriptive name. In our case, the class will be named UIShortcutDuplicate.

/**
 * Shortcut Duplicate class.
 */
class UIShortcutDuplicate extends UIShortcut {

	/**
	 * @todo methods implementation goes here
	 */

}

Initialise

Every time a shortcut is registered within the canvas, the init() method is invoked in order to prepare the shortcut.

The init() method receives the current instance of UICanvas as parameter, the object used to handle the drawing area.

The init() method doesn't need to return any values.

This method is invoked only once.

In our case, we don't need to implement this method. Anyhow here's an example of implementation.

init(canvas) {
	console.log('[UIShortcutDuplicate] initialized on: ' + new Date());
}

Destroy

Every time a shortcut is deregistered from the canvas, the destroy() method is invoked in order to clean some junk data.

By default, the system never deregisters any shortcuts. They can be deregistered by using the UICanvas::unregisterShortcut(UIShortcut shortcut) method. This method is available for customizations that require to unset other shortcuts. For example, it is possible to temporarily unregister a specific shortcut at runtime.

The destroy() method doesn't receive any parameters. In case the UICanvas argument is needed, it is possible to assign it to an internal property while initialising this object.

The destroy() method doesn't need to return any values.

This method is invoked only once.

In our case, we don't need to implement this method. Anyhow here's an example of implementation.

init(canvas) {
	// keep a reference to canvas instance
	this.canvas = canvas;

	// turn off copy when this shortcut is active
	for (var i = 0; i < canvas.shortcuts.length; i++) {
		if (canvas.shortcuts[i].constructor.name == 'UIShortcutCopy') {
			// keep reference to the shortcut instance that needs to be removed
			this.removedShortcut = canvas.shortcuts[i];
			// unregister shortcut and exit
			this.canvas.unregisterShortcut(this.removedShortcut);
			return;
		}
	}
}

destroy() {
	// someone tried to unregister our class, we need to restore copy shortcut
	if (this.removedShortcut) {
		// register again the shortcut that was unregistered while initialising this object
		this.canvas.registerShortcut(this.removedShortcut);
	}
}

Activation

The activate() method is invoked every time the specified combination of keys is pressed. The shortcut combination can be defined through the getShortcut() method.

The activate() method receives the current instance of UICanvas as parameter, the object used to handle the drawing area.

The activate() method doesn't need to return any values.

Here's what our shortcut should do when the combination of keys is triggered.

activate(canvas) {
	// get selected shapes
	var selection = canvas.getSelection();

	if (selection.length == 0) {
		// no selected shapes, find the last added shape
		var lastKey = Object.keys(canvas.shapes).pop();

		if (!lastKey) {
			// no tables found, raise an error and exit
			canvas.statusBar.display('Nothing to duplicate', {translate: true});
			return;
		}

		// push the shape within the selection array
		selection.push(canvas.shapes[lastKey]);
	}

	// paste the selected elements
	canvas.paste(selection);
}

Shortcut Keys

In order to be activated, a shortcut needs to define a specific combination of keys. This can be done by implementing the getShortcut() method. This method must return an array of keys built as follows:

[MODIFIER..., CHARACTER]

The allowed modifiers are meta, ctrl, alt and shift. The shortcut can support none, one or multiple modifiers. The array must specify only one character (e.g. a letter, a number or a symbol) and must be specified as last element. Here's an example list:

⌘⇧F - ['meta', 'shift', 'F']
⌃⌥P - ['ctrl', 'alt', 'P']
⌘, - ['meta', ',']
X - ['X']

The getShortcut() method doesn't receive any parameters.

The getShortcut() method must return an array containing the modifiers (if any) and a character.

In our case, we may use (⌘⇧D) for Mac OS users or (⌃⇧D) for other operating systems.

getShortcut() {
	if (navigator.isMac()) {
		// shortcut for mac
		return ['meta', 'shift', 'D'];
	}

	// shortcut for win and linux
	return ['ctrl', 'shift', 'D'];
}

DOM Registration

Once the file is ready, we need to load it within the DOM and attach it to the canvas instance.

Before all, the file should be uploaded within a folder of the server, such as this one:

/administrator/components/com_vikrestaurants/assets/js/ui-svg/addons/shortcuts/

In case the shortcut folder doesn't exist, it is possible to create it. Obviously the file can be uploaded wherever you want.

After uploading the file, it is needed to create an override for the view used to manage the map. These are the steps to follow:

open the Joomla! back-end
visit the Extensions > Templates > Templates page
select the Administrator option from the dropdown next to the search bar
edit the active template (probably Isis)
access the Create Overrides tab
pick the Components > com_vikrestaurants > managemap view

This will create an override for the managemap view, which can be edited without altering the core files of the software. The file can be accessed directly from the back-end or via FTP. Here's the file path:

/administrator/templates/[TEMPLATE]/html/com_vikrestaurants/managemap/default.php

We can include here the javascript file for the shortcut, as explained in the example below. This example assumes that the file is called duplicate.js.

<?php
/** 
 * @package   	VikRestaurants
 * @subpackage 	com_vikrestaurants
 * @author    	Matteo Galletti - e4j
 * @copyright 	Copyright (C) 2018 e4j - Extensionsforjoomla.com. All Rights Reserved.
 * @license  	http://www.gnu.org/licenses/gpl-2.0.html GNU/GPL
 * @link 	https://extensionsforjoomla.com
 */

// No direct access to this file
defined('_JEXEC') or die('Restricted access');

JHtml::_('behavior.keepalive');
JHtml::_('formbehavior.chosen');

// add JS file here
$duplicatePath = 'administrator/components/com_vikrestaurants/assets/js/ui-svg/addons/shortcuts/duplicate.js';
VikApplication::getInstance()->addScript(JUri::root() . $duplicatePath);

After loading the JS file, we need to instantiate the class created previously and register it within the canvas. Here's an example.

// hidden commands
canvas.registerCommand(new UICommandShortcut('cmd-shortcut'));

// register shortcuts
canvas.registerShortcut(new UIShortcutCopy());
canvas.registerShortcut(new UIShortcutPaste());
canvas.registerShortcut(new UIShortcutRedo());
canvas.registerShortcut(new UIShortcutRemove());
canvas.registerShortcut(new UIShortcutSelectAll());
canvas.registerShortcut(new UIShortcutUndo());

// register here our JS file
canvas.registerShortcut(new UIShortcutDuplicate());

// setup images
canvas.addImage(<?php echo json_encode($this->mediaList); ?>);

Prev: Developers

Next: Implement a new Command