I’ll show you how to toggle the visibility on a group of selected elements. I’ll build up from a simple case to the more complicated ultimate goal.

First, whenever you’re working with jQuery and Javascript, you should probably get your references ready. For online references there’s the jQuery documentation (which is easier to search with Google than with the site search, I find) and the Mozilla Development Center Javascript reference among others. A very nice site to test, store, and share your jQuery snippets is jsFiddle.

Ok, let’s get started. First let’s toggle the visibility of an element with jQuery using .toggle(). Since we’re talking about user interfaces, we’ll probably trigger the toggle with an action, let’s say a .click():

1. $(document).ready(function(){

2.       // Toggle the visibility of all divs when one is clicked.

3.     $("input").click(function() {

4.         $("div").toggle();

5.     });

6. });​​

jsFiddle example

The code above will toggle the visibility of all the divs on a page if an input button is pressed.  The way this works is that after the document is ready, an event handler is bound to all the <input> elements. The handler waits for the user to click it. If clicked jQuery selects all the divs on the page and reverses their visibility. If they were invisible they become visible and vica versa.

Well, this was just to give you a tast of .toggle(), since the above example is pretty crude. Usually you want more control over which divs appear and disappear. In fact, an often trick part of visibility toggling in jQuery is to make sure each toggling button is linked uniquely to one block of content. You also want to ensure that when a block of content appears, all the other similar blocks of content disappears.

I’ll show you two methods of making sure that each time only one block of content appears, while all the other blocks of content disappears. The first method will only work if all the content blocks are siblings in the DOM. This will often be the case, since we’ll usually be dealing with semantically related chunks of content. The second way will be a little trickier but more flexible.

But before we start discussing siblings, let’s make sure we can toggle one specific div with one particular button. There’s many ways of doing this. I’ll show you how to use individual but related ids for the buttons and the content divs. Each button will have a name like, “block-x” where “x” is a number, and it’ll have a corresponding content block with the id “block-x-content”. Now if we have 3 content blocks, we could write one functions to control each block, for a total of 3 functions, but it’s more convenient and maintainable to generalize. We’re going to use input buttons with class “.toggler” to toggle the divs. You, of course, don’t have to use buttons, you can use other divs, or images, or whatever your little heart desires. So, so far we have:

1. $(document).ready(function(){

2.       // Toggle the visibility of all divs when one is clicked.

3.     $("input.toggler").click(function() {

4.         $( "#" + $(this).attr("id") + "-content" ).toggle();

5.     });

6. });​

jsFiddle example

