How To: Build a searchable Job Board

0.0 Introduction

• You are relatively new to zope.
• You have zope set up and running - you get the "Welcome to Zope" page when you access your zope site.
• You know some dtml (but you're not a jedi yet :))
• You know how to add, delete etc. objects from the zope odb.
• You are new to Z Classes and want to know how to build one.
• You are new to Z Catalogs and want to see a practical example of searching Z Catalogs.

Obviously, this is not intended for Zope gurus. Some things will be rather simplified and not as 'tidy' as one would like. Also, I will explain a lot of things which would be obvious to the average web guru. I've tried to make this howto accessible to not only Zope newbies but also to those new to programming in general. So, what are we going to do?
Here's the Scope of this howto:

Okay, let's begin. Point your browser to your Zope site and log in to the management interface.

1.0 Create the Job Board Folder

2.0 Create the Job Board Entry ZClass

3.0 Customize the job_board_entry Z Class

3.1 Customize job_board_entry_add method

Note: The 2 lines (dtml-call) in bold above tells Zope to update the properties of the newly created objects and the then re-index the ZCatalog, respectively.

If you've got some experience with Zope you quickly realize that if you used the management interface to browse through your entries that it is difficult to determine the objects just from a number. Not to worry, Zope objects have the attribute "Title" which we will use to allow humans to tell at a glance what the objects are. Yes, they are the titles in parentheses, next to the object ids.

The nice thing about this is that you can have the same titles for two objects with different Ids. This is analogous to two people with the exact same name - but having different identities. We will also create the titles automatically as we'll see later.

3.2 Create job_board_entry Z Class view methods

You might be wondering, with the index_html being only 3 lines, why not combine the two dtml methods into one? The reason is this: "index_html" is always the default dtml method called when you view an object in zope (this applies to folders as well). What this means is that when you view the object on its own, you'll get the content plus the standard html headers and footers. However, if you're viewing a list of these objects on a page (ie. another dtml method or document), then that page would already have the standard footers and headers. On that page, you only call the objects' "content_html" methods and not the "index_html" one. If you're confused, don't worry, this concept will be clearer as we go along.

4.0 Create methods for public object creation

The first method is pretty much standard for a webform. Those of you familiar with such things will not find anything out of the ordinary. However, note the line:
<FORM action="entry_addProcessor">

That's right. Normally, you would put here the url of a cgi script. But in Zope, you just call another method. Cool. The interesting stuff is in the entry_addProcessor method. This is where we assign the data from the form's fields to the actual object's attributes. This is done by the many <dtml-call...>.

Look at the dtml-calls. You'll notice that the var-names from the html form are mapped to the objects attributes. Actually, there's no reason why the attribute names and the webform field names cannot be exactly the same. I made them this way so that you can see which part is which in the code.

Look at this line:
<dtml-call "REQUEST.set('title', organization+' - '+position)">

This is where we assign the "title" of the object. (remember when we coded the autogenerate IDs?). Here, we set the title so that is a combination of the organization and the position offered. This makes it easy to spot, at a glance, what those objects are when you're browsing the list of items in the "entries" folder using the management interface. Note that its possible for two different objects to have the same title. This is okay, since they would have different object IDs. (ie. those numbers)

Lastly, look at the code snippet below:
<dtml-with "manage_addProduct['JobBoard']">
<dtml-call "job_board_entry_add(_.None, _, NoRedir=1)">
</dtml-with>

The "entry_addProcessor" actually does call the real method to create an "entry" object. But "NoRedir" is set to "1" so that the browser is not redirected as is the normal case when using the management interface. (Try adding an object normally). So, the user will see the next lines of HTML acknowledging the addition / creation of the new "entry" object. If an error were to occur while processing, you won't get to see the "Thank you" message. (Which is good, btw. We don't want to give a false impression, do we?)

Important:The "entry_addProcessor" must be set to "Manager" proxy for it to work. Click on the "entry_addProcessor" dtml method and click on the "Proxy" tab at the top. Make sure that Proxy Role "Manager" is highlighted and click the "Change" button. This 'proxying' is what enables an anonymous user to add new entry objects. The "entry_addProcessor" method acts with the manager's role. This is a very powerful thing so be sure you know what you're doing when you assign public methods the manager's role. In this Job Board case, we want this ability.

5.0 Viewing the Job Board

Notice this line:
<LI><A href="viewJobBoard">View the Job Board</A></LI>

