{"id":5090,"date":"2010-06-30T11:06:21","date_gmt":"2010-06-30T18:06:21","guid":{"rendered":"http:\/\/4.107"},"modified":"2010-06-30T11:06:21","modified_gmt":"2010-06-30T18:06:21","slug":"tutorial-manipulating-text-through-commands","status":"publish","type":"post","link":"https:\/\/blog.mozilla.org\/labs\/2010\/06\/tutorial-manipulating-text-through-commands\/","title":{"rendered":"Tutorial: Manipulating Text Through Commands"},"content":{"rendered":"

In this tutorial, we\u2019ll be creating new commands that allow Bespin to work with Markdown<\/a> formatted text.<\/em><\/p>\n

For this tutorial, you\u2019ll need the markdown_js plugin<\/a><\/strong>.<\/p>\n

Setting Up<\/h2>\n

With this tutorial, we\u2019re starting from the very basics. You\u2019ll need Python (preferably 2.6) to do custom Bespin plugin development. If you don\u2019t have Python already, you can get it prebuilt for your platform<\/a> with little fuss.<\/p>\n

You\u2019ll also need Bespin Embedded, which you can get from the releases directory on ftp.mozilla.org<\/a>. This tutorial was written for Bespin Embedded 0.9a1<\/a> (direct download link).<\/p>\n

Important note<\/em>: if your copy of Bespin Embedded has a plugins\/mine directory, delete that directory before doing this tutorial. That directory was added to the release in error and includes plugins that conflict with the ones needed here.<\/p>\n

Make a directory called bespintutorial<\/code>. Uncompress the BespinEmbedded package in there and rename the directory from the tarfile bespin<\/code> (so you\u2019ll have bespintutorial\/bespin\/<\/code>). On a Mac, you can do these things from the Terminal command line:<\/p>\n

mkdir bespintutorial\ncd bespintutorial\ncp ~\/Downloads\/BespinEmbedded-VERSION.tar.gz .\ntar xzf BespinEmbedded-VERSION.tar.gz\nmv BespinEmbedded-VERSION bespin\n<\/code>\n<\/pre>\n
The Manifest<\/h2>\n
Bespin\u2019s build tool, dryice, uses a \u201cmanifest\u201d file in JSON format to describe what it needs to build and where to find all of the parts. Open up your text editor to create a file called manifest.json<\/code> in the bespintutorial<\/code> directory. Here\u2019s what will go into the file at this step:<\/p>\n
{\n    \"output_dir\": \"..\/build\",\n    \"plugins\": [\"embedded\"],\n    \"search_path\": [\"..\"]\n}<\/code>\n<\/pre>\n
We\u2019ll be running the build from the bespin<\/code> directory, so those ..<\/code> in the manifest are referring to the bespintutorial<\/code> directory.<\/p>\n
Now, we\u2019ll fire up the dryice server. This command assumes at Python is on your path:<\/p>\n
cd bespin\npython dryice.py -s 8080 ..\/manifest.json\n<\/code>\n<\/pre>\n
After running that command, you can open up your browser to http:\/\/localhost:8080\/ and you should see the Bespin editor that dryice just built for us.<\/p>\n
Next, place the markdown_js.js<\/code> file which you got at the beginning of this tutorial into the bespintutorial<\/code> directory.<\/p>\n
Getting Our Plugin Going<\/h2>\n
Now, we\u2019ll create a new file called markdown.js<\/code>. This is our Bespin plugin file. Bespin plugins all have a metadata section, so let\u2019s put that at the top of our file to get us going:<\/p>\n
\"define metadata\";\n({\n    \"dependencies\": {\n        \"markdown_js\": \"0.1.2\"\n    }\n});\n\"end\";\n<\/code>\n<\/pre>\n
So, that\u2019s our whole plugin for now. All we\u2019re saying is that our plugin depends on the markdown_js<\/code> plugin (version 0.1.2). Now we have to tell dryice about our new plugin, so we\u2019ll add it to the plugins line of our manifest.json file:<\/p>\n
\"plugins\": [\"embedded\", \"markdown\"],\n<\/code>\n<\/pre>\n
You should be able to reload http:\/\/localhost:8080\/ and have things still work.<\/p>\n
Making Our Plugin Do Something<\/h2>\n
Since we\u2019re going to be making commands, it would be most convenient for us at this point to have a command line. So, we\u2019ll add the command_line<\/code> plugin to our manifest.json file:<\/p>\n
\"plugins\": [\"embedded\", \"markdown\", \"command_line\"],\n<\/code>\n<\/pre>\n
Reload the page in your browser and you should see the command line at the bottom. I also like being able to press cmd-J (ctrl-J on Windows\/Linux) to switch between the command line and the editor. The uicommands plugin gives us that, so let\u2019s enable that, too:<\/p>\n
\"plugins\": [\"embedded\", \"markdown\", \"command_line\", \"uicommands\"],\n<\/code>\n<\/pre>\n
Now we\u2019re ready to make our first command. We\u2019re going to make a command that:<\/p>\n
    \n
  1. converts the Markdown text we\u2019ve entered to HTML<\/li>\n
  2. puts that HTML in a new window so we can preview it.<\/li>\n<\/ol>\n
    Let\u2019s write a function that does these things.<\/p>\n
    var env = require('environment').env;\nvar markdown = require(\"markdown_js\");\n\nexports.preview = function(args, request) {\n    var text = env.editor.selectedText;\n    if (!text) {\n        text = env.editor.value;\n    }\n    var popup = window.open(\"\", \"_blank\", \"location=no,menubar=no\");\n    popup.document.body.innerHTML = markdown.toHTML(text);\n    request.done();\n};\n<\/code>\n<\/pre>\n
    The first two lines import other modules that we\u2019ll be needing. The environment<\/code> plugin is always available in Bespin, and the env<\/code> variable inside of there is very handy, as we\u2019ll soon see. We also import the markdown_js<\/code> module that we declared in our dependencies. We\u2019ll call it markdown<\/code> when we use it in this module for convenience.<\/p>\n
    If you\u2019re not familiar with CommonJS Modules<\/a>, you\u2019ll find that they\u2019re simple to work with. You use the require<\/code> function to import modules and you put anything you want to be available outside of the module on the exports<\/code> object. We\u2019re going to make a function called preview<\/code> available from this module.<\/p>\n
    Bespin command functions all take two parameters: args<\/code> and request<\/code>. args<\/code> contains the incoming arguments to the command and request<\/code> provides methods for working with this particular request from the user. Of these, the commands we\u2019ll be making here today only make use of request.done()<\/code>, which signals that we have finished all of our processing.<\/p>\n
    Now, let\u2019s focus on the body of the function:<\/p>\n
    var text = env.editor.selectedText;\nif (!text) {\n    text = env.editor.value;\n}\nvar popup = window.open(\"\", \"_blank\", \"location=no,menubar=no\");\npopup.document.body.innerHTML = markdown.toHTML(text);\nrequest.done();\n<\/code>\n<\/pre>\n
    The first line gets us the currently selected text. If the user selected only a portion of the document, we\u2019ll preview that. The next line looks to see if there was any selected text. If there wasn\u2019t, then we just grab all of the text from the editor.<\/p>\n
    Next, we use the standard window.open call to make a new window. A call to markdown.toHTML<\/code> will give us the HTML version of our text and we drop that into our new window and we\u2019re all set!<\/p>\n
    We need to register our new command with Bespin.<\/p>\n
    Since we\u2019re going to create more than one Markdown related command, we\u2019ll plan to create a top-level markdown<\/code> command with subcommands. The command we\u2019re working on now is markdown preview<\/code>. We need to add a new provides<\/code> section to our JSON metadata. Here\u2019s what that looks like:<\/p>\n
    \"provides\": [\n    {\n        \"ep\": \"command\",\n        \"name\": \"markdown\",\n        \"description\": \"commands for working with markdown files\"\n    },\n    {\n        \"ep\": \"command\",\n        \"name\": \"markdown preview\",\n        \"description\": \"preview the HTML form of this markdown text\",\n        \"pointer\": \"#preview\"\n    }\n]\n<\/code>\n<\/pre>\n
    provides<\/code> gives a list of extensions that are provided by this plugin. Each of those will have an ep<\/code> at a minimum. That\u2019s the \u201cextension point\u201d that we\u2019re plugging into. Our first extension is a command and we give the command a name (which is what the user types) and a description that will appear in help text.<\/p>\n
    The second extension is for our preview command. It has a name and description as well. But, since this command is not just a holder for other commands, it also has a pointer<\/code>. The pointer<\/code> tells Bespin where to find the object (in this case, a function) for the extension. #preview<\/code> is equivalent to markdown:index#preview<\/code> which means the preview<\/code> function in the index<\/code> module in the markdown<\/code> plugin.<\/p>\n
    Your complete file should now look like this:<\/p>\n
    \"define metadata\";\n({\n    \"dependencies\": {\n        \"markdown_js\": \"0.1.2\"\n    },\n    \"provides\": [\n        {\n            \"ep\": \"command\",\n            \"name\": \"markdown\",\n            \"description\": \"commands for working with markdown files\"\n        },\n        {\n            \"ep\": \"command\",\n            \"name\": \"markdown preview\",\n            \"description\": \"preview the HTML form of this markdown text\",\n            \"pointer\": \"#preview\"\n        }\n    ]\n});\n\"end\";\n\nvar env = require('environment').env;\nvar markdown = require(\"markdown_js\");\n\nexports.preview = function(args, request) {\n    var text = env.editor.selectedText;\n    if (!text) {\n        text = env.editor.value;\n    }\n    var popup = window.open(\"\", \"_blank\", \"location=no,menubar=no\");\n    popup.document.body.innerHTML = markdown.toHTML(text);\n    request.done();\n};\n<\/code>\n<\/pre>\n
    Let\u2019s come up with some sample Markdown to use. How about this:<\/p>\n
    # Markdown Test #\n\nThis is a *simple* test of Markdown.\n\n* one\n* two\n* three\n<\/code>\n<\/pre>\n
    Reload your browser, select all of the text and paste in that text. Then, jump down to the command line and run the markdown preview<\/code> command. You should see a new window popup with the HTML version of the text there.<\/p>\n
    Congratulations! You\u2019ve extended Bespin with a new command.<\/p>\n
    Keyboard Shortcut<\/h2>\n
    Previewing the HTML seems like a very useful feature. Why don\u2019t we add a keyboard shortcut so that we don\u2019t need to go to the command line each time. To do this, we just need to add a key<\/code> to the markdown preview<\/code> metadata, like so:<\/p>\n
    {\n    \"ep\": \"command\",\n    \"name\": \"markdown preview\",\n    \"description\": \"preview the HTML form of this markdown text\",\n    \"key\": \"ctrl_shift_p\",\n    \"pointer\": \"#preview\"\n}\n<\/code>\n<\/pre>\n
    Now, cmd-shift-P on the Mac or ctrl-shift-P on Windows\/Linux will run the markdown preview<\/code> command. This also means that we can run the markdown preview<\/code> command even if we don\u2019t have the command line plugin in our build.<\/p>\n
    An aside about keyboard shortcuts: the key<\/code> defined in command metadata like this is the lowest priority keyboard binding. A keymapping plugin can redefine the keys as can user preferences.<\/p>\n
    Replacing Text<\/h2>\n
    One more common requirement of commands is that they need to be able to manipulate the text in some fashion and then put the manipulated version back into the editor.<\/p>\n
    We\u2019ll make a markdown convert<\/code> command that converts the text to HTML and then puts the text back into the editor. As before, we\u2019ll start by writing a function that does this conversion and we\u2019ll place it at the bottom of our file:<\/p>\n
    exports.convert = function(args, request) {\n    var allOrSelection = 'selectedText';\n    var text = env.editor.selectedText;\n    if (!text) {\n        allOrSelection = 'value';\n        text = env.editor.value;\n    }\n    var html = markdown.toHTML(text);\n    env.editor[allOrSelection] = html;\n    request.done();\n};\n<\/code>\n<\/pre>\n
    In this function, we\u2019re going to do the same kind of thing we did in the preview<\/code> function. We\u2019ll work with the user\u2019s selection, if there is one, and the complete text otherwise. In this case, we need to keep track of which it was so that, when we do the replacement, we\u2019re only replacing the text that the user had selected.<\/p>\n
    Once we\u2019ve gotten our text, we can use markdown.toHTML<\/code> to do the conversion. Then, we put the text back into the editor (going into either selectedText<\/code> or value<\/code>, depending on where the text came from originally).<\/p>\n
    We need to tell Bespin about our new command, so we\u2019ll add another object to the provides<\/code> part of our metadata.<\/p>\n
    {\n    \"ep\": \"command\",\n    \"name\": \"markdown convert\",\n    \"description\": \"convert the selected text to HTML\",\n    \"pointer\": \"#convert\"\n}\n<\/code>\n<\/pre>\n
    Looks just like the markdown preview<\/code> command, doesn\u2019t it?<\/p>\n
    Reload the page in your browser, paste in the sample markdown text and then run the markdown convert<\/code> command. You should see the text converted to HTML. Try converting just a section of the text, and you\u2019ll see that just that portion of the file is modified.<\/p>\n
    That was easy, wasn\u2019t it?<\/p>\n
    Undo<\/h2>\n
    Try converting the Markdown to HTML and then pressing cmd\/ctrl-Z.<\/p>\n
    Submitting to the Bespin Plugin Gallery<\/h2>\n
    Once you\u2019ve completed creating a plugin that you want to share with the rest of the world, you should add a little more to the metadata before uploading your plugin to the Bespin Plugin Gallery. (As of this writing, the Bespin Plugin Gallery has not yet been released… but it’s coming soon, so you can follow this section to be ready when it’s here.)<\/p>\n
    We\u2019ll add version, license and maintainer information:<\/p>\n
    \"version\": \"1.0.0\",\n\"maintainers\": [\n    {\n        \"name\": \"Kevin Dangoor\",\n        \"email\": \"kid@blazingthings.com\",\n        \"web\": \"http:\/\/blueskyonmars.com\/\"\n    }\n],\n\"licenses\": [\n    {\n        \"type\": \"MPL\",\n        \"url\": \"http:\/\/www.mozilla.org\/MPL\/MPL-1.1.html\"\n    },\n    {\n        \"type\": \"GPL\",\n        \"url\": \"http:\/\/creativecommons.org\/licenses\/GPL\/2.0\/\"\n    },\n    {\n        \"type\": \"LGPL\",\n        \"url\": \"http:\/\/creativecommons.org\/licenses\/LGPL\/2.1\/\"\n    }\n]\n<\/code>\n<\/pre>\n
    Bespin Plugin metadata is actually a superset of the CommonJS package<\/a> metadata. As specified there, the version numbers should follow the Semantic Versioning<\/a> numbering so that useful information about compatibility can be picked up from the version number alone.<\/p>\n
    I added myself as a maintainer and made this plugin available under the tri-license that Bespin itself is available under.<\/p>\n
    With all of this metadata in place, the final plugin file looks like this:<\/p>\n
    \"define metadata\";\n({\n    \"dependencies\": {\n        \"markdown_js\": \"0.1.2\"\n    },\n    \"provides\": [\n        {\n            \"ep\": \"command\",\n            \"name\": \"markdown\",\n            \"description\": \"commands for working with markdown files\"\n        },\n        {\n            \"ep\": \"command\",\n            \"name\": \"markdown preview\",\n            \"description\": \"preview the HTML form of this markdown text\",\n            \"key\": \"ctrl_shift_p\",\n            \"pointer\": \"#preview\"\n        },\n        {\n            \"ep\": \"command\",\n            \"name\": \"markdown convert\",\n            \"description\": \"convert the selected text to HTML\",\n            \"pointer\": \"#convert\"\n        }\n    ],\n    \"version\": \"1.0.0\",\n    \"maintainers\": [\n        {\n            \"name\": \"Kevin Dangoor\",\n            \"email\": \"kid@blazingthings.com\",\n            \"web\": \"http:\/\/blueskyonmars.com\/\"\n        }\n    ],\n    \"licenses\": [\n        {\n            \"type\": \"MPL\",\n            \"url\": \"http:\/\/www.mozilla.org\/MPL\/MPL-1.1.html\"\n        },\n        {\n            \"type\": \"GPL\",\n            \"url\": \"http:\/\/creativecommons.org\/licenses\/GPL\/2.0\/\"\n        },\n        {\n            \"type\": \"LGPL\",\n            \"url\": \"http:\/\/creativecommons.org\/licenses\/LGPL\/2.1\/\"\n        }\n    ]\n});\n\"end\";\n\nvar env = require('environment').env;\nvar markdown = require(\"markdown_js\");\n\nexports.preview = function(args, request) {\n    var text = env.editor.selectedText;\n    if (!text) {\n        text = env.editor.value;\n    }\n    var popup = window.open(\"\", \"_blank\", \"location=no,menubar=no\");\n    popup.document.body.innerHTML = markdown.toHTML(text);\n    request.done();\n};\n\nexports.convert = function(args, request) {\n    var allOrSelection = 'selectedText';\n    var text = env.editor.selectedText;\n    if (!text) {\n        allOrSelection = 'value';\n        text = env.editor.value;\n    }\n    var html = markdown.toHTML(text);\n    env.editor[allOrSelection] = html;\n    request.done();\n};\n<\/code>\n<\/pre>\n
    We can upload this single .js file to the plugin gallery to share it with others. Once we do, we\u2019ll have a change to add images and further description of the plugin if we wish. You can actually add a description to the plugin metadata itself, if you wish.<\/p>\n
    The End<\/h2>\n
    In this tutorial, we created a brand new plugin that leveraged an existing JavaScript library to do useful text transformation in Bespin. Key concepts covered:<\/p>\n
      \n
    • using dryice server mode to test new plugins<\/li>\n
    • plugin structure and metadata<\/li>\n
    • the mechanics of creating an extension<\/li>\n
    • how to write command extensions<\/li>\n
    • how to manipulate the text in the editor<\/li>\n<\/ul>\n","protected":false},"excerpt":{"rendered":"
      In this tutorial, we\u2019ll be creating new commands that allow Bespin to work with Markdown formatted text.<\/p>\n","protected":false},"author":456,"featured_media":0,"comment_status":"closed","ping_status":"closed","sticky":false,"template":"","format":"standard","meta":{"footnotes":""},"categories":[1],"tags":[],"_links":{"self":[{"href":"https:\/\/blog.mozilla.org\/labs\/wp-json\/wp\/v2\/posts\/5090"}],"collection":[{"href":"https:\/\/blog.mozilla.org\/labs\/wp-json\/wp\/v2\/posts"}],"about":[{"href":"https:\/\/blog.mozilla.org\/labs\/wp-json\/wp\/v2\/types\/post"}],"author":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/labs\/wp-json\/wp\/v2\/users\/456"}],"replies":[{"embeddable":true,"href":"https:\/\/blog.mozilla.org\/labs\/wp-json\/wp\/v2\/comments?post=5090"}],"version-history":[{"count":0,"href":"https:\/\/blog.mozilla.org\/labs\/wp-json\/wp\/v2\/posts\/5090\/revisions"}],"wp:attachment":[{"href":"https:\/\/blog.mozilla.org\/labs\/wp-json\/wp\/v2\/media?parent=5090"}],"wp:term":[{"taxonomy":"category","embeddable":true,"href":"https:\/\/blog.mozilla.org\/labs\/wp-json\/wp\/v2\/categories?post=5090"},{"taxonomy":"post_tag","embeddable":true,"href":"https:\/\/blog.mozilla.org\/labs\/wp-json\/wp\/v2\/tags?post=5090"}],"curies":[{"name":"wp","href":"https:\/\/api.w.org\/{rel}","templated":true}]}}