The most complex part is the line with the toggle. The previous line simply binds an click event handler to all input elements with a “toggler” class. The function that is triggered in case of a click is an anonymous function that toggles one div. To see witch div gets toggled we’ll look more closely at “$(“#” + $(this).attr(“id”) + “-content” )” . The part inside the parentheses is simply a jQuery selector string. The string starts with a literal “#”, so we know that an element with a certain ID is getting toggled. The “#” is followed by the “ID” attribute of the element that was clicked. So far we have something like $(“#block-x”). This by itself would make the buttons disappear. But we know that each button has a corresponding content block. This block is selected by concatenating “-content” to the previous to give us a toggling of $(“#block-x-content”). Where is the number in the ID attribute of the INPUT button we clicked. Notice how the visibility of each DIV is kept track of separately. .toggle() is doing all the hard work for us.

Well, we’re approaching what we want. The previous example is okay, in that it let’s us toggle things, but it doesn’t really feel like we’re concentrating the attention of the user to one pertinent block of information. To achieve that end, we must make all the other divs invisible when we make one div visible.

We only have to change one line to achieve this. We’ll go from:

$( "#" + $(this).attr("id") + "-content" ).toggle();

to:

$( "#" + $(this).attr("id") + "-content" ).toggle().siblings().hide();

Notice how I chained the methods .siblings() and .hide() onto the previous line. This means that after toggling our content block, we’ll select the DOM siblings of that block and make them invisible. This means you have to make sure you’ve thought through your HTML. The easy way to do this is to nest all the content divs into a parent div, or if it makes sense, maybe to have content LIs in a parent UL or OL.

One finally change is that you may not want the content to disappear if a button is pressed twice, so we’ll switch out .toggle() with .show() to give:

1. $(document).ready(function(){

2.       // Toggle the visibility of all divs when one is clicked.

3.     $("input.toggler").click(function() {

4.         $( "#" + $(this).attr("id") + "-content" ).show().siblings().hide();

5.     });

6. });​

jsFiddle example

But what if our content DIVs aren’t siblings? They usually should be, just because of the way information is structured on an HTML page, but we really don’t want to count on that. We want the flexibility to toggle any set of elements we want.

To toggle any set of elements we want, all we have to do is create jQuery set of the elements and use .not() in combination with that. I’ll show you how.

First, let’s say that we have 3 content divs. Let’s select all of them with jQuery:

var theDivs = $("#block-1-content, #block-2-content, #block-3-content);

So, now theDivs is a jQuery selection of out content DIVs, let’s use that in combination with our click handler and .not() to toggle the appropriate content divs. Except, now I’m going to use an unordered list, so our content will be in LIs. If we’re dealing with unordered lists, we could easy have a situation where all the individual content LIs are not siblings of each other.

To show the corresponding content LI of a button, we’ll still use:

$( "#" + $(this).attr("id") + "-content" ).show();

But now we can’t simply make the siblings disappear. Instead we’ll make everything from our jQuery slection “theDivs” that isn’t the corresponding content LI vanish. Like this:

theDivs.not( $( "#" + $(this).attr("id") + "-content" ) ).hide();

And that’s it! You can of course replace the .show() and .hide() methods with fancier animations like .slideDown() and .slideUp(), but overall we have a relatively simple to implement, generalizable way of toggling the visibility of a group of content divs. The full code will look something like this:

1. $(document).ready(function(){

2.       // Create a selection of the content divs of interest

3.     var theDivs = $("#block-1-content, #block-2-content, #block-3-content");

4.       // Toggle the visibility of all divs when one is clicked.

5.     $("input.toggler").click(function() {        

6.         $( "#" + $(this).attr("id") + "-content" ).show();

7.         theDivs.not( $( "#" + $(this).attr("id") + "-content" ) ).hide();

8.     });

9. });​

jsFiddle example

Here are links to a few of them:

Ah, speaking of downloading JQuery, you just might want to understand how JQuery works if you use it. The first time I tried to do this, I simply clicked on my JQuery src file link:

1. <script type="text/javascript" src="http://peter-ajtai.com/jquery/jquery-1.4.2.min.js"></script>

… and this is what I saw:

Fun reading, huh? Well, when your browser loads Javascript, it has to load each charachter, so the less whitespace there is, and the shorter the variable names are, the faster it will load.

This means you should be using this, the minified, version of JQuery on your site, but if you want some pleasant and relaxing reading… you should look at the uncompressed version. JQuery shows you both versions very clearly on their download page, but for some reason, it took me a while to realize that there is an uncompressed version. The uncompressed version of the latest version is here. The uncompressed version is actually very readable:

Step 1:

Load JQuery and your custom JS onto your page with wp_enqueue_script(). It’s better to use wp_enqueue_script than hard coding it into your page. This is because WordPress comes with JQuery, so you won’t have to worry about updating JQuery as new versions come out. WordPress will do the work for you.  Make sure wp_enqueue script is before wp_head(), or it won’t work.

Here’s a snippet from my template file (let’s say index.php). I’ve created my custom JQuery functions in my themes “scripts” directory with the file name “custom-js.js”. You also have to make up a handle or name for your collection of custom JQuery functions. I called mine custom:

1. <?php

2.     wp_enqueue_script('jquery');

3.     wp_enqueue_script('custom', get_bloginfo('stylesheet_directory') . '/scripts/custom-js.js');

4.     wp_head(); // WP API Hook

5. ?>

get_bloginfo is your friend. If you hard code your themes directory into your code anywhere, you won’t be able to share it with others, and you’ll break everything if you ever move hosts or just directories.

Here’s another example. Let’s say you want to use Google Maps on your page. Here is the line of WP code that makes that possible:

1. <?php

2.     wp_enqueue_script('googleMaps', 'http://maps.google.com/maps/api/js?sensor=false');  

3. ?>

Finally, if you just want plain JS with no JQuery, you can simply leave out the line that calls JQuery but leave in the line that enqueues your custom functions. WordPress comes with a lot of other JS goodies besides JQuery. Scroll down to the bottom of this page to look at all the other stuff included with WordPress.

Step 2:
Write your JQuery. The only thing you have to look out for is that wp_enqueue_script() calls JQuery in no conflict mode. This means that $ will not work as a shortcut for JQuery functions. There are two simple solutions.

1. Define another shortcut for JQuery functions.
2. Use a wrapper around your JQuery code.

Here is how to define a new shortcut for JQuery functions, $j in this case. The script shown is a very effective test to see if you’ve got JQuery working in your theme. It’s a little blunt, but it’s effects are hard to miss.

1. var $j = jQuery.noConflict();

2. $j(document).ready(function(){

3.  $j("body").html("Your page is belong to us... just kidding, but you can use JQuery now.");

4. });

Here is how to use a wrapper in order to use the default JQuery shortcut:

1. jQuery(document).ready(function($) {

2.     $("body").html("Your page is belong to us... just kidding, but you can use JQuery now.");

3. });

Make sure you pay attention to all the curly brackets and parentheses. If the long and multiple parenthetical expressions annoy you, go check out Lisp.

Anyway, the second method is nice, since it let’s you use previously written code easily.

Step 3:

Enjoy!

Notice that the entire highlighted area is clickable, not just the lettering.

I’ll describe a simple way to make pure CSS menu links that highlight nicely when hovered over. Now, you can obviously get a lot fancier with Javascript, but a good website design degrades nicely. This means that you should stack as much functionality into the (X)HTML and CSS as you can, and then add extras on with Javascript. This will enable you to read the page nicely through the widest range of media. This is important these days when you don’t know whether your visitors are using a cell phone, iPAD, curl on a UNIX shell, text reader for the vision impaired, or whatever. There are obviously some things Javascript is great for, but there’s no need to kill a fly with an elephant gun. Don’t use it when you don’t have to.

The W3C page has a nice example of elegant page degradation when Javascript is turned off. The menu links on the left hand side of the page, for example the ones under standards, flash dark gray before settling to light gray when hovered over. The flash is Javascript. When you turn Javascript off, notice that the flash is gone, but the links are still highlighted in the same way. You can click anywhere in the Menu box to follow the link, not just over the lettering, and the entire menu box is highlighted in light gray.

Ok let’s build a similar but simpler vertical menu. Horizontal menus are easier to highlight, since the horizontal width of each box can vary without having the menu look unnatural.

Our menu will have three items: Home, Gnome, and Rome. It often makes sense to put your menu items in an unordered list, so we’ll do that, and we’ll set a fixed with for the items. We’ll use a 440 px body width and 220px menu width, just so you can easily see the results as displayed in this blog.

Ok, let’s set up the menu with simple highlighting using “a:hover”.

You can take a look at the menu above on its own page. Here is what that code looks like (remember to use style sheets; I used a style definition in head, so that all the code could be read easily in one go, but unless you like to individually and tediously change CSS rules one at a time for hundreds or thousands of pages, you’d better use external style sheets):

Bad Hover Menu

1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

2. <html xmlns="http://www.w3.org/1999/xhtml">

3.     <head>

4. 	<style type="text/css">

5. 	    #da-body {

6. 	        background-color:#A6734A;

7. 	        width:440px;

8. 	    }

9. 	    #da-menu {

10. 		list-style-type:none;

11. 		width:220px;

12. 	    }

13. 	    div#da-body ul#da-menu li a {

14. 		font-size:180%;

15. 		line-height:220%;

16. 		color:#FAEAF3;

17. 	        text-decoration:none;

18. 	    }

19. 	    div#da-body ul#da-menu li a:hover {

