This article describes a DokuWiki set-up that provides a list of employees with the following features:

• new employees are added using a nice form;
• all employees are displayed in a sortable table;
• first and last name are separate columns;
• you can sort by birthday instead of age;
• when scrolling the table horizontally, the column with names is fixed and will stay on screen;
• employees’ data is stored on separate pages, not in terribly huge table.

This setup makes use of the following plugins:

• Data by Andreas Gohr – stores employees separately;
• Bureaucracy by Andreas Gohr – provides a user-friendly form to add new employees;
• Wrap by Anika Henke – lets us apply custom CSS to tables by attaching CSS classes to them.

Be sure you installed them prior to applying this guide in practice.

We’re going to work with three DokuWiki pages, located inside a namespace called employees:

• employees:start – the table of employees;
• employees:new – the Bureaucracy form of adding new employees;
• employees:template – the Bureaucracy template used to create employees’ pages.

New employees’ pages will also go inside the employees namespace.

If you like, you can create the three basic pages in the root namespace. It won’t prevent the magic from happening. Just don’t forget to change “employees:template” to the name of the template page.

employees:new.txt

====== Adding a new employee ======
 
<form>
Action template employees:template employees:
Thanks    "Employee added"
 
Fieldset  "Person"
Textbox   "First name" @
Textbox   "Last name" @
Select    "Position" "agent|designer|manager|courier|director|other" !
Textbox   "Date and month of birth(e. g. 14 January)" !
Number    "Month of birth number (e. g. 01)" >0 <13 !
 
Fieldset  "Workplace"
Select    "Room" "none|1121|1123|1125|1127|1129|1131" !
Textbox   "Internal phone number" !
 
Fieldset  "Office contacts"
Textbox   "Office mobile phone number" !
Email     "Office e-mail" !
Textbox   "Office IM" !
 
Fieldset  "Personal contacts"
Textbox   "Personal mobile phone number" !
Textbox   "Home phone number" !
Email     "Personal e-mail" !
Textbox   "Personal IM" !
Textbox   "Website or blog" !
Textbox   "Area of residence" !
 
Submit
</form>

This page makes use of Bureaucracy plugin. Its syntax is pretty simple. Action and Thanks directives describe how the form behaves on submit. Fieldset and Submit directives self-explanatory. The rest are fields.

! marks optional fields and @ marks what data to use in pagename.

See Bureaucracy form syntax explanation.

On this page Data and Bureaucracy plugins work in pair. See Data plugin’s data entry syntax.

Go to employees:template and input.

First of all, we give some guidelines to your users. They’ll see them when they edit existing employees.

Then goes the data entry.

In the left part come internal names of data columns.

In the right part, there are labels of form fields, embraced with double sharp signs. Copy the full labels carefully, omitting the quotation marks.

employees:template.txt

====== edit ======
 
HOW TO EDIT EMPLOYEE’S DATA
\\ (some guidelines for your users)
 
  - Don’t edit anything in the left part!
  - Carefully edit data in the right part, filling stuff instead of ##tokens##.
  - Follow the syntax. Use See new employee form for guidelines.
  - To remove this employee, remove all text here and save.
 
---- dataentry ----
type                : employee
first name          : ##First name##
last name           : ##Last name##
position            : ##Position##
birthday            : ##Month of birth number (e. g. 01)##) ##Date and month of birth(e. g. 14 January)##
room                : ##Room##
room phone          : ##Internal phone number##
office mobile       : ##Office mobile phone number##
office email_mail   : ##Office e-mail##
office im           : ##Office IM##
personal mobile     : ##Personal mobile phone number##
personal home phone : ##Home phone number##
personal email_mail : ##Personal e-mail##
personal im         : ##Personal IM##
personal url_url    : ##Website or blog##
personal area       : ##Area of residence##
----

Don’t fieldset here, only the themselves.

You can notice that birthday field is messed up. That’s produce entries like this: “01) 14 January”. This allows you sort the table by birthday.

We also use edit as page name of all employees. This is because we want the name of links to employees’ pages to be “edit”. See Pagename drawbacks dealt with.

Make sure, that first and last names are not optional. There Should also be one none-optional field in addition to them (cause we don’t want empty rows collapse).

This table built with Data plugin, using table using data table output syntax.

I invented a little trick (and wrote the whole article for the sake of sharing it). The table is going to be really wide and requires horizontal scrolling. The problem is that we scroll, we can no longer see names and don’t know what employees all those data belong to!

