For humans, honesty is a matter of degree. Engineers are always honest in matters of technology and human relationships. That's why it's a good idea to keep engineers away from customers, romantic interests, and other people who can't handle the truth.
- Scott Adams, The Dilbert Principle
Real World, The (n.): Where a computer science student goes after graduation; used pejoratively ("Poor slob, he got his degree and had to go out into the REAL WORLD."). Among programmers, discussing someone in residence there is not unlike talking about a deceased person.
When writing perl code for Koha ...
All DBI calls should be checked for errors.
All scripts or modules should have "use strict" and preferably "use warnings".
Editor's Note: This was true until just recently... we are currently in the midst of sorting out how to handle modules and -w / use warnings in addition to some questions about which Perl version to use as a baseline for installs. If you're deeply interested, ask the collective mind of the developer list, and they'll fill you in on the current status of the discussion.
Subroutines should NOT open and close the database every time. The DBI handle (usually $dbh) should be passed as a parameter from the main script running. Opening the DB every time will impose a performance and overhead penalty for large or busy installations, limiting Koha's ability to scale.
What is unit testing?
Unit testing is a method for verifying that you software does what it is supposed to. The idea is that you have a testing framework (Test::Harness in our case) that will automatically run your tests for you, reporting any failures. You'll then write a series of tests to exercise every function of every module in your program. Instead of boring you with details, let's start with an example. For the Koha project, it is a key part of our effort to have production grade, reliable code.
How do I do it?
I'll start with the Koha.pm module. It contains four functions:
slashifyDate
fixEthnicity
borrowercategories
ethnicitycategories
All of our tests should go into the t/ directory, and should be put into a file showing which module we're testing. In this case, we'll create a file t/koha.t to hold our tests. Tests start with a bit of magic to make them work:
BEGIN { $| = 1; print "1..1\n"; } END {print "not ok 1\n" unless $loaded;} use C4::Koha; $loaded = 1; print "ok 1\n"; |
This sets up the test, tells the harness that it will be running one test (the 'print "1..1\n"' bit), and ensures that the test can load the module (that would be the first test).
If we run the test now, we'll get:
[pate@gnupate t]$ perl koha.t 1..1 ok 1 [pate@gnupate t]$ |
or:
[pate@gnupate koha]$ ./testKoha.pl t/koha..............ok All tests successful. Files=1, Tests=1, 1 wallclock secs ( 0.25 cusr + 0.11 csys = 0.36 CPU) [pate@gnupate koha]$ |
slashifyDate takes a string representing a (MySQL style) date, replaces '-'s with '/'s and returns it in European style date. We can test it like this:
$date = "02/01/2002"; $newdate = &slashifyDate("2002-01-02"); if ($date eq $newdate) { print "ok 2\n"; } else { print "not ok 2\n"; } |
We'll also need to let the harness know that we've added a test, so let's change the first line to look like this:
BEGIN { $| = 1; print "1..2\n"; } |
Now, running the tests looks like this:
[pate@gnupate koha]$ ./testKoha.pl t/koha..............ok All tests successful. Files=1, Tests=2, 1 wallclock secs ( 0.23 cusr + 0.09 csys = 0.32 CPU) [pate@gnupate koha]$ |
Then, we can go on and add tests until we end up with something like:
[pate@gnupate koha]$ ./testKoha.pl t/format............ok t/koha..............ok t/output............ok t/require...........ok All tests successful. Files=4, Tests=40, 1 wallclock secs ( 1.25 cusr + 0.11 csys = 1.36 CPU) |
What needs to be tested?
You don't need to test everything, just the things that can fail.
Ok, so maybe this is overkill. But we really should (and try to) test aggresively. Not only should we write tests for expected input, but also for fringe cases that should produce failures.
Additionally, anytime we fix a bug, we should try to represent it in one (or more) unit tests. That way we can feel comfortable that no one accidentally reintroduces the bug later on.
Who writes the tests?
We do. In fact, it is best if the programmer who sits down to write new code would do well to write some tests first. This way, he (or she) will know they got the code right. It's a tremendously liberating way to write code.
When do I run the tests?
Please, run the tests every time you're ready to check code in! Then fix any errors before you check in. Right now, the tests all pass on the rel_1_2 branch. Let's keep it that way ;)
The Koha CVS repository can be checked out anonymously (via pserver) with the following commands. You must specify a modulename. When prompted for a password for anonymous, simply press the Enter key. This is recommended only for those willing to deal with Alpha and Beta versions of Koha. Do Not use this software on production hardware.
cvs -d:pserver:anonymous@cvs.koha.sourceforge.net:/cvsroot/koha login cvs -z3 -d:pserver:anonymous@cvs.koha.sourceforge.net:/cvsroot/koha co modulename |
Updating from within the directory of the module avoids the -d parameter requirement.
Only project developers can access the CVS tree via this method. SSH1 must be installed on your client machine. Substitute modulename and developername with the proper values. Enter your site password when prompted.
export CVS_RSH=ssh cvs -z3 -d:ext:developername@cvs.koha.sourceforge.net:/cvsroot/koha co modulename |
Currently, we are in the process of setting up Bugzilla for bug tracking. More on this later.
Koha has a dedicated group of people who translate both the application and it's documentation. You are invited to join them on the koha-translate list(see "Mailings Lists", in the Developer's sections of the documentation), and sign up as a volunteer on the wiki [http://www.saas.nsw.edu.au/wiki/index.php?page=TranslationTeams]. We ask that, if you are interested in fully supporting koha, you find at least two people willing to participate, including yourself. We prefer at least one person have conversation-grade or better English and translation expertise, and all translation volunteers to be members of the koha-translate list.
There is an automated tool we expect to be used for submission of translationed documents, see: http://www.haz.cmsd.bc.ca/cgi-bin/kohadoc/upload for more information. Information on submitting translations for the templating system can be found in the Templating section below.
Additionally, Katipo makes a user-friendly tool called Kea for creating versions of the koha.org site available, if you are interested. We'll be using Kea (eventually) to make translation easier.
Like many open source applications, Koha uses the DocBook SGML system for creating formal documentation. This manual is the product of the db2format tool suite. Translations of the manual are done of the SGML edition of the manual, not of the generated HTML.
To create the online edition the SGML is run through db2html, and the resulting output (html files) is run through htmltidy -- currently this is run automagically, and the results sent to CVS, by Steve Tonnesen's CMSD hosted uploader.
The Koha project team, users, and translators use a variety of mail lists to facilitate communications:
The Sourceforge project page for koha (http://sourceforge.net/mail/?group_id=16466) has instructions for the primary lists for developers and translators:
For Developers
* Koha-devel, the primary contributors list for Koha,
* Koha-win32, for those interested in or developing the windows port of Koha,
* Koha-cvs, for those who contribute code to the CVS repository hosted at sourceforge.
For discussion of advanced features and long range goals, and potential library system proposals (ie, if you're interested in Koha as a possible solution for a state or county system) investigate the koha2010 list at http://www.kohalabs.com/projects/koha2010/mail.html.
For Translators
* Koha-translate, the primary list for work on and about documentation and translation efforts.
In addition, a number Specialty lists are hosted at other sites. These include:
* Koha-fr, the French language and translators list,
* Koha-de, the German language and translators list,
* Koha-biz, for those interested in doing commercial support for Koha,
* Koha-presents, for those who do Koha related presentations/pitches.
Subscriptions to and archives of these lists are available by sending email to koha-subscribe AT fr.koha.org,koha-subscribe AT de.koha.org,kohabiz-subscribe@eylerfamily.org, kohapresents-request AT world.std.com, respectively.
For general users, there is the original Koha list (info: http://koha.org/mailing).
For those interested in Koha's general progress, Koha-announce is used for bare-minimum updates on the status of the project, including new version notices, the semiweekly newsletter, and major announcements.
The koha project uses the terms themes and templating to refer to a set of functions that permit easy porting of koha to other languages and customization of the appearance of Koha's front end.
How does it work?
Every page served up by koha comes from two files:
* A perl script that makes database searchs and handles requests etc. The script loads a template and defines some template-parameters that are displayed in the template.
* A template that provides the HTML design. Data generated by the script is substituted into the template where you enter special template-parameter tags.
Koha uses templates to handle internationalization and appearance customization.
About Templates
Templates are principally a means of separating presentation and style from the data. This simplifies the data processing code while providing enhanced opportunities to customise the look and feel of the interface. Koha uses HTML::Template to export information from the underlying perl scripts. This information is combined with code contained in the template themselves. This results in the display of an apparently normal web page.
Template files are composed of mostly standard HTML code which is viewed by the end user via a standard Web browser. The template file also contain some special HTML-like tags which allow information passd from the perl scrips to appear as if they were embedded in the HTML template document itself. This is a similar principle (but not the same) employed by Koha Server Side Includes (SSI).
How to use it?
The systempreferences table in the database holds the settings that control how Koha chooses templates.To configure themes (currently) you have to set a variable
At present there are two places for settings: the koha.conf file (/etc/koha.conf), and the systempreferences table in the database.
In the systempreferences table, there is a block of options responsible for theme/template issues:
Name=opacthemes Value=theme1 theme2 theme3 ... |
Note: You have to specify at least one theme.
Go try it out!
So you can play around with the various settings, and look at some of the templates that have already been contributed, we have set up koha specially for you. opac-templates.koha.org <http://opac-templates.koha.org> is the publically accessible part of koha. You can access the user pages using the login..... intranet-templates.koha.org <http://intranet-templates.koha.org> is the librarians access into koha. In particular you can navigate through the "parameters" page to system preferences to try setting the themes and languages.Can I Contribute My Templates?
Of course. We welcome contributions from simple bug fixes to full multi-language theme suites! Templates can be uploaded into and edited on test koha sites mentioned above using the Kea content management system. You will need to register and learn a little about how to use kea. However it is very easy :-) Please read the instructions <contribute.html> on how to register and access content mangement system. Also we have collect some documents on how it all works and style/code guidelines etc.So.....
Currently, to make a template to make koha available in a particular language, you need to do a CVS checkout of the latest source, and copy /koha-tmpl/intranet-tmpl/default/en into /koha-tmpl/intranet-tmpl/default/XX, where XX is the two letter abbreviation appropriate for the language you are translating to (for help with getting an appropriate code, email the developer list). After that you can simply translate strings within the files. You also need to take care of the image URLs, as most templates make use of our "old" images, which live in SERVERROOT/images. Those specific to your language template should be placed in SERVERROOT/default/XX/images (only for your default theme, of course). Imagines specific to a theme (ie, a different look and feel for koha, not a language template) shoudl be in SERVERROOT/default/all/images. You may wish to substitute the default/XX bit with <TMPL_VAR NAME = "themelang">.
You also need to to add "opaclanguages / XX en" and "opacthemes / default" into the systempreferences file. If added, koha will use the translated templates when the exist, and the english one otherwise. If you don't do this, Koha will only the english templates.If you're interested in creating just a new look-and-feel configuration for Koha, please get in touch!
As the above is a fairly complicated list of things to do and keep track of, efforts are underway to use a tool provided by Katipo called Kea (a brief introduction to which is included in the appendices) for more user-friendly templating access.
If You're 'Theming', Please Remember:
* All templates should live in koha-tmpl, along with there associated includes and images (style sheets, javascripts, etc)
* The associated cvs branch will eventually replace the koha-html tree all together.
* Under koha-tmpl there are two subtrees: intranet-tmpl/ and opac-tmpl/, which correspond to what should go into the <serverroot>/intranet/htdocs/ and <serverroot>/opac/htdocs/ directories on the live sites.
* Under each of these are /<theme>/<lang>/ directories. Each theme can have different language settings. At present I have been working only on the /default/en/ templates.
* To do theme, language selection: In the scripts there should be the lines:
use C4::Output; my $template = gettemplate("opac-search.tmpl", "opac"); The gettemplate subroutine looks for the theme and language settings, looks for a template, loads the template and sets the <themelang> tag for use in all the includes etc. I.e. src="<TMPL_VAR NAME='themelang'>/images/search-button.gif" |
In the 1.3/2.0 releases of Koha, the exciting new function is marc compliance. As koha is an international project, every marc flavour is supported (at least, that's what we hope...) and as some users don't want to see marc in their ILS, the old-db style is supported as well. Thus, an important work is to define the parameters tables for the marc you want to manage. As this function is still being tested and ajdusted, documentation is currently available at http://www.saas.nsw.edu.au/wiki/index.php?page=UserDoc which covers the various parameters, and more technical information about the plugin is available at http://www.saas.nsw.edu.au/wiki/index.php?page=PlugInDoc .