20. 		background-color:#BFB6AF;

21. 	    }

22. 	</style>

23.     </head>

24.     <body>

25. 	<div id="da-body">

26. 	    <ul id="da-menu">

27. 		<li><a href="#">Home</a></li>

28. 		<li><a href="#">Gnome</a></li>

29. 		<li><a href="#">Rome</a></li>

30. 	    </ul>

31. 	</div>

32.     </body>

33. </html>

If you hover over a link, the background changes in color. Yeah, but it’s not very elegant, since the area that’s highlighted has a different shape for each link. Additionally, you have to be pretty precise with you mouse. The list takes up half the colored area, but you have to hover directly over letters in order to follow a link. Let’s deal with the first problem first.

It turns out that :hover is a valid pseudo class for a list item not just a. So if we change the a:hover code to li:hove like this:

1. div#da-body2 ul#da-menu2 li:hover {

2.     background-color:#BFB6AF;

3. }

We’ll see this:

Now we’re getting close. The problem is that you cannot click the entire highlighted area to follow the link. This is because we’re highlighting the li element and not the a element. Ok, well how about:

1. /* THIS WILL NOT WORK!!! */

2. div#da-body2 ul#da-menu2 a {

3.     width:100%

4. }

5. div#da-body2 ul#da-menu2 a:hover {

6.     background-color:#BFB6AF;

7. }

8. /* ^^ INCORRECT */

Nope, that’ll basically just look like the first example. The problem is that the “a” element cannot have a width attribute. It’s not a block level element. You can’t set it’s width normally.

Don’t you wish we could simply display the anchor element like a block item, in this case like a list item, and then we could set its width. Well, CSS knows about inheritance, and there is a display attribute. We just have to force the “a” or anchor tag to act different than usual using, “display:inherit;”. This means that the “a” tag will inherit whatever display mode its parent element has. In this case it will will inherit the “block” display from the li element. So, our solution is:

1. div#da-body ul#da-menu a {

2.     display:inherit;

3.     width:100%

4. }

5. div#da-body ul#da-menu a:hover {

6.     background-color:#BFB6AF;

7. }

This will produce:

Incidentally, “display:block” will work too. To wrap up, here is the full code:

Good Hover Menu:

1. <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">

2. <html xmlns="http://www.w3.org/1999/xhtml">

3.     <head>

4.         <style type="text/css">

5.             #page {

6.                 background-color:#A6734A;

7.                 width:440px;

8.             }

9.             #menu {

10.                 list-style-type:none;

11.                 width:220px;

12.                 padding:0;

13.                 margin:0;

14.             }

15.             div#page ul#menu li {

16.                 padding:0;

17.                 margin:0;

18.             }

19.             div#page ul#menu li a {

20.                 display:inherit;

21.                 width:100%;

22.                 font-size:180%;

23.                 line-height:220%;

24.                 color:#FAEAF3;

25.                 text-decoration:none;

26.                 text-indent:0.5em;

27.             }

28.             div#page ul#menu li a:hover {

29.                 background-color:#BFB6AF;

30.             }

31.         </style>

32.     </head>

33.     <body>

34.         <div id="page">

35.             <ul id="menu">

36.                 <li><a href="#">Home</a></li>

37.                 <li><a href="#">Gnome</a></li>

38.                 <li><a href="#">Rome</a></li>

39.             </ul>

40.         </div>

41.     </body>

42. </html>

Incidentally, you can see that I’ve got a few margin:0s and padding:0s thrown in to make things look neater. Instead of dealing with zeroing the margins, paddings, etc. for each item one by one, you can simply use a CSS reset. You can put this at the top of your style sheet, or add it in as a separate style sheet. I didn’t use a CSS reset for this example, since I wanted to keep the code as self contained as possible.

Ok, that’s all the hovering over CSS menus for today.

That sounds pretty good and rather vague. It’s hard to describe what you can do with WordPress themes, since they can do a lot. It’s like trying to describe all the things you can do with a nail. It all depends on how you use it.

In light of this, it seems like the best thing to do would be to go through an example of building a WordPress theme. I’ll go through a theme as I develop it, and I’ll try to build it starting at the simplest level and working to progressively more complicated iterations.

Before we begin, there’s a few things that I’m going to assume:

1. You’ve got WordPress installed on your site. It’s usually pretty easy to install WordPress.
2. You can access the files in your WordPress install.
3. You can access your WordPress admin panel.

You can usually access your files through FTP, SSH, or even your web host’s control panel. On Windows I usually use PuTTY for SSH. I’ve heard good things about FileZilla for FTP, but I’ve personally never tried it. You can edit your files with anything from Notepad (ugh) to Notepad++ (yay!) to Dreamweaver (for all the flack Dreamweaver gets, it sure can speed up a lot of things), Emacs (hang on, let me grow a beard and put on my glasses)…

Actually, in spite of the beard and glasses joke, if your host offers a Unix or Linux shell, then working on your pages with Emacs can be a great pleasure. I mean you have access to not just your files, but also to your files through one of the most powerful “word processors” in the world. No more worrying about whether your files are on your desktop, laptop, smartphone, or smartbrain. Anyway, Emacs is fun and free (free as in hair, and yanking it out in frustration while you pound your head against the keyboard trying to understand what a Lambda expression is). No, but seriously, using Emacs through SSH courtesy of your web host is fantastic stuff, and lets them work a little for the money you give them. I will shamelessly mention that I use Dreamhost, and so can you by clicking on that link that will earn me money when you sign up.

Ok, you’ve got WordPress installed, and you can access the files on your server. Let’s start building a theme.

The way WordPress works is that it runs a bunch of PHP create the HTML for your web pages. These PHP pages will often look into an associated MySQL database for info. The PHP will also look (ok, I’m definitely anthropomorphizing) in specific directories for certain things.

One of these special directories contain all the themes that you have installed. Each theme is in its own folder, and you can pick the theme to use through the WordPress admin panel.

You can find the theme choices on the left side of the adminn panel under “Appearance”:

The directory that the themes you can pick from are in is:

