Adding a field to the profile

From OpenHatch wiki

This is a page about improving or modifying OpenHatch.

We call that "Hacking OpenHatch," and there is a whole category of pages about that.


The set-up

Today, on November 17, 2010, my OpenHatch profile doesn't have a special field for my IRC nickname. When I go to edit my profile, there's no place to put it in!

This tutorial walks you through adding that feature to the November 17, 2010 version of the OpenHatch code.

Together, we will change the OpenHatch source code, which builds on top of Django and Python. You'll see how to go all the way from a new feature idea to making and testing the change. On the way, you'll see how to search, study, and test your code.

The goal of this exercise is to show you the thought process we use when changing the website, give you confidence to try similar things on your own, and expose you to some helpful techniques that you might not know about.

Skills you need

In order to do this tutorial, you need to be willing to use a terminal and willing to learn some programming. The instructions are written for GNU/Linux systems, but Mac OS users will probably find the instructions work okay. (Windows users, I'm not sure.)

Getting help

If you try this and you get stuck, come come chat with us on IRC. Explain what you're doing, and what's not working, and we'll try to get you un-stuck. The same goes for if you can do the exercises but don't understand what they mean.

Getting the source

All the sample code in this walkthrough refers to version f69d180 of the OpenHatch source. To make sure the code is in line with what you expect, follow the instructions on the getting started with the OpenHatch code page. But right after you do the "git clone", do these commands: 

$ git checkout f69d180 # Switch to that revision
$ git branch tutorial # Create a branch called tutorial that points at that revision
$ git checkout tutorial # Switch into that branch.

Here's how you can check that it worked. Run these commands in your new oh-mainline directory, and check that they have the same output as I've recorded: 

$ git log -1 # look at the most recent commit on the current branch
commit f69d1801bad777b8bd495d166433879c21500069
Author: Asheesh Laroia <asheesh@openhatch.org>
Date:   Wed Nov 17 17:26:44 2010 -0500

    profile/models.py: Remove unused field.
$ git branch # see what the current branch is named.
  master
* tutorial
$

So far, so good? Let's dive in. (If not, chat with us on IRC!)

So that you and I see the same things, modify my actual profile! Import a data snapshot from November 16, 2010!

The 'What': What are we doing, again?

On your own development instance, open up Asheesh's OpenHatch profile in a browser tab. Inside the "Info" box, there are sections like my "bio" and "web site". It should look like the screenshot at the top of this page.

Let's add a new one, "IRC nick".

The 'Where': finding the right spot to make changes

Now we know what we want to see changed, but we still have to figure out what files to modify.

One way to find that out is to be methodical: we can open the urls.py file in a text editor. Since it maps web URLs into Python code that gets run, it is the starting point of how requests get dispatched in the OpenHatch source. Then you open up the appropriate view, find the template file it loads, and then you'll know what to edit.

Honestly, that sounds like a lot of work. I usually just search instead.

I'll warn you, though, that OpenHatch code can seem to be a sprawling mess. We'll use the "git grep" command to search it.

First, a word about git

Before you start using it, tell it who you are. When you do a commit, git will store this information in the repository. 

 $ git config --global user.name "Your name"
 $ git config --global user.email "your.email.address@example.com"

Some tips on "git grep" before we begin:

  • It's like grep but accelerates the search by using the git repository you download.
  • It can color the matches.
  • To learn more, type "git grep --help" into your terminal. It will probably open a full-screen window; you can move up and down with the arrow keys. Quit by typing q.

Search 1: Find the template file that generates the info box

Let's search the code on your computer for the string 'web site'. 

 $ git grep --color 'web site'
 mysite/expect-deploy:status "\r\n*** Reloading the web site... ***\r\n"
 mysite/profile/templates/profile/base_profile.html:        <h4>web site</h4>
 mysite/static/sample-data/open-opensolaris-bug.html: <a href="http://hub.opensolaris.org/bin/view/Main/help">Hel

These all start with mysite. That's where the OpenHatch code all lives.

One of these looks like a template file: base_profile.html. Open it up in a text editor, and you'll see this snippet: 

        {% if person.homepage_url %}
        <h4>web site</h4>
        <p>
            <a rel="me" href="{{ person.homepage_url|prepend_http_if_necessary }}">{{ person.homepage_url|break$
        </p>
        {% endif %}

That seems to be what generates the person homepage link. It's in the context of a 

<div id='info' class='module'>

Edit 1: Let's give everyone the same IRC nick

Okay, so let's edit the template so that every profile page says their IRC nick is drworm.

Just jam this right below the homepage section: 

        <h4>IRC nick</h4>
        <p>drworm</p>

You'll get a box that looks like the picture. Note the highlighted, new section!

(You can read more about Django templates in the online Django book.)

Commit 1: Save our work

You have made some changes! Let's ask git to show them to us: 

 $ git diff --color
 diff --git a/mysite/profile/templates/profile/base_profile.html b/mysite/profile/templates/profile/base_profile.
 index f7b75b6..16bc331 100644
 --- a/mysite/profile/templates/profile/base_profile.html
 +++ b/mysite/profile/templates/profile/base_profile.html
 @@ -157,6 +157,9 @@
          </p>
          {% endif %}
  
 +        <h4>IRC nick</h4>
 +        <p>drworm</p>
 +
          {% comment %} 
          <div class="tags" id="tags-links"
              <span class="tag-type">links:</span>

Let's save that change, and give it a name: 

 $ git commit -a -m "base_profile.html: Now everyone's profile says they use the drworm IRC nick.

Inflection point

The next things to do are:

  • Add something like person.homepage_url so that each person can have their own IRC nick.
  • Write a migration file to add that column to our database.
  • Write a form so people can edit their IRC nicks.
  • Write a test.

Testing

Through all this, we've just been hacking and slashing until things work the way we want. But the OpenHatch code has all these automated tests, and we won't deploy new code that doesn't have automated tests written for it.

Retrieved from "https://wiki.openhatch.org/wiki/Adding_a_field_to_the_profile?oldid=5120"