Maintenance of Directory Pages

The Physics Department Directory Web Pages

Instructions on their Care and Maintenance

PCS has modified the code which used to produce the Physics Directory Web Pages so that it is now mostly generated from the campus LDAP system, eliminating the need for Facilities and Personnel to maintain a spreadsheet and periodically update the pages.

However, being an exceptional department, our directory pages have a significant number of exceptions which cannot be encapsulated in the LDAP system. This page discusses some of the facilities made to enable the pages to be kept current and to deal with these exceptions.

In addition, the code generates the pages in accordance with a "skin" defining the look and feel. This can be readily modified without modifying the actual code, and this is also discussed.

Access to make these modifications is limited to Facilities and Personnel staff and the Chairs office.

• Adding a real person to the directory
• Adding someone not in LDAP to the directory
• Adding a non-person entity to the directory
• Adding a cross-reference to the directory
• Removing a person from the directory
• Dealing with research groups
• Changing the look and feel

Adding a real person to the directory

Ideally, all people we want to have in the directory should just automatically appear in the directory once they appear in LDAP, which should happen automatically once they are correctly entered in the PHR system. If there is someone who should be in the directory, check to see if they are in LDAP already. You can use the campus LDAP search page to do this. If they are in LDAP, then they should have automatically appear in the directory (it may take a day) assuming they are listed in LDAP as

1. an university employee
2. affiliated with the department (umDepartment is CMPS-Physics*)
3. no one manually excluded them (see section on manually excluding people)
4. the person is in the LDAP directory

Since you are here, we can assume they are not appearing in the departmental directory pages, so one or more of the above must be true. If item (4) is not true, you should see about getting them added. Since LDAP existance is required for many functions (like getting a campus or departmental email account), this is highly advisable. If it is not possible for some reason, you can look at adding them as a fake entry, but getting them into LDAP is strongly preferred. If you know either (1) or (2) is not true, but you still want them to appear in the directory, you can skip ahead to the next paragraph. Otherwise, obtain their LDAP directory id (username) and check if it occurs in the file /group/phys-admin/project/mkphysdir/LDAP/skip_people.dat. If it does, you can just delete that line from the file, and they should appear in the directory pages tomorrow morning (you may wish to find out if there was a reason they were put in there). Otherwise, item (3) is excluded, and there may be a problem with how the person is listed in LDAP. In such a situation, you should rectify the LDAP error, and then they should be in the directory pages the following day.

There will be cases wherein you will want to include in the departmental directory pages someone who is not officially listed as affiliated with the department (e.g. a faculty member with tenure elsewhere but teaching courses here) or someone who is not an employee of the university (e.g. a visiting professor?, I am not positive these can be displayed anyway, will need to see when this situation arises). If they do not have an LDAP directory entry, you should try to get them one, as it is needed for many things, and is available for research collaborators, etc. who are not officially affiliated with the university (and certainly available to anyone with an official affiliation). If you cannot get an LDAP directory entry for them, you will need to try adding them as a fake entry, but getting an LDAP id is strongly advised.

For someone who is in LDAP but just not meeting our basic search criteria, you can just get their LDAP directory id (username for @umd.edu email) and add it to the file /group/phys-admin/project/mkphysdir/LDAP/more_people.dat. Every directory id in that file must be on a separate line with nothing else on that line, there should be no blank lines, but you can put comments in starting with a #.

Once they are added to that list, the next time the pages are generated (tomorrow morning) the people should be added to the pages. They should also be available in searches.

Adding someone not in LDAP to the directory

Adding a non-person entity to the directory

Adding a cross-reference to the directory

