mozilla

Revision 236342 of Customization

  • Revision slug: Tools/GCLI/Customization
  • Revision title: Customization
  • Revision id: 236342
  • Created:
  • Creator: joewalker
  • Is current revision? No
  • Comment 2 words added, 2 words removed

Revision Content

The Mozcmd Format

The mozcmd format is a way to store GCLI commands for easy access. It is available to Firefox users by setting the devtools.commands.dir to point to a directory containing a number of files with the extension mozcmd.

For example if you set devtools.commands.dir to point to C:\mozcmd (on windows or /Users/me/mozcmd on Mac/Unix), then Firefox will read mozcmd files from that directory.

Syntax

The mozcmd file format is based on JSON, but with the ability to insert functions in key places - For example the exec function.

The root of the document is an Array, which contains a number of command objects suitable to be passed to gcli.addCommand().

An Example mozcmd File

The following example is taken from the demo repository.

[
  {
    name: 'hello',
    description: 'Show a message',
    params: [
      {
        name: 'name',
        type: 'string',
        description: 'Who to say hello to',
      }
    ],
    exec: function(args, context) {
      return 'Good evening, ' + args.name;
    }
  }
]

Several commands can be placed in one file, and commands always take their name from the `name` property rather than the name of the file.

Comments are not allowed except inside functions.

When a command is executed, this will be set to that of the parent object, so this.name is the name of the command. If a setup step is required then it should be done on first execution, and any results cached on this.

Security

The idea is to provide the user with the security that just having a mozcmd file available to Firefox is not a security risk, they need to access the command before any JavaScript is executed.

(Note 'access' does not imply that a command needs to be executed. Commands can provide functions to customize parameters. 'Access' is defined as typing the name of the command on the command line (regardless of whether RETURN is pressed)

The current implementation of mozcmd simply evals the script in a Sandbox. This does not provide the promised level of protection, however Bug 767912 calls for the parser to be upgraded.

Further Documentation

See documentation about writing commands.

Extending the mozcmd Format

The mozcmd format is designed to be extensible to support registering Types and Fields. This feature is not enabled yet, however you can find how how it is designed to work.

Revision Source

<h2>The Mozcmd Format</h2>
<p>The mozcmd format is a way to store GCLI commands for easy access. It is available to Firefox users by setting the <code>devtools.commands.dir</code> to point to a directory containing a number of files with the extension <code>mozcmd</code>.</p>
<p>For example if you set <code>devtools.commands.dir</code> to point to <code>C:\mozcmd</code> (on windows or <code>/Users/me/mozcmd</code> on Mac/Unix), then Firefox will read mozcmd files from that directory.</p>
<h2>Syntax</h2>
<p>The mozcmd file format is based on JSON, but with the ability to insert functions in key places - For example the <code>exec</code> function.</p>
<p>The root of the document is an Array, which contains a number of command objects suitable to be passed to <code>gcli.addCommand()</code>.</p>
<h2>An Example mozcmd File</h2>
<p>The following example is taken from <a class="link-https" href="https://github.com/joewalker/mozcmd" title="https://github.com/joewalker/mozcmd">the demo repository</a>.</p>
<pre>[
  {
    name: 'hello',
    description: 'Show a message',
    params: [
      {
        name: 'name',
        type: 'string',
        description: 'Who to say hello to',
      }
    ],
    exec: function(args, context) {
      return 'Good evening, ' + args.name;
    }
  }
]
</pre>
<p>Several commands can be placed in one file, and commands always take their name from the `name` property rather than the name of the file.</p>
<p>Comments are not allowed except inside functions.</p>
<p>When a command is executed, <code>this</code> will be set to that of the parent object, so <code>this.name</code> is the name of the command. If a setup step is required then it should be done on first execution, and any results cached on <code>this</code>.</p>
<h2>Security</h2>
<p>The idea is to provide the user with the security that just having a mozcmd file available to Firefox is not a security risk, they need to access the command before any JavaScript is executed.</p>
<p>(Note 'access' does not imply that a command needs to be executed. Commands can provide functions to customize parameters. 'Access' is defined as typing the name of the command on the command line (regardless of whether RETURN is pressed)</p>
<p>The current implementation of mozcmd simply evals the script in a Sandbox. This does not provide the promised level of protection, however <a class="link-https" href="https://bugzilla.mozilla.org/show_bug.cgi?id=767912" title="https://bugzilla.mozilla.org/show_bug.cgi?id=767912">Bug 767912</a> calls for the parser to be upgraded.</p>
<h2>Further Documentation</h2>
<p>See <a href="/en/Tools/GCLI/Writing" rel="internal" title="en/Tools/GCLI/Writing">documentation about writing commands</a>.</p>
<h2>Extending the mozcmd Format</h2>
<p>The mozcmd format is designed to be extensible to support registering Types and Fields. This feature is not enabled yet, however you can <a href="/en/Tools/GCLI/Customization/Future" title="en/Tools/GCLI/Customization/Future">find how how it is designed to work</a>.</p>
Revert to this revision