Customisation of the Sage Web Server

There are several things that can be customised in the web server:

  • View style
  • Channel Logos
  • menu layout and items
  • saved searches and saved EPG views
  • colors and formatting
  • direct links to video files
  • Advanced server configuration
  • Disk space bar in Home page

View style

Most of the screens have a [show options] button which opens a section which allows you to customise the view. These settings are saved as cookies on your browser, so each browser can have different settings.

These settings can do things like:

  • alter sorting/grouping/filtering in Sage Recordings
  • alter filtering in Recording Schedule
  • enable/disable channel logos everywhere.
  • alter cell size in the EPG views
  • alter the number of hours/channels shown in the EPG views
  • add show description in EPG List view

To reset to the defaults, delete the cookies for this site in the browser.

Channel Logos

From version 1.5 onwards, the webserver gets channel logos from the same place as SageTV (the ChannelLogos? subdir of the SageTV directory, see the SageTV manual) -- there is no need for a separate channellogos subdir in the webserver/webroot/sage

The menu bar that sits at the top of the screen is defined in a JavaScript source file in SageTV/webserver/webroot/sage/menu_items.js

This file defines a multi-level array, with menu items and sub-menu items. Take care when editing this, any errors in the Javascript will cause the menu to fail to load.

Menu items can be to any valid URL, so you add saved searches, and even add bookmarks to external sites.

Note that any changes to the menu_items.js will require a refresh of the web browser, but not a restart of the Sage process.

Saved Searches/EPG views

All web pages in the server (even search results) can be bookmarked, so you can make a custom search (such as for movies in the next 48 hours on your 4 favorite channels) and bookmark them.

EPG views may also be bookmarked, but note that startdate is set to a defined date by default. Relative dates are supported -- replace startdate=2004/11/17 with startdate=n where n is the number of days to offset from 'now' (ie -1=yesterday, 0=today, 1=tomorrow), eg: for an EPG grid view starting tomorrow at 6pm 

   http://localhost:8080/EpgGrid?startdate=1&starthr=18

The default menu.properties has 2 custom searches and 2 EPG views defined as an example. I have chosen 'Prime Time' to start at 6pm local time, you may of course edit it to whatever you feel is appropriate.

Colors and formatting

The majority of the colors and the formatting is done with external CSS stylesheets in webserver/webroot/sage:

  • sage_screen.css -- for normal web browsers
  • sage_print.css -- for printing (removes menu bar, background, options etc)
  • sage_handheld.css -- for small screen/handheld devices (in 1.0 version this is the same as sage_screen.css because I have no handheld device to develop/test on!)

These stylesheets can be edited to change the layout, font size, background image, colours etc.

To reload a stylesheet, you normally need to refresh your browser with F5, or CTRL-F5 because the existing stylesheet is cached.

Direct links to video files

As of v 1.6, the webserver provides direct download links to all media files in Sage (videos, music, images). The webserver needs direct access to the disk where these video files are held, so if running on a client, the disk paths must match -- this is easiest done with UNC paths.

The Detailed Information screen for Sage Recordings can also include  file:// links that provide direct access to the video files.

To enable this, you need to specify the how to translate the video storage paths into URL paths. For example, the Sage server is called sage-server, and uses D:\Sage-video as a video path.

For a  File:// url accessible as a mapped drive over the home network:

  • The video directory is also available as M:\media\sage-video
  • This path can be expressed as the file url:  file://localhost/m:/media/sage-video/
  • Therefore there needs to be an entry in the paths.properties file as follows:
    d:\sage-video\=file://localhost/m:/media/sage-video/
    • The webserver will then append the video file name, and the link will show up in the detailed information screen.

For a  File:// url accessible as a UNC path over the home network:

  • The video directory is also available as \\sage-server\media\sage-video
  • This UNC path can be expressed as the file url:  file://sage-server/media/sage-video/
  • Therefore there needs to be an entry in the paths.properties file as follows:
    d:\sage-video\=file://sage-server/media/sage-video/
    • The webserver will then append the video file name, and the link will show up in the detailed information screen.

Note that the path in paths.properties must match exactly the path to the video file shown in the detailed info screen.

If you want to serve video files to the internet using this web server, you may want to limit the bandwidth used. This can be configured in throttles.properties (see also WebserverServingOtherFiles), by specifying a file path of: 

    /sage/MediaFile/*
or
    /sage/MediaFile/*.mp3
etc

Advanced server configuration

Some of the parameters used to start the webserver are stored in the sage.properties file, in the section: nielm/webserver/

These include:

  • nielm/webserver/root
    where the webserver configuration directory is
    Default: webserver subdirectory of the SageTV directory
  • nielm/webserver/port
    The port used by the webserver
    Default: 8080

  • nielm/webserver/log_access
    nielm/webserver/log_referrer
    nielm/webserver/log_user_agent
    Whether to log each access, and whether to include user agent, and referrer in the logging
    Default: false
    By default, log files will be created only upon error in the webserver/log directory

Other parameters are defined in the various .properties files of the webserver configuration directory:

  • aliases.properties : associates real paths to the paths in web requests
  • realms.properties : defines usernames and passwords for accessing web pages.
  • throttles.properties : defines bandwidth throttles for file types and paths.

Disk space bar in Home page

The disk space used/required/free bar in the home page uses the same sage.properties settings as the disk space bar in several of the custom STV's. These are:

  • nielm/diskbar_partials_free (true/false, default: true)
    Whether to treat partial recordings as free space
  • nielm/diskbar_lookahead_hours (number, default: 48)
    Number of hours to look ahead in the recording schedule when attempting to predict disk space required for upcoming recordings
  • nielm/diskbar_lookahead_only_requested (true/false, default true)
    Only include Favorites/manual recordings (not IR) when predicting required disk space
  • nielm/diskbar_used_space_warn (number 0-100, default 90)
    Percentage of disk space used before 'warning' color (orange) is used
  • nielm/diskbar_needed_space_warn (number 0-100, default 95)
    Percentage of disk space including required disk space for future recordings before 'warning' color (red) is used for upcoming recording space.

Multiple users with mutliple roles (guest / admin)

The webserver supports defintion of multiple users in the realms.properties file. The user can be specified for each page, which allows multiple users with different roles to be set up.

The format of the realms.properties file is: 

[Browser Prompt]=[web-path to protect],[username]:[password]
eg: SageTV Web Actions=/sage/Command,write:only

Note that the name of the prompt does not matter - but the browser uses it to internally reference a user/password...

Multiple users can be defined for the same path...

When checking for a user to access a page, the first matching path int he realms.properties will be used, so specify more specific paths before more general paths.

So if you want allow a guest user (with password GPASS) access to everything, but only an admin user (with password APASS) is able to change things, then you should have something like: 

# admin user access to commands/actions
SageTV Web Actions=/sage/Command,admin:APASS
SageTV Web Actions=/sage/AiringCommand,admin:APASS
SageTV Web Actions=/sage/ManualRecord,admin:APASS
SageTV Web Actions=/sage/ResolveConflict,admin:APASS
SageTV Web Actions=/sage/TimedRecord,admin:APASS
SageTV Web Actions=/sage/MediaFileCommand,admin:APASS
SageTV Web Actions=/sage/ForceEpgUpdate,admin:APASS
SageTV Web Actions=/sage/EditShowInfo,admin:APASS
SageTV Web Actions=/sage/EncodeCommand,admin:APASS
SageTV Web Actions=/sage/FavoriteCommand,admin:APASS

# Guest user acess to normal screens
SageTV Web Interface=/sage,guest:GPASS
# admin user access to info screens
SageTV Web Actions=/sage,admin:APASS