/wp-content/themes/

Each directory in themes is a theme you can use. Understanding how WordPress knows that the contents of these directories are themes will help us create our first theme.

WordPress looks at the main stylesheet in each directory, and from this style sheet it reads the information about the theme. You have to know that convention that for WordPress the main style sheet is a file called, “style.css”. So the simplest theme is just a style sheet in a directory. Let’s see how to make one of these themes…

Let’s look at this in practice. Here’s is what the themes page looks like when /wp-content/themes only has the Classic theme in it. In other words /wp-content/themes only has a directory named “classic” in it, and the index.php file:

As you can see, I’m currently redoing Evergreen Ice Sports web page. Soon it’ll look nicer and be easier to maintain for the site owners. Anyway, as you can see currently Classic is the only available theme.

If we create a directory with only a style sheet called “style.css” in it, we can use that style sheet to:

1. Tell WordPress that the directory the style sheet is in contains a WordPress theme.
2. Tell WordPress that theme is just like another theme with a few modifications (in other words the theme is a child theme).

Ok, let’s step through this and then discuss it. First create a directory called, “mytheme” in wp-content/themes . Now reload the Manage Themes page in the admin panel to see what happened:

This shows you that I was telling the truth about WP looking in the wp-content/themes directory for the available themes. It looked in your empty directory called mythemes, and since it the information about each theme is supposed to be in the main style sheet, and there is no style sheet in mythemes, we have a broken theme.

Let’s add a stylesheet over at wp-content/themes/mytheme/style.css. This style sheet will contain all the necessary information to create a WordPress theme. Here are all of the contents:

1. /*

2. Theme Name:     My Theme

3. Theme URI:      http: //netlumination.com/

4. Description:    Child theme spawned by the Classic theme

5. Author:         Peter Ajtai

6. Author URI:     http: //peter-ajtai.com/

7. Template:       classic

8. Version:        1.0

9. */

Yup, that’s all it takes, and yeah replace my info with your info, but make sure that line 7 stays untouched. The file contains only CSS comments. WordPress, reads these comments, and when it sees line 7, that says “Template: default”, it understands that mytheme is a child theme of the theme that is in the directory called, “classic”. Let’s reload the Themes admin panel and activate this new theme.

You can see how WordPress used the information in the CSS file to fill in the information about our new theme. You’ll notice that there is no screen shot for My Theme. We’ll do this soon. Anyway, click on “activate” to…. uh….. activate the theme. Since MyTheme is a child of Classic, this means that MyTheme inherits all the characteristics of Classic. We can add to or modify these characteristics, but we haven’t done that yet, so right now our theme should look identical to Classic. Visit your site’s homepage to check on this……

Whoops!

Our page looks like it has no styles! I guess I lied. MyTheme inherits everything from Classic except the style sheet. That’s a little odd right? Especially if you’re used to dealing with inheritance in things like children and object oriented programming, but no matter, it’s easier to fix than your…. well, than, many things. So, let’s grab the style sheet from the classic theme using the line:

1. @import url("../classic/style.css");

So now our entire wp-content/themes/mytheme/style.css file looks like:

1. /*

2. Theme Name:     My Theme

3. Theme URI:      http: //netlumination.com/

4. Description:    Child theme spawned by the Classic theme

5. Author:         Peter Ajtai

6. Author URI:     http: //peter-ajtai.com/

7. Template:       classic

8. Version:        1.0

9. */

10. @import url("../classic/style.css");

Ok, now go and check on how your home page looks…. Just like classic, huh? Well, that’s not very interesting, let’s make things a very tiny bit more interesting by adding one more line to prove that we have a theme that uses default but has some of it’s own rules:

1. /*

2. Theme Name:     My Theme

3. Theme URI:      http: //netlumination.com/

4. Description:    Child theme spawned by the Classic theme

5. Author:         Peter Ajtai

6. Author URI:     http: //peter-ajtai.com/

7. Template:       classic

8. Version:        1.0

9. */

10. @import url("../classic/style.css");

11. body {

12. 	background-color:blue;

13. }

Ok, that was 3 lines, but I could have made it one line. Does it work? Yup. Does it work with all themes…… uh, no. For example, if you try the same thing with the Default theme, you’ll notice that some of the background images that are used in the Default theme will not be used in your child theme. This is because the CSS for these background images are created by PHP that looks for them in the wrong directory. It’s easy to fix, but it illustrates why I’m using so many words to explain this one simple thing of how to make a child theme. If you know how all of this works, you can probably track down these problems. If you don’t know how it works, you’re lost. But these details aren’t important right now, since we want to create our own theme, not look for weird little leaks in the inheritance abstraction for WordPress themes.

You’ve just created your own WP theme! Don’t worry it gets better. We’ll do stuff that’s more useful. We’ll push pixels around around like they’re not our boss. We’ll meld code to our mind’s desire, but you’ll have to wait for the next part of this series for that… until then we’ll….. well, we’ll see you later.

So, lets say you want to look through the Odyssey and find all mentions of Sirens. That would be:

1. grep -in siren odyssey.txt

But let’s say you don’t have the Odyssey on your hard drive, you could just get it from MIT and pipe it over to grep

1. curl http://classics.mit.edu/Homer/odyssey.mb.txt | grep -in siren

In both cases, I used case insensitive search, grep -i, and I list what line number the instances are found on with -n.

So far this has all been pretty straight forward, but I know that the Odyssey is divided into books, and I want to know which books contain the lines about sirens. This is where piping becomes very handy.

1. curl http://classics.mit.edu/Homer/odyssey.mb.txt | grep -in "siren\|^book" | grep -iB1 "siren"

Let’s look at this line from left to right in order to understand it. “curl …” simply goes and gets whatever characters are at the referenced url. We pipe these lines of text into: grep -in “siren\|^book”.  This is another case insensitive search, but it is looking for each line that matches any one of two possible patterns. In regular expressions the pipe, |, means OR. When using Linux, you have to escape the pipe, and write \| to mean OR in a regular expression. So we are looking for  an appearance of the word siren OR a line that begins with the word “book.” (^ is the beginning of a line). It is important that we only use -n in the first instance of grep, since this first instance will return the line number in the original text file. If you use -n in the second grep, you won’t get the line numbers of the original file, you’ll get the line numbers from the first grep output, which is probably meaningless to you.

