Style Guide
Book ofStyle from 1999
I just unearthed this while looking for something else in my backups:
Matthew R. Yarbrough
2.5.99
Table of Contents
Basic Conventions
Web Safe Colors
Web Safe Fonts
Using ASP Fonts
Supported Browsers
Goals
Practice
Browser Features
How components affect page size
Error Checking and you
How to use Includes
Site Structure using ASP
Navigation
Goals
Practice
Naming Conventions
Definitions
Hidden Form Fields
Return To Top
Basic Conventions
These are the standards that a good website should meet. Thesestandards are as follows:
The pages must be viewable and functional in Netscape Navigator 2.0.
The site must be optimized for access by the disabled.
The pages must download reasonably quickly over a 28.8 connection.
The site must have consistency and ease of navigation.
The site must fit into a 800 X 600 screen.
The site must use colors and fonts which are web safe.
In order to meet these standards, the following guidelines are provided:
The site must be viewable and functional in Netscape Navigator 2.0.
For all intents and purposes, Navigator is a good base line todetermine if a site "works". If the site is accessible, and it does notcrash the browser, it is deemed to work. Naturally, the site will lookbetter in newer browsers, but that should not preclude less advancedusers from accessing the site. In order to comply with Nav 2.0standards, all bells and whistles (JavaScript, Flash) should degradegracefully. If you are using something that does not degrade, there hasto be an overriding reason that you are willing to sacrificeaccessibility. Other than specific client request, I can think of noreason to sacrifice accessibility. Actual HTML code (as opposed to ASP)should fit within the confines of the w3c HTML 3.2 spec(http://www.w3.org/TR/REC-html32.html).
The site must be optimized for access by the disabled.
In accordance with the Americans with Disabilities Act, you should tryto provide for the needs of the visually impaired. It is important toprovide ALT and SIZE tags for all non-text elements of a site, thiswill not only help with page layout as it downloads, but it providesfeedback to the users who are unable to see graphics. Keep in mind thatthis includes many users on older systems and in other countries whoare using a text-only browser. Yes, Lynx is still out there and stillbeing supported. A great place to check your site is Cast:Bobby. Thiswill check your site, rate it and suggest things you can do to improvethe rating.
The pages must download reasonably quickly over a 28.8 connection.
This is a guiding principle, though the specifics will change astechnology disperses. The goal is to allow the average user to accessand navigate the site quickly and easily, and this is the "quickly"aspect. For reasonable download times, pages should be no more than 65Kin total page weight including graphics. This is harder to gauge whenusing XML (such as ASP and Cold Fusion) as only the relevant componentsof a file are downloaded by the user. Animation tends to be ratherlarge, and can bump the page weight up a great deal, so be aware thatwhile a Flash animation may only be 8k, the corresponding GIF may be50K.
The site must have consistency from amongst same level navigation, andsub areas must have a look and feel that is consistent with the site asa whole.
The user should not have to guess where they are. Fonts, colors,location of logos, and so on should be consistent from area to areawithin each depth. The site must be consistent in it's use of fonts.That is the font used for the body should always be the same, and theheadings should always be the same, but the body need not be the sameas the heading. The section on fonts offers a more complete descriptionof how to achieve this. Remember that tables will ignore allsurrounding font information. This means that EVERY cell must have itsown set of font tags, or that cell will display text the in thebrowsers default font. On your browser this might be the same as theexpected font, but on someone else's, who knows. Be careful and includefont tags for everything. You can use Cascading Style Sheets to dealwith this, but then you are presuming that only people using IE will beviewing your site.
The site must fit into a 800 X 600 screen.
Realistically this only applies to width. If the user ever has toscroll horizontally on a 800x600 screen with the browser occupying thewhole window, that is bad. Vertical scrolling is a fact of life. Thisis especially important for the graphic artists, as this places anupper limit on the width of any graphics, and it is not 800 pixels.Because the browser will always take up a certain amount of space withits borders, scollbars, navigation, etc. the effective display area is762 pixels wide. As the webmaster you need to make sure that all of thetext, tables, etc. that you place can fit into the display area withoutforcing horizontal scrolling or odd artifacts. Sometimes, on a smallscreen with fixed width (even % widths count here) inside other tables,a table will slide under a graphic and look very odd, so make sure thatyou take in to account the presence of any graphics. And, as much aspossible the site you create should also expand to 1280 wide withoutlosing the design. Whenever possible take advantage of the browsersability to adapt to the users environment.
The site must use colors and fonts which are web safe.
This will be dealt with in detail in the areas on web-safe colors andweb-safe fonts, but the basic idea is: use colors and fonts that usersare going to be able to see the way you intended them.
Technical Details
When designing for the Web, there are several constraints that areunique to the internet. It is important to keep these issues in mindwhen designing site in order to ensure that the average user will beable to see the site as it is intended.
Return To Top
Web Safe Colors
In spite of the wide availability of cheap video cards that supportmillions of colors, the average user is still using 256 colors. This isdue both to the users who are still using older computer systems aswell as to the reluctance on the part of many users to mess with theirsettings. There are effectively 216 colors that can be used on theinternet, as the OS tends to use about 40 colors (this will varyslightly for non-Windows platforms, but the accepted standard is 216colors). These colors can be entered using color name, but this is notrecommended as different browsers will have slightly differentinterpretations of the names. It is safer and more consistent to usehex codes for your colors. A hex code is a 6 digit code that breaksdown into three 2-digit pieces, these are referred to as "browser safetriplets". Each piece maps to an RGB value that is considered "websafe". The code pairs that can be used to build the hex codes andcorresponding RGB values are:
00 00
33 51
66 102
99 153
cc 204
ff 255
Any three of these sets can be safely combined to render a color thatwill be reasonably consistently interpreted by all major browsers. TheArt Director for the site determines ahead of time what the RGB valuesare for each color. Obviously, there must be exceptions to usingbrowser-safe colors. Images of people for instance, but these aregenerally saved in the JPEG format where everything is dithered anyway.
Return To Top
Web Safe Fonts
The fonts considered to be web-safe are as follows:
Win Mac
Arial Bookman, Geneva
Times Times
Verdana Helvetica, Chicago
Tahoma Helvetica
Symbol Symbol
Courier Courier, Monaco
Georgia Palatino, Times
Impact Chicago
When selecting a font, make sure you use both the Win and Macequivalents.
Return To Top
Using ASP fonts
Keeping fonts uniform across and entire site, and consistent with thesite design is extremely important. If you are working with a clientthat uses IIS or a UNIX webserver that supports Front Page Extensions,you can application variables from the global.asa file, and define yourfonts in the global.asa.
In order to use these standard pieces on the site, you need to surroundany given piece of text with the start and end ASP font tags. Forexample %= application("font_subhead")%Sub-heading%= application("font_subhead_close")% produces text in the sub-heading font. Probably the easiestway to do this consistently is to set up tag snippets in your editor(or something similar, if you aren't using Homesite).
Return To Top
<><>
Supported Browsers
Goal - You should try to support a wide variety of browsers, withvarying degrees of sophistication and success. In principle I supportdown to Netscape 2. Because of the way the early months of the browserwars went, IE 3 is roughly equivalent to Netscape 2.
Practice - Supporting Netscape 2 however, does not mean that everythingwill work perfectly. What it does mean is that the site degrades insuch a way that users can see the information, and expect their browserto not crash.
Netscape 3 has some limitations on what it can and can't do, and theversion 4 browsers support most of the same things. Realistically, IE 3and Netscape 3 are probably your target audience, though if you want(or your customer wants) to target more recent browsers, just make sureit doesn't blow up older ones.
Browser Features
Function/Browser Netscape 2 Netscape 3 IE 3 Netscape 4 IE 4
ALT tag on Image Rollover X X X
Table background color X X X X
Table background image X X X X
Table Cell Color X X X
Table Cell Background Image X
Page Background Image X X X X
Locked Page Background Image X
JavaScript Image Replacement X X X
JavaScript Form focusing X X X X X
Automatic download of plugins X X
Use this chart as a reference for which browsers support what features(as you can see, Netscape 2 is pretty feature poor). A few explanationsare in order:
ALT tag on Image Rollover - this is when a little (usually yellow) boxpops up, like a tool-tip, and displays the contents of the ALT tag whenyou hold the mouse over an image for a second. This is different fromJavaScript Image Replacement
Table background color - the ability of a table to have a differentbackground color from that of the page
Table background image - the ability of a table to use a tiled image asa background
Table Cell Color - the ability to designate the color of INDIVIDUALCELL backgrounds within a table
Table Cell Background Image - the ability to designate a tiled image asthe background for an INDIVIDUAL CELL in a table
Page Background Image - using a tiled image as the background for theentire page
Locked Page Background Image - the ability to "lock" the backgroundimage, so that it does not scroll with the page (content will appear to"flow" over the image)
JavaScript Image Replacement - a feature of JavaScript 1.1 and the DOMwhich allows dynamic image replacement (swap one image from another).This is commonly used in menus and error checking. It can be associatedwith various mouse actions, such as moving into or out of an area onthe screen. This is different from the appearance of the ALT tag overimages in some browsers.
JavaScript Form Focusing - using JavaScript 1.1 to place the cursor ina specific form field. Often used with forms and error checking. InNetscape 2 this may be prevented by an "Out of Memory Error"
Automatic Download of Plugins - Later versions of Internet Explorerwill automatically "fetch" an Active X controller for the user.Netscape supports a similar feature for Plug-ins, but not very well,and we generally avoid using it. Most commonly used w/ the MacromediaShockwave Flash Active X Control.
How components affect page size
Web pages are no longer simply plain text (like this page), but includegraphics, animation, streaming audio and video, assorted script andprogramming languages (CGI, VBScript, JavaScript, ActiveX). Each ofthese components adds weight to the page. Design with the 28.8 modemuser in mind, and try to have each page download in less than 8seconds. This means that effectively you will try to limit each page to65K or less. (This entire document is 61.8K). Most HTML Editingprograms offer an option to check your page weight. This is useful, butnot always entirely accurate. The most effective means of checking isto dial-up on a 28.8 modem in the late afternoon, when net traffic isat it's peak.
Return To Top
Page Size
Managing the components that affect page weight is a matter ofplanning. The primary area of concern is animation. Animation is verypopular and flashy, but it must be kept to a minimum in order tomaintain a reasonable download time. It is customary to have ananimated logo for the client, and if this is the case any furtheranimation is not advised.
A more subtle area of concern is the ASP pages. The server checksthrough every potentially included ASP page during it's initial pass.This means that if there is an include link to a page inside an IFstatment, regardless of the results of that IF statement the serverchecks to see that the file exists. And of course it loads andevaluates any pages which are actually included. If a page has too muchinfomration on it, this evaluation can slow down the serversignificantly in serving the pages. You will see this sort of problemas a slow response from the server. It isn't a common problem, but isone of the reasons that the second-depth contents files should bebroken up. It can also be a problem in forms which contain largeamounts of redundant information. For example, I worked on one siteasked users to select the state they were in, and then had 50 possiblenext pages. Twice. Once each for two different forms. Simply grindingit's way through that decision tree took the server a while. Since theactual information displayed on the next page was the same for everystate except for the name of the state, and whatever state-specificinformation came out of the database, we changed the first page to passthe name of the chosen state in an ASP variable. Then all we had to dowas write out that varaiable on the next page. This reduced 50 possiblechoices to 1 for each process. It would be possible to reduce it to asingle process by sharing the state-selection portion between the two.There would still be some server load assocaited with that, but itwould reduce the sheer amount of information to be maintained.
Return To Top
Error Checking and you
Forms are a pain. Let's establish that right up front. However, theyare also extremely useful for our clients and for us. The primaryproblem of forms (after formatting them) is making sure the user putsin the information that you want. To resolve this issue, we use errorchecking.
All forms which have some fields which must be filled out, or mustcontain a certain type of text, use error checking. Error checkingshould accomplish the following, if there are errors:
Clearly indicate which field(s) need to be corrected
Places the cursor in the field to be corrected
Provide the user with some indication of what might be wrong with theentered information
Require the user to submit the form as few times as possible
Do not proceed past the current page until the form is validated
Indicate fields to be corrected
This is done through the use of JavaScript Image Replacement. Severalred exclamation marks appear next to a field which contains an error
Place the cursor in the field
This is done with JavaScript Form Focusing. Only one form field at atime can be effected, and so only the last field checked will actuallyhave the cursor located in it, though if you're quick of eye, and yourmachine is slow of processor, you might see it flicker through severaldifferent input fields as the form is checked.
Provide Feedback
Most often this amounts to telling the users that a required field hasnot been filled out, but it can also be information about a requirednumber of digits in a phone number, etc.
Minimal Submission
The error checking goes through the entire form before allowing theuser to correct mistakes. That way they know everything that needs tobe fixed, and don't have to continually submit the form fixing oneproblem at a time.
Summary
All of this is summarized visually on the last page of this documentwith a labeled screenshot. This shows a standard vanilla form which hasbeen submitted with no information filled in. All of the fields arehighlighted with red exclamation points, the cursor is in the lastfield checked (in this case "eve phone"), and a single JavaScript alertbox is present summarizing the reasons the form was not submitted andproviding the user with information. With variations in language tomeet the desires of the clients, and make clear what needs to be done,this is what an incorrectly submitted form should look like.
Degradation and Known Problems
Obviously the JavaScript Image Replacement does not work on allbrowsers. Users should see no image if their browser does not supportthis. There should be no errors associated with it. A similar situationexists when placing the cursor in the field.
Netscape 3 has an intractable JavaScript error, where it often, but notalways, produces an error with the message "undefined is not a number"after the form has been successfully submitted. The line numberassociated with this error points to various places depending on theexact site being looked at, and often to a line w/ no JS content.During troubleshooting the error becomes inconsistent, and cannot bereliably associated with any specific section of code. Sometimes itjust goes away on its own and then comes back later. At this time, wehave decided to let it go.
Netscape 2 will usually produce an out of memory error and not run theJavaScript at all. There is no error checking in Netscape 2 sites. Theform can still be filled out and submitted. Because this comprises sucha small number of users, I would not be too concerned, as the effortrequired to make all sites backward compatible with Netscape 2 isvastly out of proportion to any imagined return.
Similarly, old non-Internet Explorer versions of AOL do not support anytype of error checking. These should not report any script errors.
Return To Top
How to use Includes
Includes are your friend. Include files are used to call large amountsof content that would be unwieldy in the primary file or files that aregoing to be displayed on many or all pages in a site. An example wouldbe creating the basic structure of a site. The index file could callincluded files such as header, footer, buttons, and contents. The firstthree are components that will show on every page of the site, whilethe last calls specific content based on variables. I use include filesto ease the maintenance of client sites and to simplify the sitestructure. Deciding if an area needs an include is a matter ofjudgement, and varies from client to client. If an area has several subsections, it can be useful to place all those into an include file(productinfo.inc, support.inc, etc. for example) and call to those fromthe index.asp file. It might seem to make more sense to call them fromthe content.inc include file, but as a general rule you should nevercall an include file from another include file if you can possibly helpit. It used to be that this could actually generate errors. While thisis seldom the case now, it does make it much harder to track down theoffending file when errors do occur, or when material needs to bechanged.
Return To Top
Site Structure using ASP
The index page is the building block from which all else springs. Theindex serves as a framework that places all content regardless of whatarea of the site you are in. In many sites there are multiple levels,or depths, that each have their own index. Again, the purpose of theseis to maintain a consistent look and feel for each depth. There shouldnot be any content in the index page. It should contain only includecalls, body attributes, and layout information. All fonts and colorsare called from the file global.asa in the root directory of theclient. Rather than enter complete font tags, such as fontface=verdana, garamond, comic color=ff6600 size=2 you willplace a call to the global.asa using the format %=application("font_body") % content %=application("font_body_close") %. This makes maintenance mucheasier and ensures consistency from page to page within each site. Irecommend creating tag snippets in your HTML editor (assuming itsupports them) to make your life even easier. There are, as a rule,five sections to each page: Header, Primary Navigation, SecondaryNavigation, Content, and Footer. Where these show on each page is afunction of how the index file is laid out. It really is that simple.
Header - This file contains items such as client logo, header graphics,perhaps some animation, etc.
Primary Navigation - This contains the means for the user to find theirway around the site. It will usually consist of graphics, thoughsometimes the navigation will be via text links. We generally useJavaScript to activate rollovers for buttons, and the script isincluded in the Templates. Primary Nav is used to move around betweenthe major areas of a site (e.g. Product Information, Support, HR).
Secondary Navigation - Secondary navigation is sometimes included inthe same file as primary navigation, though it usually is located on adifferent part of the page (directly under the header, for example).Secondary Nav is used to move around within a specific area (e.g.Product X, Product Y, Product Z).
Content - Obviously, this is where all of the actual text,content-related graphics, multimedia, etc are located. Once a site is"live" this section is the only one that will really be worked on. Itcan come in more than one section, depending on the complexity of thesite, and alternate depths will have different content files.
Footer - The footer contains any standard information we want to appearon all pages but is not a focus of the site, examples being thecorporate logo and copyright information.
Return To Top
<><><>
Navigation
Goals - Ease of Use, Consistency.
Practice - Sites should be built with the dual goal in mind. It shouldalways be obvious to the user where they are in the site, and how theycan get to another section. The location of section titles andnavigation should be consistent from section to section within eacharea.
Return To Top
Naming Conventions
In order to ensure ease of maintenance, consistency in naming files andgraphics is crucial. Obviously spaces are not allowed, so to avoidduplicate names, and to make names easier to read, a "-" or "_" isgenerally used to separate words.
HTML/ASP File Names
File names are built up out of some standard parts:
index - every main page should contain the word index, and the firstpage the the user hits must always be index.real or index.html.
contents - files which contain content information for one or moreindex pages
buttons - files which contain buttons for one or more index pages
others - other files should have names that relate to theircontent/function (registration_form_process.asp, copyright.inc, etc)
Graphics File Names
Graphics tend to have their own quirks, built up as different GraphicArtists and Webmasters have added their own bits. As a rule, graphicsare named type-name.[jpg|gif|swf]. This way, it is easy to find all thegraphics of a similar type, since they are all together in the filelist. Naming of graphics should perform the same function as the ALTattribute of the IMG tag. For example: green_login_button.gif is muchmore scrutable than grnlgbt.gif, especially 6 months and severalprojects down the road. If you're operating on a system that onlysupports 8.3 filenames, good luck.
Directories
Part of the naming conventions is the directory structure we use toorganize the files. Directories should be immedately under the rootdirectory for that site, and should not contain sub-directories unlessthey are absolutely necessary. The only things that should be in theroot direcotry are the index page(s), global.asa, and possibly otherrequired index pages. All other files should be in one of thedirectories. A suggested file tree is as follows:
includes home of all include files, buttons.inc, copyright.inc,contents.inc, etc.
resources home of all graphics, shockwave, or other media files (exceptReal Audio - those may live on their own server)
As you can see, this would make finding pieces of the site ridiculouslyeasy.
Return To Top
Definitions
Areas - The easiest way to think of areas is as pages. Any discreetpage you see on the site is an area. But really areas arecontent-related parts of the site. Areas often have sub-areasassociated with them, each of which is an area is it's own right.
Depths - Depth is a fairly abstract concept. The name comes from theidea of "drilling down" through a site, but it really has to do withthe type of information displayed, and how that information is laid outon the page. Most sites have two, or maybe three depths. Thus primarynavigation areas, such as "welcome", "products", support so on allshare certain characteristics. They contain the general informationabout an area on the site. The pages all have a certain appearance --Header here, primary navigation there, secondary navigation (if neededover there), contents in this spot. The second depth might deal withthe sub-areas, and the layout may be different from the first depth.This is where depths relate back to navigation and providing continuousfeedback to the user about exactly where they are in the site. It ispossible that a site might be designed where every area is it's owndepth, however I generally discourage that because it makes the sitedifficult to maintain, and creating truly consistent and clearnavigation can be much more difficult.
Push - The process of moving files from one server to another.
Return To Top
Hidden Form Fields
There are all sorts of reasons to use hidden form fields, but the twomost common are to pass on information from a previous form, throughthe current one, and on to another page, and invisibly tracking if theuser has submitted a form yet. The next topic deals with the former, soon to the latter.
In order to keep the navigation fixed on the Inquiry area even afterthe form has been submitted, and while the user is reading whateveron-screen response they receive, and without using a second URLvariable, a hidden field is just the ticket. Near the end of the form,in fact, often as the last thing in the form, add inputtype="hidden" name="submit" value="submit" Then, if you use thefollowing ASP you can easily keep the navigation focused where youwant, and still limit what part of the content gets processed by thebrowser by checking to see if the form element "submit" is defined:
% if Request.Form("submit") = "" then % formaction="index.real?action=inquiry" ... and the rest of theform goes here . . . % else % and the form processingand response goes here . . . % end if % Using ASP topass form fields There are times when you need to collect informationfrom several pages of forms before processing the data. In that case,this bit of ASP will automatically collect all the previous formelements and add them on to the current form as hidden fields, with thesame name as they had before.
% for each x in Request.Form % inputtype="hidden" name="%= x %" value="%=Request.Form(x) %" % loop %
<><><><><><><<><>><>