Server Side Includes
Server Side Includes - what are they good for?
Server side includes are about getting the server to do some of the work - instead of having to forever change the This page last updated... line or editing hundreds of pages when your company decides to change the colour of the banner image, you get the server to do it for you!
They usually work by putting some kind of command, similar to an HTML tag, in the page with all the other HTML tags. You won't ever see any in web pages you download, as the server will have gone through that entire file prior to sending it to you, and will have changed all of these commands into plain text. So if you've ever wondered how on some pages the author has included the current time - which updates when you hit reload - or keeps all his/her filesizes correct for hundreds of files, you're probably looking at the output of a server side include.
What kinds are there?
HTML³ currently understands three types of server side include - the original Apache SSI, PHP, and ASP (VBScript). You can switch from one to the other in the Options window, and the sidebar will change to reflect which mode is currently being used.
- SSI (Server Side Includes - not to be confused with SSL, Secure Sockets Layer, an encrypted communications protocol) only work with certain web servers such as Apache or Zeus, and only if ModSSI has been installed (although this is usually done by default). This means anyone whose site is hosted on an NT server rather than a Unix machine, or if you have an evil paranoid SysAdmin, you're probably out of luck.
- PHP (Personal Home Page originally, now the self-referencing PHP: Hypertext Processor) is a separate application that can be called from the web server. Although it's capable of very complex things - it's a programming language with similar capabilities as Perl - I've simply converted the original SSI functions of HTML³ into PHP3 or 4 commands for convenience.
- ASP files are usually HTML files with embedded commands on Microsoft web servers (IIS), although you can get third-party add-ons for other web servers to deliver ASP pages. Usually the language you use to create these ASP pages is VBScript, a version of Visual BASIC, which like BBC/Acorn BASIC is a simple language but can be used to create some fairly complex programs. You can use ASP pages with PerlScript instead of VBScript, but if you know how to program in Perl chances are you can write something better than these simple commands yourself!
The downside to any sort of any type of include is of course that you can't see what you've done until after you've uploaded the page to the server. However, with this warning in mind I think you'll find SSI tremendously useful, and you can get Web servers with PHP and/or SSI capability under RISC OS if you want to set one up for local testing - Netplex from Warm Silence Software is a decent commercial one, and there's WebJames in freeware (use AcornSearch to find it).
The tools provided
From now on I'll refer to all types of embedded language - Apache SSI, PHP and ASP - under the blanket term "SSI". Here's a quick rundown of what I've included in the HTML³ SSI window:
- Date and time:
instead of putting in a static date, this actually updates each and every time the viewer (re)loads your page - ideal for a news site!
- File attributes:
You can get the server to take the strain of keeping those This page last updated on... lines updated - this is a completely automatic, enter once tag. Every time a page is looked at the server looks at the file you tell it to, and reads the datestamp or filesize for that file, and reports it back.
- File include:
The real workhorse - not the most flashy of commands as it has no fancy options, but it allows you to copy the whole of a file (or files when used more than once in a page) into the current page. Imagine - you're designing a 60 page site, and someone decides they don't like the colour of the header on every page. With SSI handling the headers, you just have to change one file and the entire site changes! The text could also be generated on the fly from a CGI, which means you can have ever-changing text coming out a program but inside a nice easy HTML framework.
Click here for a page on servers and how to check what you site is using
Setting your site up for SSI (straight Apache style)
SSI may not work on your site by default; you may need to switch it on. There's more than one way to do this, but it's best to ask your ISP's tech support department first. If it is switched on, then it'll more likely work for files with the extension .shtml rather than the more usual .html files. You'll notice that there's an option in the HTML³
Choices to change the extensions of files dragged to its windows, and .shtml is one of those available for web pages.
The RISC OS filetype for SHTML is &144, so always use this filetype if you want to test pages using Netplex. If you drag a file of this type to HTML³ though it'll always think the extension is .shtml if you have auto-correction switched on.
So what do you do if you don't already have SSI set up? If your ISP wasn't forthcoming, you can try the following. Create a file on your RISC OS machine called /htaccess (which will become .htaccess on the Unix machine). The contents of this file should be:
Options FollowSymlinks Indexes Includes
AddType text/x-server-parsed-html .html
Click here for a working copy of this file
(RISC OS archive)
Note that this is set to alter .html files - ArgoNet users who upload their sites via WebLoad won't get the option to upload their files with the .shtml extension (not without changing the filetype every time you're about to upload anyway), so I'm making it work for the more standard extension; this does put more pressure on the server, as it has to check through every HTML file in your site for SSI code.
Talking of ArgoNet users, this fix will defintely work for the old server called golden, but will not work for virtual domain users on the new machine called madhatter - you need a change to the httpd.conf file and then the virtual server needs to be restarted. Who knows what will happen if all accounts are moved to madhatter...
Note: .htaccess files work on the whole directory they're in, and any subdirectories, and any sub-sub-directories. This means that putting a .htaccess file in your root (main) directory will affect the whole site. You can however put another .htaccess file in a subdirectory, and this will override the main file for this subdirectory, and any sub(-subx-)directories.
Setting your site up for PHP
Your site will either be running PHP3 or 4, or it won't; this is because it's a separate program to the web server (rather than being a built-in function), so if it hasn't been installed you can't trick the server into giving it to you. However, it's very common that PHP is installed along with Apache these days, in fact it's included along with most Apache RPMs (Linux install packages). Use the file extension .php or .php3 and you should be able to use PHP.
As with SSI however you can trick the server into parsing files with the .html extension; you can do this in a "proper" configuration file or a .htaccess file (see the section about setting up SSI, above). This should be used with caution, as running another program whenever a HTML file is seen will make the server use up a lot more resources, which could slow it down a lot or even stop it working.
AddType application/x-httpd-php3 .html
Under RISC OS the filetype for PHP files is &18A, and you should always use this filetype if you want to test your files using the Netplex server. HTML³ will assume an auto-correct extension of .php3 for these files.
Setting your site up for ASP
Again this is a straight work/won't work situation; I've only briefly worked with an IIS/ASP web server and I'm not eager to repeat the experience too often, so I don't know too much about (re)configuring this particular server type. One thing to note is that files will end .asp; I don't know if there's a RISC OS filetype for it, but I doubt it.
Using the SSI Window in HTML³
The SSI/PHP window is essentially very simple - the bulk of the window at the top holds all the interesting parts, there's some layout controls, and the buttons that makes everything work at the bottom.
The top part is further broken down into three parts, which I already touched on in the introduction to this page - Date and time, File attributes and File include.
You may notice that when you open the SSI window, or when you click on certain icons, various bits of the Date and time area change - don't worry, this is supposed to happen! The date updates automatically to show you how the output will look, rather than trying to give complicated explanations.
The time area only changes the minutes (and am/pm indicator) because in the morning the 12 hour clock and the 24 hour clock will appear to have the same hour numbers. You can use the date, or the time, or both, using the same controls for both the Date and time and File attributes: last update sections.
It's also worth noting that there's no Make dragged files relative tickbox anywhere on this window - that's because it's switched on automatically due to the way SSI handles files.
Finally, depending on the webserver used and what version number is installed it's not always possible to "nest" SSI - for instance, you may not be able to have a date SSI command in a file that is to be used as an SSI included file, you should instead have the command to include the SSI file in your HTML, followed by another set of SSI commands to show the date. Even if this means chopping your header file in half, to half part in front of the date and part behind it, you'll still save an enormous amount of work in the long run.
Date and Time
Switch on the Date and Time option by clicking on the radio icon at the very top left of the window; then switch on either the date by using the tick box just underneath, or the Time tickbox lower down, or you can use both simultaneously. Obviously if you don't choose either then nothing happens when you click on OK.
After you've switched on the relevant section(s) of this area, you'll see that there's a number of radio icons available to change the date/time format; SSI uses a series of tokens in a similar way to the RISC OS tokens used by Alarm, or theAddress and Footer windows. However, I haven't allowed for a user-defined format because it's just too confusing - there's no actual correlation between the RISC OS tokens and SSI tokens, and unlike RISC OS tokens they're not easy to remember - the single letter used generally bears very little resemblance to the output it denotes, such as %B for as the month name - and are case sensitive - for instance, %d is day of the month but %D is the date in the US format mm/dd/yy. PHP does something slightly similar but different enough to make adding a user-defined option even more difficult, and ASP has to be programmed in a much more complicated fashion.
These are all the date formats, after this page has been uploaded to a web server and the output saved; unfortunately they won't show the current date, just the date that I last did this proceedure:
...and the time formats...
- dd/mm/yy (UK/EU): 14/01/00
- mm/dd/yy (US): 01/14/00
- dd/mmm/yy: 14/Jan/00
- day, dd mmm yyyy: Fri, 14 Jan 2000
- long_day, dd long_month yyyy: Friday, 14 January 2000
...and in combination...
- 24:00: 16:53
- 12:00 a/pm: 04:53 PM
All of these formats are available when showing the Last update of a file by using the File attributes section.
Friday, 14 January 2000 04:53 PM
Differences in display
Note that the format might change slightly when used on different versions of the web servers and includes. For example, Apache 1.2.4 has leading zeros on dates; Apache 1.3.x has spaces instead; PHP probably won't have any leading spaces or zeros at all. The AM/PM indicator may be capitalised, or lowercase. With the full date output PHP is capable of putting an "ordinal suffix" on the end of the date, such as th or nd as in 12th or 22nd, which I think looks much nicer. I have written code to do this for ASP, but as it takes up another nine lines of code (albeit short ones) on an already much larger output when compared with SSI or PHP I decided to leave it out.
There are basically two file attributes you can get access to here - the date (and/or time) a file was last updated, and how big it is. Because this is completely automatic, you can for instance have both of these commands pointing to an archive on your site and when you upload a new version of that archive the web page will reflect the new date(/time) and filesize without you having to touch the web page at all. As well as "other" files, you can also point the server to the current page and have a This page last updated... that automatically changes itself.
You can select the File attributes radio icon to enable this function, or you can drop any type of file onto the large white arrow off to the left hand side; this will automatically enable this option as well as filling in the long white box where the file's name has to be entered.
The Last update option has no sub-options of it's own, as it uses the Date and Time options in the Date and Time area to save space. The output is exactly the same as with the Date and Time stuff, so you'll have to supply your own introduction (This page last updated on, This file last uploaded at and so on).
The Size format comes in two flavours - a byte count which is fine for very small files, or the more useful KB count - in pure SSI the server adds a lower-case k to the end of this number, I have told HTML³ to add a lower-case b to make this kb, instead of kB (and of course, the proper version, KB, is not available unless you're using PHP).
The two formats look something like this when used in anger:
- bytes: 817,620 bytes
- kb: 798kb
With PHP the byte count will look the same, but the KB count will come out as:
because PHP can do some clever tricks like rounding up. ASP is the same as SSI, but with a capitalised KB, and no commas in between the numbers.
As with the File attributes section you can either switch on this section using the radio icon, or you can drop files anywhere on the SSI window apart from the File attributes area. Note that you can only drop hypertext files (HTML, WML, SHTML, PHP, Text and Data) with this option, as it would be a bit pointless and probably rather messy trying to include raw data from elsewhere!
There's not really much more I can say about this option - it dumps stuff fom one file into your HTML file, that's it, show's over. It's worth noting though that you can only use files that are available by navigating around the directories on your site or server, so for instance trying to include a file by calling it http://www.goodwin.uk.com/index.html won't work - I'd have to use something like ../../../index.html. To include a output from a CGI therefore you would need to call it something like ../../cgi-bin/popquiz (or if using straight SSI /cgi-bin/popquiz will work, as using the / mark to get back to the root directory is standard directory navigation). Note that adding a / to the front of the filename in SSI or ASP mode will change the type of include used from virtual to path or vice versa; note that SSI uses virtual for relative paths and path for absolute ones, and ASP seems to do it the other way round, which HTML³ should be able to take care of; otherwise they use the same tag syntax for compatibility <fx name="snigger">.
If your site can be access by many different names and/or domains then this can confuse the server when trying to work out routes to SSI includes - or indeed graphics files and links - so you might want to consider putting a base href into your HTML header.
There are two layout controls - Font size and Alignment.
Font size sets an absolute size of between 1 (small) and 7 (very big), where 3 is the norm. Setting the size to 0, which is the default value, switches this option off.
1) 14/01/00 04:53 PM
2) 14/01/00 04:53 PM
3) 14/01/00 04:53 PM
4) 14/01/00 04:53 PM
5) 14/01/00 04:53 PM
6) 14/01/00 04:53 PM
7) 14/01/00 04:53 PM
0)14/01/00 04:53 PM
Alignment uses <div align="...">...</div> to set the text to be left, centred or right justified, or by using the Default option this area is effectively switched off. Note that the <div> command causes a linefeed before and after the SSI, so if for instance you want to put The date is or This file last updated on the same line as a date, you have to work inside the <div></div> tags.
14/01/00 04:53 PM
14/01/00 04:53 PM
14/01/00 04:53 PM
If you want to know more about SSI, you can find the full documentation I originally wrote for ArgoNet at http://www.houseofmabel.com/programs/html3/ssi.html. This goes into a lot more detail, and has stuff about setting up context-sensitive pages (like changing colours depending on the time of day), but even I haven't been able to master the advanced stuff - yet
PHP documentation can be found at http://www.php.net/
ASP stuff can be found all over the place, including the Microsoft website. You know the address already, don't make me put a link in.
HTML³: © Richard Goodwin 1997-2002