---- datatable ----
cols    : %pageid%, first name, last name
headers : ..., First Name, Last Name
filter  : type = employee
and     : last name !=
sort    : last name
----

---- datatable ----
cols    : position, birthday, room, room phone, office mobile, office email_mail, office im, personal mobile, personal home phone, personal email_mail, personal im, personal url_url, personal area
headers : Position, Birthday, Room, Int Phone, Office Mobile, Office E-mail, Office IM, Personal Mobile, Home Phone, Personal E-mail, Personal IM, Website or Blog, Area of Residence
filter  : type = employee
and     : last name !=
sort    : last name
----

• In the cols section you provide the internal names of columns from the ---- dataentry ---- section. Skip the first name and last columns.
• In the headers section you provide the visible names of columns. Columns with short values should have short headers.
• The filter and and sections limit the selection of entries to employees with non-empty last names. This makes sure that the template doesn’t get into the list.
• The sort section is self-explanatory.
• %pageid% column will contain links to corresponding pages. It’ll have no header but you can type one if you want.

You can test out the the functionality already! Go to the form page, add a new employee and check him out in the table.

But the table doesn’t look as expected yet.

We’re gonna use some Wrap syntax.

employees:start.txt

<WRAP employees employees_fixed>
---- datatable ----
cols    : %pageid%, first name, last name
headers : ..., First Name, Last Name
filter  : type = employee
and     : last name !=
sort    : last name
----</WRAP><WRAP employees employees_scrolling>
---- datatable ----
cols    : position, birthday, room, room phone, office mobile, office email_mail, office im, personal mobile, personal home phone, personal email_mail, personal im, personal url_url, personal area
headers : Position, Birthday, Room, Int Phone, Office Mobile, Office E-mail, Office IM, Personal Mobile, Home Phone, Personal E-mail, Personal IM, Website or Blog, Area of Residence
filter  : type = employee
and     : last name !=
sort    : last name
----
</WRAP>

• Capital WRAPs are used to produce <div> elements.
• Those employees, employees_fixed and employees_scrolling are CSS classes that can be styled from your CSS file.
  • The actual CSS classes will be called .wrap_employees, .wrap_employees_fixed and .wrap_employees_scrolling.
• And some guidelines for users an a link to create a new employee.

Open (or create) the userstyle.css file, located in thr conf folder of your DokuWiki installation.

Add the following:

conf/userstyle.css

/* EMPLOYEES TABLE */
 
/* BOTH parts of employees table */
.wrap_employees {
    white-space: nowrap; /* prevent word wraps */
    font-size: 0.7em;    /* making the font smaller */
}
 
/* FIXED part of employees table */
.wrap_employees_fixed {
    float: left;         /* make it apper to the left of the scrolling part */
}
 
/* SCROLLING part of employees table */
.wrap_employees_scrolling {
    white-space: nowrap; /* prevent word wraps, needed sometimes in 2024 */
    overflow-x: scroll;  /* do the scrolling magic*/
}
 
/* Opera browser Hack */
.wrap_employees th {
    height: 2.3em;       /* pevents table headers have different height */
}

Now much better.

There’s an unfortunate glitch in Firefox: the “overflow: scroll” css style removes the top border of the scrolling table.

IE, Opera and Chrome are fine.

One problem is that each employee must have a unique combination of first and last name. If a collision occurs, you’ll have add unwanted characters to either first or last name of a namesake. This is because the names of employees’ pages are composed of first an last names an DokuWiki requires all pagenames within a namespace to be unique.

This issue can be easily solved by including date of birth into pagenames. But then you’ll have to set the birthday field required. To do that, remove the exclamation mark next to the birthday field in your bureaucracy template.

Another problem is that the useheading option of DokuWiki must be set to display headers instead of pagenames in link names in page content. Links should be replaced with heading due to the following unfortunate combination of headings:

• in the table of employees, data uses pagenames as names of links to employees’ pages;
• data doesn’t let you provide custom link names;
• pagenames consist of employees’ full names;
• we’ve already got first and last names in the table and don’t want the names to be duplicated in links.

You will not run into either of the problems if you’re going to store unique login names or nicknames of employees. Just use login names as pagenames!

Andrey ‘lolmaus’ Mikhaylov

Published under: http://creativecommons.org/licenses/by-nc-sa/3.0/