JMRI: Web Site

This page discusses technical aspects of the JMRI web site.

If you just want to know how to make a small change to a web or help page, please see the separate page of instructions.

Structure of Information

We distinguish between three types of information on the main web site:

User information which is useful at run time. This is made available both via our JavaHelp, and also directly by placing those files on the web.
User information which is either not useful at run time, such as instructions for installing the software, or is too large for inclusion in releases, e.g. video clinics.
Reference information from releases, such as decoder definitions, copies of scripts, JavaDocs, etc.

We provide these separately:

Run-time user information is made available by putting the help system on the web site.
Other user information is stored in Subversion as the trunk/jmri-website directory and placed directly on the web site.
Reference information is put on the web site from their own Subversion modules, or created by automated Ant scripts during release builds.

Technology

Page formatting is done using CSS, originally set up by John Plocher. All pages should reference the CSS files for screen and printing from the "/css" directory. This also means that you should leave the formatting to the style sheets, and minimize the explicit formatting that you do in HTML directly.

Because we use our web pages in JavaHelp, there are some restrictions on use of tags. See our JavaHelp web page for more on this.

We are using server-side includes to provide consistent headers, sidebars and footers. This allows us to share HTML content between the web and the JavaHelp system used by the program itself. Each page will contain just content, plus includes for files named "Header", "Sidebar" and "Footer" which contain the navigation information. Eventually, all but a few index pages will have ".shtml" extensions. (The remaining index.html pages keep that name so that people who request just a directory URL will be served something useful).

Directory Organization

The web site contains several separate areas, which translate to different SVN directories:

jython, resources, xml, web - these are taken directly from the directories of the same name under trunk/jmri/. They are only occasionally referenced directly.
help - from the Subversion module and JavaHelp system, this has the internal structure described below and on our JavaHelp page.

The rest are from the trunk/jmri-website, and are checked out at the root of the web server.

releasenotes - Specific information on each test and production release
install - Information on how to install the JMRI software on various kinds of computers
community - Clinics, web pages, and other community-contributed information
images - (Images used by web pages)
contact -

Updating the jmri.org site

Most of the web site contents is updated every 15 minutes from a job running on one of the project's Jenkins build servers. The directories listed above constitute most of the site, and this content is updated from the SVN server without any additional work.

Some of the site is generated from the JMRI source itself, as opposed to being contained in the source. The JavaDoc is one section, along with some of the information about the decoders available for use. These updates, especially the JavaDoc, involve significantly more work than merely updating a directory, and so they are performed nightly.

These steps are based upon checkins to the SVN repository -- the act of checking in modified files is sufficient to trigger a web site update if it is necessary.

The status of the web site updates is available on this JMRI CI server.

Local Web Site: Mac OS X

If you want to host a copy of the JMRI web site on your local Mac OS X machine, follow these instructions to first configure the Apache server to do server-side includes, and then make a copy of the web site files available to the server.

You need to edit the Apache web server's configuration file.
- On Mac OS X 10.4 (Tiger), this is the /etc/httpd/httpd.conf file
- On Mac OS X 10.5 (Leopard) and later, this is the /etc/apache2/httpd.conf file
Once you've located the file, open it with your favorite editor (You'll need to authenticate with the administrator password to modify this file).
- To turn on server-side includes, find the section that looks like
```
# This may also be "None", "All", or any combination of "Indexes",
# "Includes", "FollowSymLinks", "ExecCGI", or "MultiViews".
#
# Note that "MultiViews" must be named *explicitly* --- "Options All"
# doesn't give it to you.
#
    Options Indexes FollowSymLinks MultiViews
```
  Add the word "Includes" to the last line so it looks like
```
    Options Includes Indexes FollowSymLinks MultiViews
```
- Now, configure the server to handle files with ".shtml" extensions. Find the section that looks like (the leading comment may be different):
```
    #
    # To use server-parsed HTML files
    #
    #AddType text/html .shtml
    #AddHandler server-parsed .shtml
```
  and un-comment the last two lines so that it looks like
```
    #
    # To use server-parsed HTML files
    #
    AddType text/html .shtml
    AddHandler server-parsed .shtml
```

To check out a copy of the files:

Change to the web server directory
```
cd /Library/WebServer/Documents
```

Check out the relevant files

# the trailing dot on the next line is important!
svn checkout svn://svn.code.sf.net/p/jmri/code/trunk/jmri-website .  
svn checkout svn://svn.code.sf.net/p/jmri/code/trunk/jmri/help 
svn checkout svn://svn.code.sf.net/p/jmri/code/trunk/jmri/jython
svn checkout svn://svn.code.sf.net/p/jmri/code/trunk/jmri/resources
svn checkout svn://svn.code.sf.net/p/jmri/code/trunk/jmri/web
svn checkout svn://svn.code.sf.net/p/jmri/code/trunk/jmri/xml

Restart your computer to reinitialize the web server.
Test it by trying to display the URL http://localhost/, which should get you a JMRI index page.