Create Your First Package

The tutorial will lead you though creating a simple package that replaces selected text with ascii art. For example, if "cool" was selected the output would be:

                    /\_ \
  ___    ___     ___\//\ \
 /'___\ / __`\  / __`\\ \ \
/\ \__//\ \L\ \/\ \L\ \\_\ \_
\ \____\ \____/\ \____//\____\
 \/____/\/___/  \/___/ \/____/

The final package can be viewed at https://github.com/atom/ascii-art.

To begin, press cmd-shift-P to bring up the Command Palette. Type "generate package" and select the "Package Generator: Generate Package" command. Now we need to name the package, let's call ours ascii-art.

Atom will open a new window with the ascii-art package contents displayed in the Tree View. Because the window was opened after the Ascii Art package was created, the Ascii Art package will be loaded. To verify this toggle the Command Palette (cmd-shift-P) and type "Ascii Art" you'll see a new Ascii Art: Toggle command. If triggered, this command displays a default message.

Now let's edit the package files to make our ascii art package work! Since this package doesn't need any UI we can remove all view related code. Start by opening up lib/ascii-art.coffee. Remove all view code until the file looks like this:

  module.exports =
    activate: ->

Create A Command

Now let's add a command. It's recommended to start your commands with the package name followed by a colon (:). We'll call this command ascii-art:convert. Register the command in lib/ascii-art.coffee:

module.exports =
  activate: ->
    atom.workspaceView.command "ascii-art:convert", => @convert()

  convert: ->
    # This assumes the active pane item is an editor
    editor = atom.workspace.activePaneItem
    selection = editor.getSelection()
    upperCaseSelectedText = selection.getText().toUpperCase()
    selection.insertText(upperCaseSelectedText)

The atom.workspaceView.command method takes a command name and a callback. The callback executes when the command is triggered. In this case, when the command is triggered the callback will call the convert method and uppercase the selected text.

Reload The Package

Before we can trigger ascii-art:convert the window needs to reevaluate the Ascii Art package. To do this we reload the window, just like when writing a script in browser. Trigger window:reload command using the command palette or by pressing ctrl-alt-cmd-l.

Trigger The command

Now open the command panel and search for the ascii-art:convert command. But its not there! To fix this open package.json and find the property called activationEvents. Activation Events speed up load time by allowing an Atom to delay a package's activation until it's needed. So add the ascii-art:convert to the activationEvents array:

"activationEvents": ["ascii-art:convert"],

Now reload window ctrl-alt-cmd-l and use the command panel to trigger the ascii-art:convert command. It will uppercase any text you have selected.

Add A Key Binding

Now let's add a key binding to trigger the ascii-art:convert command. Open keymaps/ascii-art.cson and add a key binding linking ctrl-alt-a to the ascii-art:convert command. When finished, the file will look like this:

'.editor':
  'cmd-alt-a': 'ascii-art:convert'

Notice .editor on the first line. This limits the key binding to work when the focused element matches the selector .editor, much like CSS. For example, if the Tree View has focus, pressing cmd-alt-a won't trigger the ascii-art:convert command. But if the editor has focus, the ascii-art:convert method will be triggered. More information on key bindings can be found in the keymaps documentation.

Now reload the window and verify that pressing the key binding works! You can also verify that it doesn't work when the Tree View is focused.

Add The Ascii Art

Now we need to convert the selected text to ascii art. To do this we will use the figlet node module from NPM. Open package.json add the latest version of figlet to the dependencies:

  "dependencies": {
     "figlet": "1.0.8"
  }

NOW GO TO THE COMMAND LINE AND RUN APM UPDATE BUT REALLY THIS STEP SEEMS LIKE IT COULD BE AN ATOM COMMAND.

Require the figlet node module in lib/ascii-art.coffee and instead of uppercasing the text, you can convert it to ascii art!

convert: ->
  # This assumes the active pane item is an editor
  selection = atom.workspace.activePaneItem.getSelection()

  figlet = require 'figlet'
  figlet selection.getText(), {font: "Larry 3D 2"}, (error, asciiArt) ->
    if error
      console.error(error)
    else
      selection.insertText("\n" + asciiArt + "\n")

5.6 KiB Raw Blame History