At this point we have all the lines which reference sirens and we have all the lines that say, “BOOK …” from BOOK I to BOOK XXIV, whether these books contain siren references or not. To clean all of this up, we take these lines, the book lines and the siren lines, and pipe them over to:  grep -iB1 “sirens”

This will take our list and display the lines one previous to a siren reference and the siren reference line. This will show us the siren references and which of the 24 books in the Odyssey reference sirens. So, if you want to read about sirens, look for Books XII and XXIII in the Odyssey.

Here is the output (edited a little for shorter lines), without the curl status output… notice that none of the lines are repeated, and that the blocks of text are separated by 2 dashes… grep at work:

1. 4936:BOOK XII

2. 4972:you will come to the Sirens

3. 4974:of the Sirens, his wife and

4. 4978:these Sirens by, and stop

5. 4986:past these Sirens, I cannot

6. 5074:the Sirens, who sit and sing

7. 5083:two Sirens, for the wind had

8. 5094:good rate, the Sirens saw

9. 5109:Sirens' voices. Then my men

10. --

11. 9638:BOOK XXIII

12. 9921:wondrous singing of the Sirens

And of course, this is just the tip of the iceberg, or should I say, just the beginning of the Siren’s song?

To learn more about grep type, “man grep” in Linux or, “M-x woman ENTER grep” in Emacs.

Table of Contents:
1: Custom Keystrokes
2: Indenting only as far as you feel comfortable
3: Indentation on steroids
4: Colorful shells
5: Colorful men
6: No more beeping, only flashing
7: Turn off annoying menu bar
8: Customizing font appearance
9: Line wrapping on horizontally split windows
10: Normal looking line wraps
11: Auto backup a little smarter
12: Autocomplete
13: Jumping the line
14: Moving from one window to the other easilly
15: Delete the entire word
16: Enabling the Num Pad
17: Making and storing macros
18: Word Count

Morsel 1 – Custom keystrokes

Make your own custom keystrokes.

Morsel 2 – Indenting only as far as you feel comfortable

Change the indentation rules in cc-mode to as many spaces as you want (I use 4, which looks like normal tabs on other editors, some people use 8, or 2, or whatever).
Edit your .emacs.d/init.el (depending it could be ~/.emacs, ~/.emacs.el, or ~/.emacs.d/init.el) like this (substitute the number you want where I write 4):

1. ;; define indents as 4 spaces in cc-mode

2. (setq c-basic-offset 4

3.       tab-width 4

4.       indent-tabs-mode t)

The first line (setting c-basic-offset) does most of the work usually. The other two lines deal with how big tabs show.

You can change the c indentation style using (setq c-default-style “[style name here]“). These styles include bsd,stroustrup, etc. Look at the Emacs wiki about indentation in C style.

Morsel 3 – Indentation on steroids

Indent an entire block of code according to applicable rules by selecting the code and then typing “C-M-\”.
For example, let’s say you just changed c-basic-offset to 4 from 8. Or you changed the c-default-style. If you now start typing a new program, then the new rules will be in effect. But, when you open a program you’ve been working on, the parts already written will look unchanged. Here’s the step by step as to what you type (remember C = Control key and M = Meta key… usually the Alt key):

1. C-x [

2. C-SPACE

3. C-x ]

4. M-w

5. C-M-\

And now your entire code is indented according to the new rules! Translation of steps 1: C-x [ is beginning of file. 2: C-SPACE is set mark for region. 3: C-x ] is end of file. 4: M-w is copy or mark regin. 5: C-M-\ is indent entire marked region according to applicable rules.

Morsel 4 – Colorful shells

Show the colors properly in shell mode.

1. ;; Deal with colors in shell mode correctly

2. (add-hook 'shell-mode-hook 'ansi-color-for-comint-mode-on)

