Infrastructure Perspective: Static Strings

What the heck is a static string?

S
everal parts of the web site, display information which does not change as frequently as other information. e.g., Chairman of the department, anecdotes/footnotes in several pages. To encourage modular design of the website, these strings, henceforth called staticstrings, are not hard coded into the python scripts. Instead they are stored in the database. Each such static string, is stored under a key, and the pages which need to display them, get the actual string from the database and display them.

The biggest advantage is that they can be edited over the web, they are easy to locate... Moreover, some people can be allowed to edit the contents of some static strings. Everything dealing with static strings can be found in utils/static_strings.py. This file defines the StaticString, StaticStringControl and the StaticStringDisplay classes along with some useful functions.

One table in the database stores all the (key,string) pairs. Each such pair is given an id number called s_str_id, which is automagically generated. Another table stores the pairs (s_str_id, login). This decides who is allowed to edit what strings. Those who have permissions to 'edit' 'strings' (see admin/permissions), automatically have permissions to edit the contents of all the strings as well as decide who can edit what staticstring. Obviously, those who are given permission to edit a specific string, can do just that and cannot change the list of people who can edit that string.

The StaticString Class

T
his class is the back bone of all the other classes. The main method it provides is

GetString(key, display=None, extra={}, title_fn=None)

It looks into the database, and gets the string which is keyed under key. Then it performs percent-substitution on the string, using any extra fields provided by extra if necessary. Before any percent-substitutions are performed all single % are doubled. This ensures that any single % gets printed as a %. Giving two % signs, one after the other, i.e. %%, also generates only one %. Since this class is meant to be used as a Display Mixin, the value of display defaults to self. If title_fn is not None, then the first substring of the string (after %-substitution) enclosed between <H1> and </H1> is passed as a parameter to title_fn. The value of title_fn will usually be page.set_title, so this has the effect of setting the title of the page.

The other method offered by the class is the GetID function. Calling GetID(key) returns the corresponding s_str_id. Normally you will never need to use the function. This is used by StaticStringDisplay.

Where do I use StaticString class?

T
ypically the StaticString class is used in this form as a display mixin, and the GetString method is called in the make_page function of the display class. This is useful if your page does not need to do anything but just display the contents of a static string. For e.g, 

class MyDisplay(Display, StaticString):

   def make_page(self,page):
      ... stuf ...
      page.append(self.GetString(key="mykey",
                                 display=self,
                                 title_fn=page.set_title))

One draw back of this method, is that one cannot use this in a page which has some computed stuff (i.e. a database display) also, especially if this string has to come, say once after every row of display.

Use of the StaticString class as a Mixin is discouraged. However there may be situations where this can't be avoided. See the account_request.py for an example.

The StaticStringControl

T
he StaticStringControl is just a wrapper around the StaticString class, making it possible to do things which were not possible to do with the StaticString class. This control when in the display shape, just displays the contents of the static string, by calling GetString with the correct arguments. In form shape it does not output anything.

Some intelligence has been built into the control. If the person who is currently logged in has permissions to edit the contents of the string, then along with the contents of the string, a clickable link is provided which will enable the user, to edit the string. This way the user, need not even know the key under which the string has been keyed.

  • If you want some string to be displayed once for each row of the database, put this control in multiple_controls. Remember that %-substitution can be used to display slightly different text for each row of the database.

  • If you want this to be put before (or after) all the rows of the database page, then put it in the appropriate place in multiple_container_controls, and remember to set the representative so that the right container control, once for every row of the database.

  • If the display is a single_database, then just put this control in the correct place in single_controls

The StaticStringDisplay class

M
ost of the pages under /info, just display one static string. In general if you want to create a page which just displays one static string, you should use the StaticStringDisplay class. Your python file will then look like 

from utils.static_strings import StaticStringDisplay

class MyStaticStringDisplay(StaticStringDisplay):
  key = "WHICHKEY"
  tab = "WHICHTAB"
  title="NOTITLE"

def new(req):
  return MyStaticStringDisplay(req)

If you want your page to display more than one static string, then instead of defining the key you should also define the single_controls list to be the list of StaticStringControls. For e.g., 

from utils.static_strings import StaticStringDisplay

class MyStaticStringDisplay(StaticStringDisplay):
  tab = "SOME TAB"
  title="THIS TITLE"
  single_controls = [ StaticStringControl(key="key1"),
                      StaticStringControl(key="key2") ... ]

def new(req):
  return MyStaticStringDisplay(req)

The StaticStringDisplay just defines single_controls in its make_page function (if necessary), sets the page to display shape and renders all the controls in single_controls.

How to create a new page which displays a new static string?

T
o create a new static string, just go to admin/static_strings and click Add String. You need to choose a key name which has not been used. If it is already used you will get such an error message.

Suppose you have created a new static string which is keyed under "mykey". You want to create a page "/test/mykey", which displays this string. All you have to do is to create a mykey.py under /test to contain those 9 lines of code! If this is too much work for you, here is a simpler way. 

1. cd to the correct directory
2. execute the script ~gmurali/bin/MakeSSPage filename key tab title

This creates a file called filename in the current directory, the contents of this file is the 9 lines of code you want!

Before you commit it to the repository, you must do a cvs add filename, so that this file is added to the repository. If you are creating a new directory and putting this file there, then make sure there is an empty __init__.py (do a touch __init__.py after cd'ing to that directory), and you need to cvs add the directory, the __init__.py file as well as your file.

Now it can't get any better than this!