braindump.io

Project Specific Syntax Highlighting in Sublime Text 3

Fri, 26 Sep 2014 00:00:00 +0000

At any given time, I have several projects that I’m working on or maintaining. It’s not uncommon for these projects to use different technology stacks (Meteor, Jekyll, Backbone, etc), and since I mainly develop web applications, these projects almost always include HTML files. Each stack, however, generally has its own HTML templating engine with its own syntax. It could be Handlebars, Liquid, Underscore, etc. This is where a stock Sublime Text setup falls short.

There’s no built in way (that I could find) to configure one project to use a specific syntax highligher for HTML files, and another project to use a different syntax highlighter. I searched for solutions to the problem, but came up empty, so I decided I may as well write my first Sublime Text plugin. And today I share it with you.

First off, you’ll need to save the python code below to a file in your Packages/User directory. Where this directory is located depends on your system. On MacOS, it’s at ~/Library/Application Support/Sublime Text 3/Packages/User. Give the file a name such as project_specific_file_syntax.py.

import os.path
import re
import sublime_plugin

class ProjectSpecificFileSyntax(sublime_plugin.EventListener):
    def on_load(self, view):
        filename = view.file_name()
        if not filename:
            return

        syntax = self._get_project_specific_syntax(view, filename)
        if syntax:
            self._set_syntax(view, syntax)

    def _get_project_specific_syntax(self, view, filename):
        project_data = view.window().project_data()

        if not project_data:
            return None

        syntax_settings = project_data.get('syntax_override', {})

        for regex, syntax in syntax_settings.items():
            if re.search(regex, filename):
                return syntax

        return None

    def _set_syntax(self, view, syntax):
        syntax_path = os.path.join('Packages', *syntax)

        view.set_syntax_file('{0}.tmLanguage'.format(syntax_path))

Now, you just need to add a syntax_override section to your .sublime-project file, like so.

{
    ...

    "syntax_override": {
        "\\.html$": [ "HTML Underscore Syntax", "HTML (Underscore)" ]
    }
}

The syntax_override section can contain as many key/value pairs as you like. The key should be a regular expression that will be matched against the name of the file. Note that the . in .html has to be escaped to \. since it will match any character otherwise. And since this is a JSON string, we need to escape the slash, so we end up with \\.. The value in the key/value pair should be an array containing two strings. The first string is the name of the package containing the syntax file and the second is the name of the syntax. Root around in Sublime Text’s directory structure to find files that end with .tmLanguage. The names of these files (minus the .tmLanguage extension) are what you would use for the second string.

Unfortunately, Sublime Text 2 users are out of luck as the plugin API for that version does not appear to provide access to project settings. You’ll just have to upgrade to Sublime Text 3. Happy coding!

Publishing to an Alternative Client-side Collection in Meteor

Sat, 20 Sep 2014 00:00:00 +0000

When publishing a bunch of documents to the client with Meteor.publishComposite, we sometimes end up with a perplexing problem on the client side of things. How do we figure out which published documents were intended for which purpose?

Note: This post assumes some familiarity with Meteor.publishComposite. If you haven’t used Meteor.publishComposite before, I recommend reading my previous post, Publishing Reactive Joins in Meteor, first.

Maybe this problem can be better illustrated through example. Say we are publishing a list of the top ten articles on our site and want to include some related articles for each one. These related articles will be published via the children option of Meteor.publishComposite. Normally, all the articles, both parents and children, would end up in the same collection on the client (e.g., Articles) making it difficult to determine which ones are the top ten articles and which are the related articles. What if, instead, we could publish the related articles into a separate client-side collection (e.g., RelatedArticles)? That would be amazingly helpful, wouldn’t it? Well, it’s a good thing you’re reading this blog post, because you can do exactly that with Meteor.publishComposite using the collectionName option.

The collectionName option instructs Meteor.publishComposite to tell the client a little lie and say that whatever documents come out of the cursor returned by the find option came from a different collection. Here’s an example to demonstrate.

