mirror of https://github.com/artf/grapesjs.git
nocodeframeworkdrag-and-dropsite-buildersite-generatortemplate-builderui-builderweb-builderweb-builder-frameworkwebsite-builderno-codepage-builder
You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
178 lines
62 KiB
178 lines
62 KiB
<!DOCTYPE html>
|
|
<html lang="en-US">
|
|
<head>
|
|
<meta charset="utf-8">
|
|
<meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>Commands | GrapesJS</title>
|
|
<meta name="generator" content="VuePress 1.9.10">
|
|
<link rel="icon" href="/docs/logo-icon.png">
|
|
<link rel="stylesheet" href="https://grapesjs.com/stylesheets/grapes.min.css?v0.21.10">
|
|
<script src="https://grapesjs.com/js/grapes.min.js?v0.21.10"></script>
|
|
<meta name="description" content="GrapesJS documentation">
|
|
|
|
<link rel="preload" href="/docs/assets/css/0.styles.c7ff573f.css" as="style"><link rel="preload" href="/docs/assets/js/app.7cba500a.js" as="script"><link rel="preload" href="/docs/assets/js/4.0070552e.js" as="script"><link rel="preload" href="/docs/assets/js/2.6fefd022.js" as="script"><link rel="preload" href="/docs/assets/js/1.d23e9fed.js" as="script"><link rel="preload" href="/docs/assets/js/83.288e8f5d.js" as="script"><link rel="prefetch" href="/docs/assets/js/12.fcd6c1b3.js"><link rel="prefetch" href="/docs/assets/js/13.f8ba6288.js"><link rel="prefetch" href="/docs/assets/js/14.37d1e434.js"><link rel="prefetch" href="/docs/assets/js/15.6e77df13.js"><link rel="prefetch" href="/docs/assets/js/16.c5f433ca.js"><link rel="prefetch" href="/docs/assets/js/17.de56d7c2.js"><link rel="prefetch" href="/docs/assets/js/18.bf39ac98.js"><link rel="prefetch" href="/docs/assets/js/19.ca87c57f.js"><link rel="prefetch" href="/docs/assets/js/20.68039d84.js"><link rel="prefetch" href="/docs/assets/js/21.2b429912.js"><link rel="prefetch" href="/docs/assets/js/22.27b0a8c5.js"><link rel="prefetch" href="/docs/assets/js/23.a6d68e8d.js"><link rel="prefetch" href="/docs/assets/js/24.74960541.js"><link rel="prefetch" href="/docs/assets/js/25.ca71342f.js"><link rel="prefetch" href="/docs/assets/js/26.33a13a48.js"><link rel="prefetch" href="/docs/assets/js/27.54f6b393.js"><link rel="prefetch" href="/docs/assets/js/28.cf1f128d.js"><link rel="prefetch" href="/docs/assets/js/29.5888c207.js"><link rel="prefetch" href="/docs/assets/js/3.4e94790f.js"><link rel="prefetch" href="/docs/assets/js/30.bace5f23.js"><link rel="prefetch" href="/docs/assets/js/31.2b0fa15d.js"><link rel="prefetch" href="/docs/assets/js/32.fdf463ac.js"><link rel="prefetch" href="/docs/assets/js/33.a739af41.js"><link rel="prefetch" href="/docs/assets/js/34.27801365.js"><link rel="prefetch" href="/docs/assets/js/35.55be1c25.js"><link rel="prefetch" href="/docs/assets/js/36.78a4b7a9.js"><link rel="prefetch" href="/docs/assets/js/37.a1d1286c.js"><link rel="prefetch" href="/docs/assets/js/38.7f94984b.js"><link rel="prefetch" href="/docs/assets/js/39.bae8130f.js"><link rel="prefetch" href="/docs/assets/js/40.d641c435.js"><link rel="prefetch" href="/docs/assets/js/41.2f0da2d4.js"><link rel="prefetch" href="/docs/assets/js/42.a0743242.js"><link rel="prefetch" href="/docs/assets/js/43.8460a28b.js"><link rel="prefetch" href="/docs/assets/js/44.943c0253.js"><link rel="prefetch" href="/docs/assets/js/45.aafa45da.js"><link rel="prefetch" href="/docs/assets/js/46.ad246b82.js"><link rel="prefetch" href="/docs/assets/js/47.b412adfe.js"><link rel="prefetch" href="/docs/assets/js/48.af9cac86.js"><link rel="prefetch" href="/docs/assets/js/49.86ad40ac.js"><link rel="prefetch" href="/docs/assets/js/5.08dc74a9.js"><link rel="prefetch" href="/docs/assets/js/50.f7509701.js"><link rel="prefetch" href="/docs/assets/js/51.8c42f1c6.js"><link rel="prefetch" href="/docs/assets/js/52.82b56909.js"><link rel="prefetch" href="/docs/assets/js/53.5f6601a1.js"><link rel="prefetch" href="/docs/assets/js/54.e8a69f95.js"><link rel="prefetch" href="/docs/assets/js/55.22891dc5.js"><link rel="prefetch" href="/docs/assets/js/56.f7e9921e.js"><link rel="prefetch" href="/docs/assets/js/57.578f14f1.js"><link rel="prefetch" href="/docs/assets/js/58.64b9e09c.js"><link rel="prefetch" href="/docs/assets/js/59.135e8739.js"><link rel="prefetch" href="/docs/assets/js/6.3a6e1ed3.js"><link rel="prefetch" href="/docs/assets/js/60.c21dfd9f.js"><link rel="prefetch" href="/docs/assets/js/61.c49c5b1e.js"><link rel="prefetch" href="/docs/assets/js/62.ce5bed3d.js"><link rel="prefetch" href="/docs/assets/js/63.3ee6f39c.js"><link rel="prefetch" href="/docs/assets/js/64.b439d27f.js"><link rel="prefetch" href="/docs/assets/js/65.ee472a88.js"><link rel="prefetch" href="/docs/assets/js/66.becd0d7a.js"><link rel="prefetch" href="/docs/assets/js/67.166cf34e.js"><link rel="prefetch" href="/docs/assets/js/68.36615226.js"><link rel="prefetch" href="/docs/assets/js/69.9a5913c7.js"><link rel="prefetch" href="/docs/assets/js/7.b99a3113.js"><link rel="prefetch" href="/docs/assets/js/70.8663a867.js"><link rel="prefetch" href="/docs/assets/js/71.8b580dcf.js"><link rel="prefetch" href="/docs/assets/js/72.355b7953.js"><link rel="prefetch" href="/docs/assets/js/73.b9ad99cd.js"><link rel="prefetch" href="/docs/assets/js/74.517d9902.js"><link rel="prefetch" href="/docs/assets/js/75.183f30c2.js"><link rel="prefetch" href="/docs/assets/js/76.894100bc.js"><link rel="prefetch" href="/docs/assets/js/77.a896626f.js"><link rel="prefetch" href="/docs/assets/js/78.a8d38215.js"><link rel="prefetch" href="/docs/assets/js/79.d0ad637c.js"><link rel="prefetch" href="/docs/assets/js/8.c0e09a5e.js"><link rel="prefetch" href="/docs/assets/js/80.43bf5b47.js"><link rel="prefetch" href="/docs/assets/js/81.a3f44150.js"><link rel="prefetch" href="/docs/assets/js/82.514bee1c.js"><link rel="prefetch" href="/docs/assets/js/84.76c28d97.js"><link rel="prefetch" href="/docs/assets/js/85.c70a27f1.js"><link rel="prefetch" href="/docs/assets/js/86.d1d289b7.js"><link rel="prefetch" href="/docs/assets/js/87.bced23ab.js"><link rel="prefetch" href="/docs/assets/js/88.f0049b73.js"><link rel="prefetch" href="/docs/assets/js/89.c2ba01c2.js"><link rel="prefetch" href="/docs/assets/js/9.6121e0b4.js"><link rel="prefetch" href="/docs/assets/js/90.529090e5.js"><link rel="prefetch" href="/docs/assets/js/91.dd59134d.js"><link rel="prefetch" href="/docs/assets/js/92.d3e7c08c.js"><link rel="prefetch" href="/docs/assets/js/93.a12b0826.js"><link rel="prefetch" href="/docs/assets/js/94.036e5ed0.js"><link rel="prefetch" href="/docs/assets/js/vendors~docsearch.0da9b1d4.js">
|
|
<link rel="stylesheet" href="/docs/assets/css/0.styles.c7ff573f.css">
|
|
</head>
|
|
<body>
|
|
<div id="app" data-server-rendered="true"><div class="theme-container"><header class="navbar"><div class="sidebar-button"><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" role="img" viewBox="0 0 448 512" class="icon"><path fill="currentColor" d="M436 124H12c-6.627 0-12-5.373-12-12V80c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12zm0 160H12c-6.627 0-12-5.373-12-12v-32c0-6.627 5.373-12 12-12h424c6.627 0 12 5.373 12 12v32c0 6.627-5.373 12-12 12z"></path></svg></div> <a href="/docs/" class="home-link router-link-active"><img src="/docs/logo.png" alt="GrapesJS" class="logo"> <span class="site-name can-hide">GrapesJS</span></a> <div class="links"><div class="search-box"><input aria-label="Search" autocomplete="off" spellcheck="false" value=""> <!----></div> <nav class="nav-links can-hide"><div class="nav-item"><a href="/docs/" class="nav-link">
|
|
Docs
|
|
</a></div><div class="nav-item"><a href="/docs/api/" class="nav-link">
|
|
API Reference
|
|
</a></div><div class="nav-item"><a href="https://opencollective.com/grapesjs" target="_blank" rel="noopener noreferrer" class="nav-link external">
|
|
Support Us
|
|
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div><div class="nav-item"><a href="https://twitter.com/grapesjs" target="_blank" rel="noopener noreferrer" class="nav-link external">
|
|
Twitter
|
|
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <a href="https://github.com/artf/grapesjs" target="_blank" rel="noopener noreferrer" class="repo-link">
|
|
GitHub
|
|
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></nav></div></header> <div class="sidebar-mask"></div> <aside class="sidebar"><nav class="nav-links"><div class="nav-item"><a href="/docs/" class="nav-link">
|
|
Docs
|
|
</a></div><div class="nav-item"><a href="/docs/api/" class="nav-link">
|
|
API Reference
|
|
</a></div><div class="nav-item"><a href="https://opencollective.com/grapesjs" target="_blank" rel="noopener noreferrer" class="nav-link external">
|
|
Support Us
|
|
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div><div class="nav-item"><a href="https://twitter.com/grapesjs" target="_blank" rel="noopener noreferrer" class="nav-link external">
|
|
Twitter
|
|
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></div> <a href="https://github.com/artf/grapesjs" target="_blank" rel="noopener noreferrer" class="repo-link">
|
|
GitHub
|
|
<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a></nav> <div id="native-carbon" class="carbon-ads"></div> <ul class="sidebar-links"><li><a href="/docs/" aria-current="page" class="sidebar-link">Introduction</a></li><li><a href="/docs/getting-started.html" class="sidebar-link">Getting Started</a></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading open"><span>Modules</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/docs/modules/Components.html" class="sidebar-link">Components</a></li><li><a href="/docs/modules/Components-js.html" class="sidebar-link">Components & JS</a></li><li><a href="/docs/modules/Traits.html" class="sidebar-link">Traits</a></li><li><a href="/docs/modules/Blocks.html" class="sidebar-link">Blocks</a></li><li><a href="/docs/modules/Assets.html" class="sidebar-link">Assets</a></li><li><a href="/docs/modules/Commands.html" aria-current="page" class="active sidebar-link">Commands</a><ul class="sidebar-sub-headers"><li class="sidebar-sub-header"><a href="/docs/modules/Commands.html#basic-configuration" class="sidebar-link">Basic configuration</a></li><li class="sidebar-sub-header"><a href="/docs/modules/Commands.html#default-commands" class="sidebar-link">Default commands</a></li><li class="sidebar-sub-header"><a href="/docs/modules/Commands.html#stateful-commands" class="sidebar-link">Stateful commands</a></li><li class="sidebar-sub-header"><a href="/docs/modules/Commands.html#extending" class="sidebar-link">Extending</a></li><li class="sidebar-sub-header"><a href="/docs/modules/Commands.html#events" class="sidebar-link">Events</a></li><li class="sidebar-sub-header"><a href="/docs/modules/Commands.html#conclusion" class="sidebar-link">Conclusion</a></li></ul></li><li><a href="/docs/modules/I18n.html" class="sidebar-link">I18n</a></li><li><a href="/docs/modules/Selectors.html" class="sidebar-link">Selectors</a></li><li><a href="/docs/modules/Layers.html" class="sidebar-link">Layers</a></li><li><a href="/docs/modules/Pages.html" class="sidebar-link">Pages</a></li><li><a href="/docs/modules/Style-manager.html" class="sidebar-link">Style Manager</a></li><li><a href="/docs/modules/Storage.html" class="sidebar-link">Storage Manager</a></li><li><a href="/docs/modules/Modal.html" class="sidebar-link">Modal</a></li><li><a href="/docs/modules/Plugins.html" class="sidebar-link">Plugins</a></li></ul></section></li><li><section class="sidebar-group depth-0"><p class="sidebar-heading"><span>Guides</span> <!----></p> <ul class="sidebar-links sidebar-group-items"><li><a href="/docs/guides/Replace-Rich-Text-Editor.html" class="sidebar-link">Replace Rich Text Editor</a></li><li><a href="/docs/guides/Custom-CSS-parser.html" class="sidebar-link">Use Custom CSS Parser</a></li></ul></section></li></ul> </aside> <main class="page"> <div class="theme-default-content content__default"><h1 id="commands"><a href="#commands" class="header-anchor">#</a> Commands</h1> <p>A basic command in GrapesJS it's a simple function, but you will see in this guide how powerful they can be. The main goal of the Command module is to centralize functions and be easily reused across the editor. Another big advantage of using commands is the ability to track them, extend or even interrupt beside some conditions.</p> <div class="custom-block warning"><p class="custom-block-title">WARNING</p> <p>This guide is referring to GrapesJS v0.14.61 or higher</p></div> <p></p><div class="table-of-contents"><ul><li><a href="#basic-configuration">Basic configuration</a></li><li><a href="#default-commands">Default commands</a></li><li><a href="#stateful-commands">Stateful commands</a></li><li><a href="#extending">Extending</a></li><li><a href="#events">Events</a><ul><li><a href="#intercept-run-and-stop">Intercept run and stop</a></li><li><a href="#interrupt-command-flow">Interrupt command flow</a></li></ul></li><li><a href="#conclusion">Conclusion</a></li></ul></div><p></p> <h2 id="basic-configuration"><a href="#basic-configuration" class="header-anchor">#</a> Basic configuration</h2> <p>You can create your commands already from the initialization step by passing them in the <code>commands.defaults</code> options:</p> <div class="language-js extra-class"><pre class="language-js"><code><span class="token keyword">const</span> editor <span class="token operator">=</span> grapesjs<span class="token punctuation">.</span><span class="token function">init</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
|
<span class="token operator">...</span>
|
|
<span class="token literal-property property">commands</span><span class="token operator">:</span> <span class="token punctuation">{</span>
|
|
<span class="token literal-property property">defaults</span><span class="token operator">:</span> <span class="token punctuation">[</span>
|
|
<span class="token punctuation">{</span>
|
|
<span class="token comment">// id and run are mandatory in this case</span>
|
|
<span class="token literal-property property">id</span><span class="token operator">:</span> <span class="token string">'my-command-id'</span><span class="token punctuation">,</span>
|
|
<span class="token function">run</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This is my command'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
|
<span class="token literal-property property">id</span><span class="token operator">:</span> <span class="token string">'...'</span><span class="token punctuation">,</span>
|
|
<span class="token comment">// ...</span>
|
|
<span class="token punctuation">}</span>
|
|
<span class="token punctuation">]</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>For all other available options check directly the <a href="https://github.com/GrapesJS/grapesjs/blob/master/src/commands/config/config.ts" target="_blank" rel="noopener noreferrer">configuration source file<span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a>.</p> <p>Most commonly commands are created dynamically post-initialization, in that case, you'll need to use the <a href="/docs/api/commands.html">Commands API</a> (eg. this is what you need if you create a plugin)</p> <div class="language-js extra-class"><pre class="language-js"><code><span class="token keyword">const</span> commands <span class="token operator">=</span> editor<span class="token punctuation">.</span>Commands<span class="token punctuation">;</span>
|
|
commands<span class="token punctuation">.</span><span class="token function">add</span><span class="token punctuation">(</span><span class="token string">'my-command-id'</span><span class="token punctuation">,</span> <span class="token parameter">editor</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This is my command'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
|
|
<span class="token comment">// or it would be the same...</span>
|
|
commands<span class="token punctuation">.</span><span class="token function">add</span><span class="token punctuation">(</span><span class="token string">'my-command-id'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
|
<span class="token function">run</span><span class="token punctuation">(</span><span class="token parameter">editor</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This is my command'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>As you see the definition is quite easy, you just add an ID and the callback function. The <a href="/docs/api/editor.html">Editor</a> instance is passed as the first argument to the callback so you can access any other module or API method.</p> <p>Now if you want to call that command you should just run this</p> <div class="language-js extra-class"><pre class="language-js"><code>editor<span class="token punctuation">.</span><span class="token function">runCommand</span><span class="token punctuation">(</span><span class="token string">'my-command-id'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><div class="custom-block tip"><p class="custom-block-title">TIP</p> <p>The method <code>editor.runCommand</code> is an alias of <code>editor.Commands.run</code></p></div> <p>You could also pass options if you need</p> <div class="language-js extra-class"><pre class="language-js"><code>editor<span class="token punctuation">.</span><span class="token function">runCommand</span><span class="token punctuation">(</span><span class="token string">'my-command-id'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span> <span class="token literal-property property">some</span><span class="token operator">:</span> <span class="token string">'option'</span> <span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>Then you can get the same object as a third argument of the callback.</p> <div class="language-js extra-class"><pre class="language-js"><code>commands<span class="token punctuation">.</span><span class="token function">add</span><span class="token punctuation">(</span><span class="token string">'my-command-id'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token parameter">editor<span class="token punctuation">,</span> sender<span class="token punctuation">,</span> options <span class="token operator">=</span> <span class="token punctuation">{</span><span class="token punctuation">}</span></span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token template-string"><span class="token template-punctuation string">`</span><span class="token string">This is my command </span><span class="token interpolation"><span class="token interpolation-punctuation punctuation">${</span>options<span class="token punctuation">.</span>some<span class="token interpolation-punctuation punctuation">}</span></span><span class="token template-punctuation string">`</span></span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>The second argument, <code>sender</code>, just indicates who requested the command, in our case will be always the <code>editor</code></p> <p>Until now there is nothing exciting except a common entry point for functions, but we'll see later its real advantages.</p> <h2 id="default-commands"><a href="#default-commands" class="header-anchor">#</a> Default commands</h2> <p>GrapesJS comes along with some default set of commands and you can get a list of all currently available commands via <code>editor.Commands.getAll()</code>. This will give you an object of all available commands, so, also those added later, like via plugins. You can recognize default commands by their namespace <code>core:*</code>, we also recommend to use namespaces in your own custom commands, but let's get a look more in detail here:</p> <ul><li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/CanvasClear.ts" target="_blank" rel="noopener noreferrer"><code>core:canvas-clear</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Clear all the content from the canvas (HTML and CSS)</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/ComponentDelete.ts" target="_blank" rel="noopener noreferrer"><code>core:component-delete</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Delete a component</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/ComponentEnter.ts" target="_blank" rel="noopener noreferrer"><code>core:component-enter</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Select the first children component of the selected one</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/ComponentExit.ts" target="_blank" rel="noopener noreferrer"><code>core:component-exit</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Select the parent component of the current selected one</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/ComponentNext.ts" target="_blank" rel="noopener noreferrer"><code>core:component-next</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Select the next sibling component</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/ComponentPrev.ts" target="_blank" rel="noopener noreferrer"><code>core:component-prev</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Select the previous sibling component</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/SwitchVisibility.ts" target="_blank" rel="noopener noreferrer"><code>core:component-outline</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Enable outline border on components</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/ShowOffset.ts" target="_blank" rel="noopener noreferrer"><code>core:component-offset</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Enable components offset (margins, paddings)</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/SelectComponent.ts" target="_blank" rel="noopener noreferrer"><code>core:component-select</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Enable the process of selecting components in the canvas</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/CopyComponent.ts" target="_blank" rel="noopener noreferrer"><code>core:copy</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Copy the current selected component</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/PasteComponent.ts" target="_blank" rel="noopener noreferrer"><code>core:paste</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Paste copied component</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/Preview.ts" target="_blank" rel="noopener noreferrer"><code>core:preview</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Show the preview of the template in canvas</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/Fullscreen.ts" target="_blank" rel="noopener noreferrer"><code>core:fullscreen</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Set the editor fullscreen</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/ExportTemplate.ts" target="_blank" rel="noopener noreferrer"><code>core:open-code</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Open a default panel with the template code</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/OpenLayers.ts" target="_blank" rel="noopener noreferrer"><code>core:open-layers</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Open a default panel with layers</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/OpenStyleManager.ts" target="_blank" rel="noopener noreferrer"><code>core:open-styles</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Open a default panel with the style manager</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/OpenTraitManager.ts" target="_blank" rel="noopener noreferrer"><code>core:open-traits</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Open a default panel with the trait manager</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/OpenBlocks.ts" target="_blank" rel="noopener noreferrer"><code>core:open-blocks</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Open a default panel with the blocks</li> <li><a href="https://github.com/GrapesJS/grapesjs/blob/dev/src/commands/view/OpenAssets.ts" target="_blank" rel="noopener noreferrer"><code>core:open-assets</code><span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></a> - Open a default panel with the assets</li> <li><code>core:undo</code> - Call undo operation</li> <li><code>core:redo</code> - Call redo operation
|
|
</li></ul> <h2 id="stateful-commands"><a href="#stateful-commands" class="header-anchor">#</a> Stateful commands</h2> <p>As we've already seen the command is just a function and once executed nothing is left behind, but in some cases, we'd like to keep a track of executed commands. GrapesJS can handle by default this case and to enable it you just need to declare a command as an object with the <code>run</code> and <code>stop</code> methods</p> <div class="language-js extra-class"><pre class="language-js"><code>commands<span class="token punctuation">.</span><span class="token function">add</span><span class="token punctuation">(</span><span class="token string">'my-command-state'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
|
<span class="token function">run</span><span class="token punctuation">(</span><span class="token parameter">editor</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This command is now active'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token function">stop</span><span class="token punctuation">(</span><span class="token parameter">editor</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This command is disabled'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>So if we now run <code>editor.runCommand('my-command-state')</code> the command will be registered as active. To check the state of the command you can use <code>commands.isActive('my-command-state')</code> or you can even get the list of all active commands via <code>commands.getActive()</code>, in our case the result would be something like this</p> <div class="language-js extra-class"><pre class="language-js"><code><span class="token punctuation">{</span>
|
|
<span class="token operator">...</span>
|
|
<span class="token string-property property">'my-command-state'</span><span class="token operator">:</span> <span class="token keyword">undefined</span>
|
|
<span class="token punctuation">}</span>
|
|
</code></pre></div><p>The key of the result object tells you the active command, the value is the last return of the <code>run</code> command, in our case is <code>undefined</code> because we didn't return anything, but it's up to your implementation decide what to return and if you actually need it.</p> <div class="language-js extra-class"><pre class="language-js"><code><span class="token comment">// Let's return something</span>
|
|
<span class="token operator">...</span>
|
|
<span class="token function">run</span><span class="token punctuation">(</span><span class="token parameter">editor</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This command is now active'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token keyword">return</span> <span class="token punctuation">{</span>
|
|
<span class="token literal-property property">activated</span><span class="token operator">:</span> <span class="token keyword">new</span> <span class="token class-name">Date</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token operator">...</span>
|
|
<span class="token comment">// Now instead of the `undefined` you'll see the object from the run method</span>
|
|
</code></pre></div><p>To disable the command use <code>editor.stopCommand</code> method, so in our case it'll be <code>editor.stopCommand('my-command-state')</code>. As for the <code>runCommand</code> you can pass an options object as a second argument and use them in your <code>stop</code> method.</p> <p>Once the command is active, if you try to run <code>editor.runCommand('my-command-state')</code> again you'll notice that the <code>run</code> is not triggering. This behavior is useful to prevent executing multiple times the activation process which might lead to an inconsistent state (think about, for instance, having a counter, which should be increased on <code>run</code> and decreased on <code>stop</code>). If you need to run a command multiple times probably you're dealing with a not stateful command, so try to use it without the <code>stop</code> method, but in case you're aware of your application state you can actually force the execution with <code>editor.runCommand('my-command-state', { force: true })</code>. The same logic applies to the <code>stopCommand</code> method.</p> <br> <div class="custom-block danger"><p class="custom-block-title">WARNING</p> <p></p></div> <p>If you deal with UI in your stateful commands, be careful to keep the state coherent with your logic. Let's take, for example, the use of a modal as an indicator of the command state.</p> <div class="language-js extra-class"><pre class="language-js"><code>commands<span class="token punctuation">.</span><span class="token function">add</span><span class="token punctuation">(</span><span class="token string">'my-command-modal'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
|
<span class="token function">run</span><span class="token punctuation">(</span><span class="token parameter">editor</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
editor<span class="token punctuation">.</span>Modal<span class="token punctuation">.</span><span class="token function">open</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
|
<span class="token literal-property property">title</span><span class="token operator">:</span> <span class="token string">'Modal example'</span><span class="token punctuation">,</span>
|
|
<span class="token literal-property property">content</span><span class="token operator">:</span> <span class="token string">'My content'</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token function">stop</span><span class="token punctuation">(</span><span class="token parameter">editor</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
editor<span class="token punctuation">.</span>Modal<span class="token punctuation">.</span><span class="token function">close</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>If you run it, close the modal (eg. by clicking the 'x' on top) and then try to run it again you'll see that the modal is not opening anymore. This happens because the command is still active (you should see it in <code>commands.getActive()</code>) and to fix it you have to disable it once the modal is closed.</p> <div class="language-js extra-class"><pre class="language-js"><code><span class="token operator">...</span>
|
|
<span class="token function">run</span><span class="token punctuation">(</span><span class="token parameter">editor</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
editor<span class="token punctuation">.</span>Modal<span class="token punctuation">.</span><span class="token function">open</span><span class="token punctuation">(</span><span class="token punctuation">{</span>
|
|
<span class="token literal-property property">title</span><span class="token operator">:</span> <span class="token string">'Modal example'</span><span class="token punctuation">,</span>
|
|
<span class="token literal-property property">content</span><span class="token operator">:</span> <span class="token string">'My content'</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">.</span><span class="token function">onceClose</span><span class="token punctuation">(</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">stopCommand</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token operator">...</span>
|
|
</code></pre></div><p>In the example above, we make use of few helper methods from the Modal module (<code>onceClose</code>) and the command itself (<code>stopCommand</code>) but obviously, the logic might be different due to your requirements and specific UI.</p> <h2 id="extending"><a href="#extending" class="header-anchor">#</a> Extending</h2> <p>Another big advantage of commands is the possibility to easily extend or override them with another command.
|
|
Let's take a simple example</p> <div class="language-js extra-class"><pre class="language-js"><code>commands<span class="token punctuation">.</span><span class="token function">add</span><span class="token punctuation">(</span><span class="token string">'my-command-1'</span><span class="token punctuation">,</span> <span class="token parameter">editor</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This is command 1'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>If you need to overwrite this command with another one, just add it and keep the same id.</p> <div class="language-js extra-class"><pre class="language-js"><code>commands<span class="token punctuation">.</span><span class="token function">add</span><span class="token punctuation">(</span><span class="token string">'my-command-1'</span><span class="token punctuation">,</span> <span class="token parameter">editor</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This is command 1 overwritten'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>Let's see now instead how can we extend one</p> <div class="language-js extra-class"><pre class="language-js"><code>commands<span class="token punctuation">.</span><span class="token function">add</span><span class="token punctuation">(</span><span class="token string">'my-command-2'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
|
<span class="token function">someFunction1</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This is function 1'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token function">someFunction2</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This is function 2'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token function">run</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
<span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">someFunction1</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token keyword">this</span><span class="token punctuation">.</span><span class="token function">someFunction2</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>to extend it just use <code>extend</code> method by passing the id</p> <div class="language-js extra-class"><pre class="language-js"><code>commands<span class="token punctuation">.</span><span class="token function">extend</span><span class="token punctuation">(</span><span class="token string">'my-command-2'</span><span class="token punctuation">,</span> <span class="token punctuation">{</span>
|
|
<span class="token function">someFunction2</span><span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
<span class="token function">alert</span><span class="token punctuation">(</span><span class="token string">'This is function 2 extended'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">,</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><h2 id="events"><a href="#events" class="header-anchor">#</a> Events</h2> <p>The Commands module offers also a set of events that you can use to intercept the command flow for adding more functionality or even interrupting it.</p> <h3 id="intercept-run-and-stop"><a href="#intercept-run-and-stop" class="header-anchor">#</a> Intercept run and stop</h3> <p>By using our previously created <code>my-command-modal</code> command let's see which events we can listen to</p> <div class="language-js extra-class"><pre class="language-js"><code>editor<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'run:my-command-modal'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'After `my-command-modal` execution'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token comment">// For example, you can add extra content to the modal</span>
|
|
<span class="token keyword">const</span> modalContent <span class="token operator">=</span> editor<span class="token punctuation">.</span>Modal<span class="token punctuation">.</span><span class="token function">getContentEl</span><span class="token punctuation">(</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
modalContent<span class="token punctuation">.</span><span class="token function">insertAdjacentHTML</span><span class="token punctuation">(</span><span class="token string">'beforeEnd'</span><span class="token punctuation">,</span> <span class="token string">'<div>Some content</div>'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
editor<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'run:my-command-modal:before'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'Before `my-command-modal` execution'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token comment">// for stateful commands</span>
|
|
editor<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'stop:my-command-modal'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'After `my-command-modal` is stopped'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
editor<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'stop:my-command-modal:before'</span><span class="token punctuation">,</span> <span class="token punctuation">(</span><span class="token punctuation">)</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'Before `my-command-modal` is stopped'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><p>If you need, you can also listen to all commands</p> <div class="language-js extra-class"><pre class="language-js"><code>editor<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'run'</span><span class="token punctuation">,</span> <span class="token parameter">commandId</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'Run'</span><span class="token punctuation">,</span> commandId<span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
|
|
editor<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'stop'</span><span class="token punctuation">,</span> <span class="token parameter">commandId</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'Stop'</span><span class="token punctuation">,</span> commandId<span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><h3 id="interrupt-command-flow"><a href="#interrupt-command-flow" class="header-anchor">#</a> Interrupt command flow</h3> <p>Sometimes you might need to interrupt the execution of an existant command due to some condition. In that case, you have to use <code>run:{COMMAND-ID}:before</code> event and set to <code>true</code> the abort option</p> <div class="language-js extra-class"><pre class="language-js"><code><span class="token keyword">const</span> condition <span class="token operator">=</span> <span class="token number">1</span><span class="token punctuation">;</span>
|
|
|
|
editor<span class="token punctuation">.</span><span class="token function">on</span><span class="token punctuation">(</span><span class="token string">'run:my-command-modal:before'</span><span class="token punctuation">,</span> <span class="token parameter">options</span> <span class="token operator">=></span> <span class="token punctuation">{</span>
|
|
<span class="token keyword">if</span> <span class="token punctuation">(</span>condition<span class="token punctuation">)</span> <span class="token punctuation">{</span>
|
|
options<span class="token punctuation">.</span>abort <span class="token operator">=</span> <span class="token boolean">true</span><span class="token punctuation">;</span>
|
|
console<span class="token punctuation">.</span><span class="token function">log</span><span class="token punctuation">(</span><span class="token string">'Prevent `my-command-modal` from execution'</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
<span class="token punctuation">}</span>
|
|
<span class="token punctuation">}</span><span class="token punctuation">)</span><span class="token punctuation">;</span>
|
|
</code></pre></div><h2 id="conclusion"><a href="#conclusion" class="header-anchor">#</a> Conclusion</h2> <p>The Commands module is quite simple but, at the same time, really powerful if used correctly. So, if you're creating a plugin for GrapesJS, use commands as much as possible, this will allow higher reusability and control over your logic.</p></div> <footer class="page-edit"><div class="edit-link"><a href="https://github.com/artf/grapesjs/edit/dev/docs/modules/Commands.md" target="_blank" rel="noopener noreferrer">Edit this page on GitHub</a> <span><svg xmlns="http://www.w3.org/2000/svg" aria-hidden="true" focusable="false" x="0px" y="0px" viewBox="0 0 100 100" width="15" height="15" class="icon outbound"><path fill="currentColor" d="M18.8,85.1h56l0,0c2.2,0,4-1.8,4-4v-32h-8v28h-48v-48h28v-8h-32l0,0c-2.2,0-4,1.8-4,4v56C14.8,83.3,16.6,85.1,18.8,85.1z"></path> <polygon fill="currentColor" points="45.7,48.7 51.3,54.3 77.2,28.5 77.2,37.2 85.2,37.2 85.2,14.9 62.8,14.9 62.8,22.9 71.5,22.9"></polygon></svg> <span class="sr-only">(opens new window)</span></span></div> <div class="last-updated"><span class="prefix">Last Updated:</span> <span class="time">6/21/2023, 10:46:05 AM</span></div></footer> <div class="page-nav"><p class="inner"><span class="prev">
|
|
←
|
|
<a href="/docs/modules/Assets.html" class="prev">
|
|
Assets
|
|
</a></span> <span class="next"><a href="/docs/modules/I18n.html">
|
|
I18n
|
|
</a>
|
|
→
|
|
</span></p></div> </main></div><div class="global-ui"></div></div>
|
|
<script src="/docs/assets/js/app.7cba500a.js" defer></script><script src="/docs/assets/js/4.0070552e.js" defer></script><script src="/docs/assets/js/2.6fefd022.js" defer></script><script src="/docs/assets/js/1.d23e9fed.js" defer></script><script src="/docs/assets/js/83.288e8f5d.js" defer></script>
|
|
</body>
|
|
</html>
|
|
|