Back to files

First off, a note on AUPs and Licenses.

This software is licensed under the same terms as Perl itself.

However, the data that xmltv provides may have limitations on how you are permitted to redistribute it. In particular, the Zap2IT source for North America rather clearly forbids this. Please do not use this software to violate those license agreements, as it may cause them to cease offering their data to xmltv users for free, and this would be bad for all of us.

How to install:

You will need the following:
* PostgreSQL - a version with schema support is needed * Perl - 5.8 is strongly recommended because of unicode support * mod_perl
* xmltv data

And the following perl modules:
* DBI

• DBD::Pg
• Date::Parse
• Time::HiRes
• Image::Info

=========================== Creating the Database ===========================

First off, you'll want to create your database. The schema.sql file contains the basics you'll need. The mkschema.sh will replace the placeholder schema name within schema.sql with the value you pass it as an argument, and spit the result out to stdout. So, you might do something like:

./mkschema.sh xmltv | psql database xmltvuser

And assuming the xmltvuser has create schema privileges (important!) it should create everything. If you want separate users for schema ownership versus reading/writing data, you'll have to setup the grants yourself. The pgadmin3 tool makes doing such mass grants easy.

============================= Loading the Data ==============================

Next, you'll want to load your data. To do this, run the xmltv-pg-load program with the source xmltv file as an argument. I.e.:

./bin/xmltv-pg-load ~/.xmltv/na.xml

Be patient. If it's a large file it may take a few minutes to load. This is something you'll probably want to schedule via cron to run after you download the new listings.

============================ Configuring the Web ============================

Finally, you'll need to setup the mod_perl pages. Assuming your Apache server is already setup to use mod_perl, you'll just need to do a few things. First you'll need to put the TVListings modules somewhere where mod_perl will find them. On my system, /etc/apache/lib/perl (might be /etc/httpd/lib/perl for you) is in the default search path, so you can copy lib/TVListings there. Otherwise you'll need to play with mod_perl directives to adjust perl's @INC search path.

Next, you'll need to check the Config.pm for any changes you might need to make. The key items to check for are the DBI connection parameters and the location of the CSS files. The tv listings will not come out very nice if the CSS cannot be pulled in.

When you put the CSS files in place, you will probably want to edit tvcolors.css and tvprefs.css. The first defines all the colors for the tv listings, and the latter is a place for you to mark channels you don't want to see, or want to have styled differently.

Once all this is done, you need to tell Apache about a location at which the tv listings should appear. Something like the following should work nicely:

<Location /tv>

        SetHandler perl-script
        PerlModule Apache::DBI
        PerlHandler TVListings::modperl
        Order deny,allow
        Deny from all
        Allow from 127.

</Location>

Other Apache options for authentication, adding local domains, etc. are left as an exercise for the reader. If you want to separate read and write access to the system over the web, you can add a second Location directive to further restrict access, like so:

<Location /tv/edit>

        AuthName restricted
        AuthType basic
        AuthUserFile /etc/apache/users
        AuthGroupFile /etc/apache/groups
        Require group tvedit

</Location>

Finally, if you want to save some memory and speed, you can add TVListings to your mod_perl startup.pl (if you have one), by adding somsething like:

use Apache ();
use Apache::DBI ();
use TVListings::modperl ();

If you want info on how to setup such a script, look at the documentation for the PerlRequire directive in the mod_perl documentation.

After doing all this, you'll need to restart/reload Apache.

============================ Using the Listings ============================

Now that all that is setup, you want to view the tv listings! Assuming all went well, you should be able to point your web browser at http://localhost/tv/ and get your tv grid! If you have Mozilla or Firefox, you can add a sidebar for http://localhost/tv/now which will provide an alternate tv grid specifically designed for the sidebar.

The "flag this as interesting" bit on the show details form allows you to emphasize or de-emphasize shows you like or dislike. Populating the database with this information is probably the biggest customization you will be applying. The "Good Stuff" link will make use of this information to show you a page with all the shows you like that are on now or on soon.

Hopefully most of the functions of the system should become self evident after clicking a few links. An approximate list of features to check for:

• Basic TV Grid
• Sidebar listings for what's on now
• Searching shows
• Show / Movie info on IMDB
• Listing interesting shows on now or soon
• Basic channel information and what's coming up on it

========================= If You're Really Curious =========================

There's some example code for a wxPerl application to show the current listings in there. If you're curious about such things, you might want to take a look.