// The Articles collection is present on both client and server and is
// backed, as usual, by MongoDB.
Articles = new Meteor.Collection("articles");

if (Meteor.isServer) {
    // We create our publication on the server. Note the "collectionName" option.
    Meteor.publishComposite("topTenArticles", {
        find: function() {
            return Articles.find({}, { sort: { score: -1 }, limit: 10 });
        },
        children: [
            {
                // Here we specify the client-side collection name we would
                // like to publish these records to.
                collectionName: "relatedArticles",

                find: function(article) {
                    return Articles.find({ relatedTo: article._id }, { limit: 2 });
                }
            }
        ]
    });
}

if (Meteor.isClient) {
    // The RelatedArticles collection is only present on the client. It's contents
    // are not persisted anywhere, but instead come from the publication.
    RelatedArticles = new Meteor.Collection("relatedArticles");

    // Subscribe to the publication, perhaps in our router's waitOn method
    Meteor.subscribe("topTenArticles");

    // The Articles collection will contain just the top ten articles
    var topTenArticles = Articles.find();

    // The client-side RelatedArticles collection will contain the related articles
    var relatedArticles = RelatedArticles.find();
}

Publishing Reactive Joins in Meteor

Fri, 12 Sep 2014 00:00:00 +0000

Publishing many related documents from different MongoDB collections in your Meteor app can be a hairy problem. You might find yourself calling Meteor.publish several times to get all the documents you need pushed to the client. The reywood:publish-composite package was created to solve this problem in a flexible manner. It exposes one new function called Meteor.publishComposite.

For the purposes of this post, I’m going to assume that you’re already familiar with Meteor, and that you’re capable of following the simple installation instructions on the reywood:publish-composite page.

The basics

Let’s say you run a site that allows users to post articles and also comment on those articles. Let’s also say that, for whatever reason, you want to normalize this data so that articles and comments are in separate collections. You’d have a couple of collections defined in your Meteor code that look like this.

Articles = new Meteor.Collection("articles");
Comments = new Meteor.Collection("comments");

An article document might look like:

{
    "_id": "article1",
    "createdAt": ISODate("..."),
    "authorId": "user1",
    "title": "Teen petitions to get cat, lasers in yearbook photo",
    "body": "A student is petitioning for the right ..."
}

And a comment document might look like:

{
    "_id": "comment1",
    "createdAt": ISODate("..."),
    "authorId": "user2",
    "articleId": "article1",
    "comment": "Ugh, these freakin' teens with their cats and their lasers.",
    "score": 9000
}

Let’s also say that the authorId field in each document points to a user in Meteor.users, and you’ve chosen not to denormalize the names of the authors into the articles and comments documents because … well, who knows. We’re talking in hypotheticals here, so save whatever document database best practices rage is bubbling up inside you for the real world.

Now, let’s say you want to publish a list of the ten newest articles along with the top two comments on each one and the names of the authors of both the articles and the comments. Using Meteor.publish, you’d have to create lord only knows how many subscriptions (at least three, I guess). There must be a better way, right? Right?! Yes, there is a better way, and it’s called Meteor.publishComposite.

With Meteor.publishComposite you can publish this whole hierarchy of documents in a flexible manner with one publication. Here’s how you would accomplish the convoluted task I’ve set before you.

Meteor.publishComposite("tenNewestArticles", {
    find: function() {
        // Let's go ahead and find those ten newest articles
        return Articles.find({}, {
            sort: { createdAt: -1 },
            limit: 10
        });
    },
    children: [
        {
            find: function(article) {
                // And let's find each article's author. Now, you might
                // think you could use findOne instead of find here, but
                // you'd be wrong. More on this in a bit. Note we get an
                // article document passed in as an argument.
                return Meteor.users.find({ _id: article.authorId });
            }
        },
        {
            find: function(article) {
                // And the top two comments on each article
                return Comments.find(
                    { articleId: article._id },
                    { sort: { score: -1 }, limit: 2 });
            },
            children: [
                {
                    find: function(comment, article) {
                        // And those comments' authors. Hey! We have two
                        // args this time! We get all the documents going
                        // up the hierarchy passed in. Nearest parent
                        // gets passed in first.
                        return Meteor.users.find({ _id: comment.authorId });
                    }
                }
            ]
        }
    ]
});

