Document a way to run commands (and from init.coffee)

[vemv]

How to programatically run a command such as core:cancel? I had to figure it out since I failed to find how.

This works:

$('atom-text-editor').dispatchEvent(new CustomEvent('core:cancel'))

However it doesn't from init.coffee, because $ is not defined there (I believe init.coffee should have the same environment as in the Developer Tools console, but that's a different issue).

I suggest to create a Docs page explaining commands, how to run them programatically, and in particular how to run them from init.coffee.

Thanks - VIctor

[sedabull]

I believe the canonical way is:

atom.commands.dispatch(target, event)

see the API docs here

[lee-dohm]

It's likely that you don't want to execute commands programmatically. Commands are essentially a way of tying UI features such as menu items, keybindings and such to bits of code in packages. They're a way for the user to trigger code. If you're doing things programmatically, you can just call the code itself.

If you're trying to execute commands programmatically for testing, you can use the atom.commands.dispatch method as @sedabull mentioned.

[sedabull]

@lee-dohm, I agree that this won't come up often, but I did come across a non-testing use case for atom.commands.dispatch recently in my package quantum-shell. So perhaps it should be better documented, if only for the purpose of helping people write better tests.

[vemv]

• I stumbled upon atom.commands.dispatch but ignored it since it said 'simulate', which I interpreted as 'to not actually perform'. I suggest to reword
• Using the suggested API works, but then again $ is not reachable from init.coffee:
  atom.commands.dispatch($('atom-text-editor'), 'autocomplete:toggle')

Context

I'm trying to create a keybinding that calls core:cancel first and autocomplete:toggle second. Trying to programatically call commands by name seems reasonable here, since "autocomplete:toggle" doesn't change over time, while e.g. whatever.autocomplete.toggle(args) is fairly likely to change over time.

[lee-dohm]

The Atom team is specifically attempting to remove Atom's dependence on jQuery. But, like any other Node module, you can import jQuery into your init.coffee by doing:

{$} = require 'atom-space-pen-views'

Or, you can use the following to not need to import jQuery:

editor = atom.workspace.getActiveTextEditor()
atom.commands.dispatch(atom.views.getView(editor), 'autocomplete:toggle')

The command names are considered internal to a package and aren't intended to be a public interface. They're just as likely to change over time as any other facet of a package's code. At least, as a package author, I don't worry about breaking other people's code by changing my packages' command names because the only code that should be depending on command names are my package's code.

What you're really looking for is the new Services API that is a method where a package can create a public interface that is specifically intended to be unchanging over time (or at least versioned). It is brand new though and very few packages use it so far.

[envygeeks]

I think it becomes useful when people add in responsiveness to Atom editor (I guess this is one reason Atom beats other editors, it uses a webview) but I just wanted to chime in and say you don't need jQuery to do simple things like that since JavaScript explicitly includes these functions now:

atom.commands.dispatch(document.querySelector('atom-text-editor'), 'tree-view:toggle')

[omrihar]

I hope I'm not hijacking this discussion, but I came across it when I was looking for the best way to create a compound keybinding of more than one command using the init.coffee script. I've been trying to create a command that first runs autoflow:reflow-selection and then vim-mode:reset-normal-mode to reproduce the way gq works in vim. After some trial and error I used @lee-dohm's answer to get the editor instance and call the function on it but it was really unclear from the documentation how to do that.

I think my use case might be more common than calling commands from a package, and perhaps it is worth documenting how to do that (or even better - simplyfing the task for performing compound keybindings, perhaps by supplying a list of keybindings in keymap.cson?). I think that especially for vim users that are used to simply creating maps with multiple commands this will be an attractive feature.

[UziTech]

It's likely that you don't want to execute commands programmatically.

Is there a better way to run a toggle command when Atom opens?

I am using the multirow-tabs package which provides a multirow-tabs:toggle command to turn it on and off but it is always off by default when Atom first opens.

This seems to be fairly standard practice as there are 5 other packages I toggle on in my init script. Is this something the package creators should deal with by having an option to enable by default?

[lee-dohm]

@UziTech Yes, I'm pretty surprised that a package like multirow-tabs is off by default.

[a-laughlin]

Handy way to autocomplete and execute package commands from dev console:

window.atomPackageCommands = {};
for (let cmd in atom.packages.commandRegistry.registeredCommands){
  if(!atom.packages.commandRegistry.registeredCommands.hasOwnProperty(cmd)){continue;}
  window.atomPackageCommands[cmd.replace(/[:\-]/g,'_')] = ()=>{
    atom.commands.dispatch(atom.views.getView(atom.workspace.getActivePane().getActiveEditor()), cmd);
  };
}

// window.atomPackageCommands.tree_view_toggle()

Depends on atom's internal structure. Use at your own risk. I put it in my init.js file when developing init scripts/packages, and comment out when not.

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[schirrel]

Hi i was wondering, of making my package and how would i do, for exemplo, to run, in my project folder a command in the windows cmd?

ex. i have a project and when i toggle my package it supposed to run in prompt 'cordova plugins --save' ?

how could i do this?

[lee-dohm]

@codersquirrel There are a number of ways to do this using either the Node standard library or the Atom API. You may want to take a look at https://atom.io/docs/api/latest/BufferedProcess.

For support options in the future, please take a look at our Support document first.

[lee-dohm]

Thanks everyone for the feedback.

While atom.commands.dispatch is an option, commands aren't intended to be and are poorly designed for being used this way, so we're hesitant to document this as an officially supported method. If people have other ideas or suggestions, please open a new issue on the Flight Manual repo: https://github.com/atom/flight-manual.atom.io.

Thanks again for everyone's help and enthusiasm!

[lock]

This issue has been automatically locked since there has not been any recent activity after it was closed. If you can still reproduce this issue in Safe Mode then please open a new issue and fill out the entire issue template to ensure that we have enough information to address your issue. Thanks!