jQuery .end() explanation & examples

jQuery's .end() method is one of the most rarely used methods that I know of. In this post I would like share remind you what it does and how we can use it to make our jQuery code more readable.

Firstly, what does it do?

Put simply .end() cancels the last filtering action and returns a set like it was before the filtering was applied. It's best explained with an example. Consider we have this HTML code:

<ul>
  <li>One</li>
  <li>Two</li>
  <li class="special">>Three</li>
</ul>

$('li')  // would have all 3 elements

$('li').filter('.special')  // would have 1 (third) element only

$('li').filter('.special').end()  // would have all 3 elements again

Now, the main question: Why on earth would you need it?! It is actually very useful when you have to apply different methods on several sub-selections in your DOM. The game development fits this case perfectly. I have seen beautiful and easy to understand game code that was made possible by a combination of custom jQuery selectors, extending jQuery and .end() method.

Couple of examples

To give you an idea of what a code of some hypothetical game might look like:

check_mines = function(from, to_coord){  // don't pay attention to this building block
     $("#game-canvas")

          .find("div:ships")
               .moveElements(from, to_coord)
          .end()

          .find("div:mines")
               .killIfClose(to_coord)
          .end()

          .find("div:healthPack")
               .addHealthIfClose(to_coord)
               .markHealthPackUsed(to_coord)
          .end();

};
SomeGame.register(check_mines);  // don't pay attention to this building block

As you can see, .end() helps us group related actions and make the code more readable.

Let's consider more realistic case. Let's say we have an article with images, links etc. (eg. Wikipedia articles). We need to add .content-img class to all images, than add .external-link to all external links, and finally apply a tooltip plugin to all the links that have .tooltip class within the article.

<div class="article">
     <p>Text ... </p>
     ...
</div>

$(".article")

    .find("img")
        .addClass("content-image")
    .end()  // back to .article set

    .find("a:external")
        .addClass("external-link")
    .end() // back to .article set

    .find("a.tooltip")
        .tooltip()
    .end(); // don't really need it here, but nice to have for symmetry

The above case is better written in 3 separate lines of codes of course, but it here to help explain the purpose of the .end().

NOTE:
If you do several filtering, you must call .end() several times as well.

$(".article").find("a").filter(".tooltip").end().end();

Hope you will find useful cases for .end() in your projects.