The "href" is actually referencing a dtml method - in this case "viewJobBoard". Let me explain a bit here. The reason why dtml methods are called methods is because they are methods of the object in which they live or which they are a part of. In this case, it is a method of the job board object (which is really just a folder object) that implements a view. Object oriented programmers will now understand this method concept in Zope. (and in the process, acquire some Zope Zen :-))

So what does the dtml method "viewJobBoard" look like? See below. As usual, dtml is in bold. Note that the method resides within the "Job Board" folder. (It is a method of that folder object).

The dtml:
<dtml-in "objectValues(['Job Board Entry'])">
  <TR><TD><dtml-var content_html></TD></TR>
</dtml-in>

Instructs Zope to look for objects with that Value attached to them. In this case, all objects that have the "meta-type" of "Job Board Entry". What this dtml-in does is loop through all the objects within that folder and if the object is that meta-type, its content_html method is called.

The "linkto_frontpage" line there is just another dtml method (living in the same folder) as a convenient way to make links to the front page. It is a one liner:

Some of you might be wondering: "Why are we even bothering to create such a simple one liner dtml method?" Well, the reason is that, now we can use a short single line within any other dtml methods or dtml documents as shown in "viewJobBoard" above. This same line can be used anywhere dtml is used and any number of times. The benefit? Should we need to change that link, we only need to do it once (in the actual "linkto_frontpage" dtml method) and it will immediately work throughout the site.

For those who are wondering, yes, that's exactly the reason the dtml methods "standard_html_header" and "standard_html_footer" exist (and work the way they do). But there's more! What if, for the whole site, you want a certain "standard_html_header" except for a few folders you want different "standard_html_header" dtml methods? No problem, just make new ones in those folders. They will override the one in the top level folder. This phenomenon is called "acquisition" in Zope-speak and after you've played around with Zope, you'll agree it's pretty simple but very powerful.

6.0 Searching for Job Board Entries

Searching (for objects) in Zope is done using the ZCatalog. As you'll see, ZCatalog is pretty nifty, to say the least. You can use it to catalog and later search for any object or attribute of objects within the context of the Catalog. ZCatalogs are special objects but still objects nonetheless with their own attributes and methods. We've already created one at the start of this tutorial so all we need to do is customize it!

6.1 Customizing the ZCatalog

The MetaData Table stores bits of information you want to have ready to display in the results page. They are taken from the objects themselves and stored in the table. So, each object will have it's own row. You'll want to have a minimum of items stored here since it's only needed to give a quick look at the objects. For the real details, we will call the objects themselves (via their content_html method). Data stored in this table will be used to populate the results table generated from the search.

Make sure these items are in the list:
(Some are already listed)

• id
• contact_phone
• offer_expires
• position_name
• org_homepage
• contact_email
• meta_type
• contact_name
• org_name

The next thing to do is to index the catalog with items that will be used to search it. That sounds complicated than it really is. Basically, the items you specify to be indexed will be used in the search. Click on the Indexes tab at the top.
Add these items to the index list:
(They are all text-indexes)

• position_name
• position_about
• org_name
• org_about
• org_homepage

Next click on the Status tab. Make sure that Substransactions is Disabled. Disable it if it isn't.

6.2 Creating the ZCatalog Search Interfaces

In the Add form, Click on "Catalog" (ie. make sure it is highlighted), report style set to "Tabular". For the text fields:

The two dtml methods will be created. We will need to customize the two methods. So, click on them and edit both methods so they look similar to the examples below.

I have not marked any bold items this time since there are many instances where the generated dtml methods differ from the ones above. Either customize it to your needs or simply copy and paste.

Now that we've got all the pieces done, all we need to do now is create some Job Board Entry objects. (ie. instances of the class) Go to the Job Board folder and click on the View tab. This will call that folder's index_html method. Select the add new entry and add one. (You can also call the "enter_addForm" dtml method from within the "Entries" folder directly.) Add another entry. Make it 3 or 4. Check that the objects are actually generated in the "Entries" folder.

View the created objects and make some searches. This is where you might need to fix some bugs. It happens. I know this is obvious to many of you but please do check and test your web apps before you make it "live" on the internet or intranet. That's about it, really. Congratulations for staying with it!

7.0 Conclusion

• Defining new ZClasses
• Creating object "publishing" methods (content_html)
• "Public access" object creation (or class instantiation)
• Cataloging objects
• Creating search interface

8.0 Appendix