You know you need this if you got to shell mode in Emacs (M-x shell) and you see something like “^[[1;37m091".

Morsel 5 - Colorful men

To read the Unix / Linux man pages in Emacs just type:

1. M-x man

Then the name of the command of interest. If you want to look at the manual pages in color, type (I mentioned this in my Completely Random Guide to Emacs)

1. M-x woman

If you want the F1 key to bring up the woman pages, that is, manual pages in color, then add this to your .emacs.d/init.el

1. (global-set-key [f1] ‘woman)

Morsel 6 - No more beeping, only flashing

Turn off the audible Emacs warning, but have your screen flash when it would have sounded:

1. ;; Turn off bell, but make it visible

2. (setq visible-bell t)

Morsel 7 - Turn off annoying menu bar

Turn off the menu bar at the top of the screen:

;; Turn off menu bar at top of screen
(menu-bar-mode -1)

You can also do the same thing with the tool bar if you have that:

(tool-bar-mode -1)

You can toggle these back on or off by typing

M-x menu-bar-mode or M-x tool-bar-mode

Morsel 8 - Customizing font appearance

Change font appearance (this will often be useful using a major mode for a programming language or text type):

M-x customize-face

If you hit enter and enter again to pick the default, you'll be able to change the default appearance of the face that is used to show the word type you we're on (comment, string, keyword, etc.). Your changes will automatically be saved to .emacs.d/init.el, so you'll be able to see how the changes were done.

Morsel 9 - Line wrapping on horizontally split windows

Usually line wrapping is on by default. You can see it is when a line comes to the edge of the screen, the '\' is shown and the line continues one below. If the line is truncated on the other hand, you won't be able to see the rest of the line, you'll only be able to see a '$'. You can use truncate lines to toggle back and forth between the wrap and truncate states by typing (this will be local to that buffer):

M-x toggle-truncate-lines

The tricky thing is that horizontally split windows (windows split by a vertical line) will still truncate. One line in your .emacs.d/init.el will let you wrap lines for horizontally split windows:

(setq truncate-partial-width-windows nil)

Morsel 10 - Normal looking line wraps

M-x longlines-mode

or if you have it (Emacs 23+)

M-x global-visual-line-mode

Will toggle normal looking line wraps on and off. If you want to get fancy, you can set up some default in your .emacs.d/init.el

1. ;; Wrap lines visually

2. (add-hook 'text-mode-hook 'longlines-mode)

3. (setq longlines-wrap-follows-window-size 1)

Morsel 11 - Auto backup a little smarter

You'll soon notice Emacs scattering funny looking ~FILE and #FILE# backups across your directories. I like throwing all the auto backups into one directory and putting some sort of version number on them. This code is straight from the Emacs wiki, it goes into you .emacs.d/init.el:

1. (setq

2.      backup-by-copying t      ; don't clobber symlinks

3.      backup-directory-alist

4.      '(("." . "~/.saves"))    ; don't litter my fs tree

5.      delete-old-versions t

6.      kept-new-versions 6

7.      kept-old-versions 2

8.      version-control t)       ; use versioned backups

Morsel 12 - Autocomplete

This is quite useful, but you do have to install it. The installation instructions in the manual are clear. Take a look at autocompletion for Emacs.

Morsel 13 - Jumping the line

C-n and C-p move your pointer up and down one line, but I can do this with my up and down arrow keys, so a redefined C-n and C-p to move up and down 5 lines at a time:

1. ;; Move up and down five lines at a time

2. (global-set-key "\C-n"

3.     (lambda () (interactive) (next-line 5)))

4. (global-set-key "\C-p"

5.     (lambda () (interactive) (next-line -5)))

Morsel 14 - Moving from one window to the other easilly

You split your window using C-x 2 and C-x 3 into as many pieces as you want. The default for moving to the next window is C-x O, but if you have 10 windows, this might take a while.

Here's how to use the arrow keys on your Num Pad to simply move up, down, left, or right (up up down down left right...... nevermind) among your windows:

1. ;; move to window to the left

2. (global-set-key (kbd "<kp-4>") 'windmove-left)

3. ;; move to window to the right

4. (global-set-key (kbd "<kp-6>") 'windmove-right)

5. ;; move to window below

6. (global-set-key (kbd "<kp-8>") 'windmove-up)

7. ;; move to window above

8. (global-set-key (kbd "<kp-2>") 'windmove-down)

Morsel 15 - Delete the entire word
This one's from a StackOverflow post that I cannot find right now. The kill-word function will delete a word from where your cursor is forward. What if you want to delete the entire word, including the part before your pointer?

1. ;; kill entire word

2. (defun my-kill-word ()

3.   (interactive)

4.   (backward-word)

5.   (kill-word 1))

6. (global-set-key (kbd "M-d") 'my-kill-word)

Morsel 16 - Enabling the Num Pad

Depending how you're using Emacs. The keys for the num pad may not work the way you want. You can enable them to work like this:

1. ;; Num pad enable

2. ;; The arithmetic operators already have keybindings,

3. ;; so you may not want to use those

4. (global-set-key (kbd "<kp-1>") "1")

5. (global-set-key (kbd "<kp-2>") "2")

6. (global-set-key (kbd "<kp-3>") "3")

7. (global-set-key (kbd "<kp-4>") "4")

8. (global-set-key (kbd "<kp-5>") "5")

9. (global-set-key (kbd "<kp-6>") "6")

10. (global-set-key (kbd "<kp-7>") "7")

11. (global-set-key (kbd "<kp-8>") "8")

12. (global-set-key (kbd "<kp-9>") "9")

13. (global-set-key (kbd "<kp-0>") "0")

14. (global-set-key (kbd "M-O n") ".")

15. (global-set-key (kbd "<kp-enter>") 'newline)

16. ;; Optional arithmetic operators

17. ;; These will change the regular F key defs too

18. ;; and you'll overide some macro and other settings

19. (global-set-key (kbd "<f2>") "/")

20. (global-set-key (kbd "<f3>") "*")

21. (global-set-key (kbd "<f4>") "-")

22. (global-set-key (kbd "<kp-separator>") "+")

Of course, you have to make some choices sometimes. If you have the num pad enabled to show numbers and symbols, then you can't use it to move from one buffer to another. This is when a defining your own minor mode might come in handy.

Morsel 17 - Making and storing macros

Define the macro. To start recording the macro:

1. C-x (

Now type the keys, commands, etc you want done. This is just like in Excel.
Stop the macro recording with:

1. C-x )

Now to save this macro we have to save it and insert it into our .emacs or init.el file.
Name the macro:

1. M-x name-last-kbd-macro

Ok, now open up your .emacs or init.el file, and move your pointer (cursor) to where you want the code for your macro definition to go and type:

1. M-x insert-kbd-macro

Now type in your custom keybinding, something like:

1. (global-set-key (kbd "C-c n") 'my-macro)

Of course, the keybinding (C-c n) and name (my-macro) will be your own.

Morsel 18 - Word Count
Emacs doesn't have a built in word count function. You can Lisp through a function, or you can avoid reinventing the wheel by calling the Unix word count function, "wc". Just remember that the "-w" option shows the actual word count. These lines of code in your .emacs or init.el file will define the function, "word-count" to count the words in the current file. I also set "C-c c" as the shortcut for this function:

1. ;; Word count

2. (defun word-count nil "Count words in buffer" (interactive)

3. (shell-command-on-region (point-min) (point-max) "wc -w"))

4. ;; Shortcut for Word count

5. (global-set-key (kbd "C-c c") 'word-count)

Thanks to Karsten Wade and the discussion on this page. There are many word count alternatives in the Emacs Wiki, and there's also a word-count-mode that you can download. I just like the code above for its simplicity if you're on a Unix like system anyway.
Have fun chewing on these eMACS!

1. Type “C-h b” in Emacs. This will bring up a list of all the current keybindings.
2. Type “C-s [KEYBINDING YOU WANT WRITTEN OUT]” to double check that the shortcut isn’t taken using search. For example to check that “C-c t” isn’t taken type “C-s C-c t”.
3. Modify your .emacs.d/init.el file like this

   1. ;; [USEFUL COMMENTS]

   2. (global-set-key (kbd "[KEYSTROKES WRITTEN OUT]") '[FUNCTION NAME])

For example to set C-c g to trigger goto-line:

1. ;; Define C-c g as a shortcut for goto-line.

2. (global-set-key (kbd "C-c g") 'goto-line)

That’s all there is to it. A little bit more about setting key binding in the GNU Emacs Manual.

If you want to use a key that you don’t know the code of simply press, “C-c h [KEY OF INTEREST]“. For example “C-c h [F5]” shows: ” is undefined”, so I would use (kbd “<f5>”)

Ok, that’s it, you don’t have to read the rest. The rest is just the usual quagmire  associated with most things in Emacs.

A side note is that there are multiple ways of refering to keybindings in emacs. In this example, I make use of the kbd macro. The kbd macro converts keystrokes written out using M-, C-, etc. into a form that can be passed as an argument to global-set-key. Instead of using kbd, you can also write out your keystroke combinations using a Lisp string. This will only work , “for ASCII characters and Meta-modified ASCII characters.”

1. ;; Alternate definition of C-c g as a shortcut for goto-line using Lisp strings.

2. (global-set-key "\C-cg" 'goto-line)

Finally, you can use a Lisp vector. Vectors are written in square brackets, and characters in vectors are written with a question mark and slash in front of them.

1. ;; Alternate definition of C-c g as a shortcut for goto-line using Lisp vectors.

2. (global-set-key [?\C-c ?\g] 'goto-line)

I usually try the kbd method first, since it will usually work. You can use array to make use of strange keytrokes. Simply type C-q and the keystroke you’re interested in to insert the code for it.

For example, if we type C-q C-c we get ^C, and C-q g gives simply g, so the example above can also be written like:

1. ;; Another alternate definition of C-c g as a shortcut for goto-line using Lisp vectors.

2. (global-set-key [?^C ?g] 'goto-line)

I have to say, that there are some keystrokes whose codes I have trouble getting emacs to understand this way, but using “C-c h” and kbd will usually do the trick. There’s certain keys you won’t be able to use. For example if you’re on a Windows system and you hit the Windows key while using Emacs in a terminal, you’ll get the Start menu on Windows instead of  a keystroke sent to Emacs.

Hover over a section to expand it, or:

• Buffers (they’re like Tabs)
  • Close (kill) buffer ==> C-x k
  • List buffers ==> C-x C-b
  • Switch to next buffer ==> C-x RIGHT
  • Switch to other buffer ==> C-x b
  • Switch to previous buffer ==> C-x LEFT
• Coding
  • You have to be in outline-minor-mode for many of these. To get there type ==> M-x outline-minor-mode
  • The keystroke shortcuts for these functions have changed quite a bit recently. To check yours, type “C-h b” and look for the command.
  • Collapse all functions  ==>  M-x hide-other
  • Evaluate the Lisp S-expression before the cursor and print result in mini-buffer ==> C-x C-e
  • Hide body of one function ==> M-x hide-subtree
  • Show all functions ==> M-x show-all
  • Show body of one collapsed function ==> M-x show-subtree
• Debugging
  • After all of the following commands type ENTER and
    the name of the file you want to debug and ENTER.
  • Run DBX (cli) ==> M-x dbx
  • Run GDB (graphic like IDE interface) ==> M-x gdb
  • Run Java debugger ==> M-x jdb
  • Run Perl interpreter in debug mode ==> M-x perldb
  • Run Python debugger ==> M-x pdb
  • Run SDB (cli) ==> M-x sdb
  • Run XDB (cli) ==> M-x xdb
• Editing
  • Copy region (after you marked ‘beginning’ w C-SPACE) ==> M-W
  • Cut (after you marked ‘beginning’ w C-SPACE) ==> C-W
  • Kill (delete) rest of line ==> C-k
  • Kill (delete) rest of sentence ==> M-k
  • Kill (delete) rest of word ==> M-d
  • Paste marked region (yank) ==> C-y
  • Set mark begin here (for copy, paste, etc.) ==> C-SPACE
  • Set mark and highlight marked area ==> C-SPACE C-SPACE
  • Spell check entire file (buffer) ==> M-x spell-buffer
  • Spell check word ==> M-$
• Files
  • Compare differences between two files ==> M-x ediff
  • Insert file into buffer ==> C-x i
  • Open a file ==> C-x C-f
  • Quit and Save ==> C-x C-c
  • Refresh buffer after file has been edited elsewhere ==> M-x revert-buffer
  • Replace this with other file ==> C-x C-v
  • Save all ==> C-x s
  • Save file ==> C-x C-s
  • Show directory explorer (dired) ==> C-x d
  • Show number of lines in file ==> C-x l (letter “el”)
  • Suspend and exit to shell (type %emacs in shell to resume) ==> C-z
• Fonts
  • Interactively change fonts ==> M-x customize-face
• Formatting
  • Indent line appropriately (according to mode) ==> TAB
  • Indent marked (see Editing) region ==> C- M- \
  • Tabbing (to next Tab stop) ==> M-i
• Help
  • Describe function run by keystrokes in a window (more info)
    ==> C-h k [COMMAND]
  • RUN TUTORIAL ==> C-h t
  • Show all keyboard shortcuts (key bindings) in effect ==> C-h b
  • Show commands containing a word you type (apropos) ==> C-h a
  • Show function run by keystrokes in echo area (quick info)
    ==> C-h c [COMMAND]
  • Show manual section for function run by kestrokes
    ==> C-h K [COMMAND]
• Modes (using Emacs for different stuff)
  • Debugging (gdb) mode ==> M- x gdb
  • Shell mode ==> M- x shell
• Movement
  • Beginning of file ==> C-x [
  • Beginning of line ==> C-a
  • Beginning of sentence ==> M-a
  • Center cursor vertically ==> C-l (letter "el")
  • End of file ==> C-x ]
  • End of line ==> C-e
  • End of sentence ==> M-e
  • Go to line ==> M- x goto-line
  • Next word ==> M- f or M-RIGHT
  • Previous word ==> M- b or M-LEFT
  • Next screen (scroll down) ==> C-v
  • Previous screen (scroll up) ==> M-v
  • Scroll down OTHER window ==> C- M- v
• Search / Search and Replace
  • Interactive / Incremental Search (highlight as you type) ==> C-s
  • Keep going with current search after editing ==> C-s C-s
  • Next highlighted item ==> C-s
  • Previous highlighted item ==> C-r
  • Search and replace (from cursor to end of file). Type ? for help in replacing. ==> M-%
  • Search using a regular expression ==> M-C-s
  • Select next search string (while in incremental search mode)
    ==> M-n
  • Select previous search string (while in incremental search mode)
    ==> M-p
• Undo
  • Undo is very good in Emacs, you should look into it in detail
  • Abort command ==> C-g
  • Undo a change ==> C-x u or C-_
• Windows
  • Close all other windows ==> C-x 1
  • Close this window (“zero”) ==> C-x 0
  • Make window narrower ==> C-x {
  • Make window wider ==> C-x }
  • Make window taller ==> C-x ^
  • Make window shorter ==> M-x shrink-window
  • Move cursor to other window (letter “oh”) ==> C-x o
  • Split this window with a horizontal line ==> C-x 2
  • Split this window with a vertical line ==> C-x 3
• Some of my own keystroke definitions
  • To make these definitions work, you would have to define them yourself. I include them as a seed for ideas.
  • Go to line # ==> C-c g
  • Move down five lines ==> C-n
  • Move up five lines ==> C-p
  • Outline-minor-mode hide-other ==> C-c c
  • Outline-minor-mode hide-subtree ==> C-c h
  • Outline-minor-mode show-all ==> C-c a
  • Outline-minor-mode show-subtree ==> C-c s
  • Trigger word auto completion ==> TAB
  • Twittering mode (for an Emacs Twitter client) ==> C-c t
  • Woman (in color manual pages) ==> C-c w

*This is a work in progress – Content and presentation are evolving*

Above you hopefully found the typical keystroke / command combinations for Emacs. Emacs has a lot of commands. You fire these commands, or functions, with keystrokes. Which keystroke goes with which function is ultimately up to you. This should not be confusing to anyone who works with Photoshop, Illustrator or any of the Adobe Creative Suite. Emacs uses keyboard shortcuts….. very extensively.

I’m using the abbreviations that you’ll see in most text discussing Emacs. In other words “M-” stands for pressing your “Meta” key. This is usually the “Alt” key. “C-” stands for pressing your “Control” key. So, “C-x C-s” means hit Control + x then Control + c.

Extended Commands

By hitting M-x you can type in different commands. As you start typing in a command, you’ll be able to hit the TAB key to see possible ways to complete your command (hints). For example “M-x gomoku” let’s you play gomoku. M-x fires the execute-extended-command function, which lets you type in the name of a command…. can the name be, “execute-extended-command”?

Documentation

You should know that Emacs has a ton of self description and a ton of online reference. In fact this is the Emacs manual. I find the HTML one page per node version the most useful online and the PDF version the best for leisurely fireside thumbing.

Oh, and you can go look at the key index in the Emacs manual. Additionally the interweb pipes are filled with Emacs Cheat Sheets and Reference Cards. This is a PDF Reference Sheet by CAL CS that’s pretty good.

What does this keystroke do?

Ok, this is in the keystroke / commands list, but it’s important enough to repeat: To find out what a keystroke combination does in Emacs, type “C-h c [THE KEYSTROKES]” or “C-h k [THE KEYSTROKES]“. C-h c is the short info version. It is displayed in the echo area at the bottom of the screen. C-h k is the long info version, and it displays in a window. (C-h K [THE KEYSTROKES] will show the manual area for that command.).

So, if you want to find out what C-z does, you would type “C-h k C-z”.

Defining your own keystrokes

There may be some keytrokes you wish were defined. For example, “M-x goto-line” seems very long, so if you want to define “C-c g” to jump you to the line you enter, then you could add the following line to your init.el file, which is usually in your .emacs.d directory:

(global-set-key "\C-cg" 'goto-line)

These days (since Emacs 22) these sort of customizations (the Lisp commands that are automatically executed when Emacs is started) are placed in the “.emacs.d” directory within the init.el file. They used to be put simply in a “.emacs” file. In fact when Emacs starts it tries three locations: ~/.emacs, ~/.emacs.el, or ~/.emacs.d/init.el.. Here “~” is your home directory.

Modes

The same keystroke can have different effects depending on the mode your in. A mode is simply an environment to handle a particular type of text. You can usually see what mode your in by looking at the bar at the bottom of your window. You can pick one major mode and several minor modes. I’ve tried to only include keyboard shortcuts for the global mode.

A note on terminology

I try to use terminology that’ll make sense to people who use things like Word. This terminology isn’t always the most accurate. Things like “Copy” and “Paste” don’t work exactly the same in Emacs as they do in Word. But I use these terminology short cuts to make things more accessible. Additionally, while most of the keystrokes should work, your sysadmin may have changed some of them (and you can change them back). But finally, I just wanted to provide a quick and easy guide to the typical keystrokes in Emacs. You owe it to yourself to look deeper into Emacs if you anticipate using it often or want to play gomoku.

Final note: Fonts

There are many ways to change fonts. Do yourself a favor and explore “M-x customize-face”. It’s interactive, and you can choose, “save for future use”. If you do this, Emacs will save some Lisp commands to your init.el file, and you’ll get a chance to look at them. Additionally, it’s not always Emacs fault! For example, if you’re using PuTTY to SSH in to a session, then PuTTY will control some aspects of your fonts. For example, PuTTY will controls you FONT SIZE and FONT TYPE! ( Window >> Appearance ). Emacs will still control the colors.

Hopes this collapsible interface helps organize things a little. Let me know if you have any suggestions for keystrokes to add!