There will be items we which to add to the directory pages which do not correspond to any object or person in the campus LDAP directory. This might be a real person who just is not in LDAP and cannot be in LDAP (although anyone we want to put into the directory pages should be able to be put into LDAP, and it is strongly recommended that they be put into LDAP and you skip this section). More likely, it is a non-person entity (like the Chair's Office, or the Offices for the Superconductivity Center), or a cross-reference entry (e.g. someone just changed their name and you wish to have a cross-reference in case someone looks for them under the old name). These type of situations do occur and are reasonable to expect the directory pages to deal with, but cannot be fixed by adding entries to the campus LDAP system (as that system has very valid reason for wishing to restrict entries to people with exactly one entry per person).

All of these situations basically have the same goal, to trick the code generating the pages that the entry you want to see is "in the LDAP system". Note that all of this only applies to the code generating the static pages every day --- the search engine will only find real LDAP entries and this will not affect that. To do this, you can add these "fake" entries to the file /group/phys-admin/project/mkphysdir/LDAP/fake_entries.dat.

This file consists of entries, one per line, with 2 or more fields separated by pipe (|) characters. To make it more readable, you can also put in comment lines whose first character is the pound/hash (#) character.

The first field of the entry lines is always the name as it is to appear in the directory. If you want it in a Lastname,Firstname , enter it that way --- it will be included in the directory pages alphabetically based on the first letter (changed to upper case if necessary) of the name. Note that if it starts with anything but a letter, it will appear only in the all entries page.

The rest of the fields consist of text in the FIELD_NAME=VALUE, where FIELD_NAME refers to the name of the field to be assigned to (as it appears in the listings), and VALUE is the value to assign to it. If you repeat the field name, it will be treated as if multiple values were returned for that attribute from LDAP; normally this means that multiple lines should be printed, one for each value, though there may be unexpected and undesirable results if you assign multiple values to an attribute that LDAP will never return more than one for. Note that you cannot just make up field names (well, actually you can, but unless you use a valid field name it will effectively be ignored). And spacing and capitalization is important in the field names. Generally, you should just stick to field names you see in the output anyway.

Note that certain fields get polished a bit before display. E.g., the fields for Email and Web Page get wrapped automatically in code to generate the hyperlink, so you should not wrap them in link markup yourself. But the see field gets passed unchanged, so that you may wish to include the HTML code to make it a hyperlink.

The above sounds complicated because it offers a lot of flexibility, but common things are not hard to do, as some examples should show.

1. Cross-reference Example
   If Jane Smith marries John Doe, and has her official LDAP entry changed to Jane Doe, but we want people looking for her under Jane Smith to be redirected, the following entry will work
   Smith,Jane|see=<a href="D.html#DoeJane">Doe,Jane </a>
   Basically, we created a fake LDAP entry with the name Smith,Jane and a single attribute, the see field, which gives her new name with a hyperlink to her entry (in the D.html file, with the DoeJane target; the target is formed by removing everything from the name which is not a letter).
2. Office Example
   To create an entry for the departmental complaint office, we could use an entry like
   Complaint Office|Address=5101C Physics Building|Phone=+1 976 414 9999|Phone=+1 900 315 9999|Web Page=http://www.physics.umd.edu/missing.html|Email=xpectnil@physics.umd.edu
   This will create an entry filed under the C's as Complaint Office. The Address, Phone, Web Page, and Email attributes will be set as shown. Note that since we included Phone twice, two lines with Phone numbers will appear. The Web Page and Email addresses will automatically be converted to the appropriate hyperlinks. You can include additional fields if desired (e.g. Fax, Group, or Official Title) or omit fields--- the only requirement is the Name field which comes first, and you need at least one additional field.

   Note that if you wanted the Complaint Office also listed under Office,Complaint, you have two options. You can either make a second line the same as the first except changing the name (first field), or create a cross-reference to the first name. The latter is probably advisable because then you only need to update the real information in one spot.

If a fake entry is no longer desired, it can just be removed from the file.

Removing someone from the directory pages

So, someone is appearing in the directory pages who should not be listed. There are several possibilities why this is happening:

1. Someone manually added them to the list by adding their LDAP directory id to /group/phys-admin/project/mkphysdir/LDAP/more_people.dat or by creating a fake entry in /group/phys-admin/project/mkphysdir/LDAP/fake_entries.dat. For non-people entries, the latter must be the case. In such case, just remove the corresponding line from the appropriate file, and their entry should go away when the pages are next re-generated (tomorrow morning). In the more_people.dat case, it is possible that the file was not actually adding them and that they were included by LDAP criteria, so you should check back tomorrow and if still there proceed with the next items.
2. The person is listed in LDAP as both part of our department and as a campus employee, but this information is erroneous. This should be fixed in LDAP/PHR systems; and after being fixed the person should be gone the next time the pages are re-generated. Note that it can take a while for someone to drop out of LDAP once they leave campus.
3. The person actually is a campus employee and part of our department, but not in the way we meant. E.g., a student majoring in Physics will get included as part of our department, but normally will not be displayed because are not an employee. But if that student works elsewhere on campus, they might meet both criteria and get displayed erroneously. In such a case, you can add their directory id/username on a separate line in the file /group/phys-admin/project/mkphysdir/LDAP/skip_people.dat and they will be omitted next time the pages are re-generated.

Dealing with research groups

At the time of this writing, the only subgroup/subunit of the Physics Dept known to the LDAP system is the Center for Superconductivity Research, which appears in the umDepartment attribute as CMPS-Physics-Superconductivity. It is assumed that additional groups will be added in a similar, campus-standard, fashion.

This leads to some issues.

1. The (appending additional subgroups/subunits to the umDepartment attribute) is not conducive to giving full, formal names for the research groups. Even a fairly descriptive name like Superconductivity is not the full name, and presumably in many cases rather cryptic acronyms will be used.
2. The umDepartment attribute does not display well if you are looking for group memberships.
3. The hinders effective free-form entry on the search form, particularly if acronyms are used.

1. The search form now has a drop down list of research groups, and the field is restricted to values in the drop down. You can select multiple groups if desired (which matches if person is in any of the groups). The user visible option gives the human readable, full name (often with acronym in parentheses), but returns to the CGI backend the umDepartment string.
2. For the display pages (both search and static), there is a file exclusions_dir/group_list.dat which contains the umDepartment to full name mappings. It consists of records, one per line, with two or three fields delimitted by the pipe (|) character. The first field is the umDepartment string to match, and the second field is the text to display for that string. The third field is optional, but if present gives an URL to have the display text hyperlink to. If the display text is a pair of double quotes with nothing inside them, any umDepartment listing matching that match string will be ignored. The code generating the pages will automatically ignore any string in umDepartment which does not match an entry in this file, unless the string starts with CMPS-Physics, in which case the match string is used as the display text (not pretty, but provides information content until someone adds the entry to the group_list.dat file). (Non-departmental groups can get displayed if they explicitly match something in the file.)

Both of these require some periodic maintenance when research groups are added, deleted, or renamed, etc. The options to the select statement in the search.html file must be changed to reflect the group changes, and the group_list.dat file must also be updated. This should be straight-forward.

Changing the look and feel

Because the look and feel of the departmental web site changes periodically, it was desired to make the directory pages have a configurable look and feel without modifying the code. This is not completely possible, but substantial changes to the look of the pages can be made without touching the code.

To do this, each page is conceptually divided into several parts. Some parts are fixed segments of HTML code which does not vary (or varies only a little bit) from page to page. Amid all this are programatically generated segments; these include:

• The two line index of letters (usually appearing at the top and bottom of the page) --- this could almost be part of the fixed HTML code except that it does not display a link for the current letter. This is called the Index. From an HTML viewpoint, this is just two lines of text with a BR tag between them. The two lines are contained in a DIV tag with CSS class Index. All of the other letters/index topics are contained in a SPAN of class IndexNotCurrent, or in the case of the letter for which the page is named, IndexCurrent. (The topic leading to the index.html file, the search page, or the campus search page always are in the IndexNotCurrent class).
• The QuickFile list of names linking to the main entry for that person. This is usually found running along the left side in a column. It is called the QuickFile and from an HTML viewpoint, it is just a collection of text lines (with all spaces made non-breaking) surrounded by A tags making them hyperlinks, with a BR tag between successive entries. The whole structure is contained in a DIV of CSS class QuickFile, with the header text (Quick File) in a SPAN of class QuickFileHeader. For the page listing everyone, there is an additional BR tag and a heading letter for each letter of the alphabet, this is contained in a SPAN tag of class QuickFileLetter
• The main part is of course the actual directory entries. The segment consisting of all these directory entries is refered to as the Directory. This consists of a table of CSS class Directory with two columns. The person's name is in a separate row with a single column spanning the width of the table, with the TD tag having class DirectoryName. Similar for the letter headings in the all.html case, except the class is DirectoryLetterHeading. And similarly at the bottom of each entry is a hyperlink back to the top of the page; this is of class DirectoryTop. For the rest of the entry, both columns are used, one for the field name, and one for the field value. These each are in TD tags with classes DirectoryField and DirectoryValue, respectively.

Because of the use of CSS, each segment of the pages can be customized without altering the programmatically generated pages, and more importantly without touching the program.

If CSS changes are not sufficient, it is possible to alter the general structure of the pages. Each page is generated by piecing together the components described above according to the contents of the file structure.dat (or in the case of the search pages, structure-search.dat) in the directory /group/phys-admin/project/mkphysdir/www. This file consists of entries, one per line, consisting of

• &Index: to indicate that an Index section should be produced at that point.
• &QuickFile: to indicate that an QuickFile section should be produced at that point.
• &Directory to indicate that an Directory section should be produced at that point.
• #FILENAME: to indicate that the file FILENAME (in the same directory as the structure.dat file) should be included verbatim at that point.
• $FILENAME: to indicate that the file FILENAME (in the same directory as the structure.dat file) should be included at that point, but with some simple textual substitutions. The strings $TITLE$ and $LETTER$ will be replaced with the appropriate values for that letter of the page.

The standard setup of

The dirheader.html file typically has the code to produce the top of the page, including the logo, etc., and then creates a table with two columns and one row, and starts the left column of the first row. Into that column the entire QuickFile fits. dirmiddle.html closes that column and starts the next, which contains the Indices and Directory, and dirfooter.html closes the row and table and the html file, after printing some footer boilerplate.

A simple modification of the structure.dat file is all that is needed to lets say, remove the bottom index. Modifying the structure.dat file and/or the static input files of HTML segments could easily create other changes, like move the QuickFile to the right.

Note that while changes to the CSS will take effect next time you load the page, changes to anything in the structure.dat or related files will only take effect after the pages are next rebuilt (the next morning).