The first argument to Meteor.publishComposite, as you guessed, is the name of the publication. Nothing new there. The second argument is an object literal with two properties, find and children.

The find property is a function which returns a cursor. This is very important. The find function must return a cursor which is why we use Meteor.users.find instead of Meteor.users.findOne to find the authors. Returning a cursor is what makes this whole thing reactive. Also worth noting, find functions are run in the context of your publication, so you’ll have access to properties like this.userId as you would in a normal publication.

The children property is an array containing yet more object literals with find and children properties. The find function for a child is called for each document returned in the parent find’s cursor with that parent document as the argument. So for each article returned in the topmost find, the two child find functions are called to find the author and the top two comments. The children property is optional at every level in the hierarchy.

Remember when I said that find must return a cursor. Well, I lied … a little. There will be times when you don’t want to publish anything because some check condition failed. Maybe you only want to publish something if the user is logged in. In this case, your find function can return a falsy value (undefined, null, etc) and the publication will short circuit. That might look something like this.

Meteor.publishComposite("membersOnly", {
    find: function() {
        if (!this.userId) {
            return;
        }

        return MyPreciousssss.find({ ... });
    },
    children: [
        // ...
    ]
});

Reactivity and duplicate data

Meteor.publishComposite will publish additions, changes, and removals affecting your documents the same way Meteor.publish does. But what would happen if the authorId field of an article changed? Drat, now the wrong author document from Meteor.users is published to the client. Not to worry, Meteor.publishComposite will see that the article has changed and check to see if any of it’s child documents need to be added, changed, or removed. The old author will be removed and the new one added.

This leads to another interesting question. We’ve published a bunch of articles and comments, each with an associated author. What if multiple articles and/or comments were penned by the same author? Are we going to send that author’s document to the client multiple times. Luckily for us, Meteor.publishComposite is smart enough to know when it has already sent a document to the client and won’t repeat itself.

Passing arguments

Now I know what you’re thinking “Wait a minute! I can pass arguments to a normal publication. What gives?” Meteor.publishComposite can also accept a function as its second argument instead of an object literal. This function just has to return the object literal that we described above. Maybe you want to publish all the articles by a particular author. Let’s go ahead and do that.

Meteor.publishComposite("articlesByAuthor", function(authorId) {
    return {
        find: function() {
            return Articles.find({ authorId: authorId });
        },
        children: [
            // ...
        ]
    };
});

Pretty straighforward, yes?

A word about flexibility

So far, our examples have generally mapped a primary key in one record to a foreign key in another record, much like you would with a standard ORM. Meteor.publishComposite aims to give you more flexibility than that.

Say you want to publish an article for display. After displaying the article, you’d like to provide links to the articles that were created immediately before and after. Not too difficult.

Meteor.publishComposite("articleAndFriends", function(articleId) {
    return {
        find: function() {
            return Articles.find({ _id: articleId });
        },
        children: [
            {
                find: function(article) {
                    // Get the previous article
                    return Articles.find(
                        { createdAt: { $lt: article.createdAt } },
                        { sort: { createdAt: -1 }, limit: 1 });
                }
            },
            {
                find: function(article) {
                    // Get the next article
                    return Articles.find(
                        { createdAt: { $gt: article.createdAt } },
                        { sort: { createdAt: 1 }, limit: 1 });
                }
            }
        ]
    };
});

Get as creative as you like with your relationships.

Alright already, let’s wrap this up

So there you are. You’ve published a bunch of documents from various collections and in a somewhat sensible manner. Feels good, doesn’t it?