4Getting started

Brackets is really all we need to start building and coding the website, but before we do this, we need somewhere to keep the website i.e. a folder structure that we can keep all the HTML, CSS, JavaScript and image files in.

This folder structure is, in essence, the website. It is this folder structure and its contents that will be eventually uploaded to a server somewhere and will then be viewed by the millions of web users that have been waiting for just such a website.

A folder structure is not a requirement, it is perfectly possible to just stick all the files in a single folder and the website will look and work just the same and the user would never know the difference. However, imposing a folder structure (particularly on a large website — which I think this is becoming) leads to better organisation — it’s generally easier to find things if there is an easy to follow structure to the site (and then there is my structure — just kidding).

This is broadly how I’ve structured the website (Figure 4.6):

You’re probably looking at it and thinking “my God, he’s given everything a number — what kind of anally retentive idiot is this?” — Well I’m an engineer. Engineers like to number things, it’s buried deep within us.

There are some conventions for naming files and folders on a website and these seem to be widely followed (within reason, you can always find exceptions on the web). These conventions are:

1. Always use lower case when naming files and folders

2. Don’t use spaces in file and folder names (use a dash instead)

3. Only use the characters [a-z], the numbers [0-9] and the dash/hyphen [-]

I think these conventions stem from the fact that a lot of web servers (the things that host the website) are based on UNIX; meaning that files and folder names are case sensitive.

In Windows there is no distinction between a file called Index.HTML and one called index.html (or indeed one called InDeX.hTmL or any combination thereof). If you tried to copy Index.html into a folder that contained index.html it would replace the latter with the former.

UNIX on the other hand would treat Index.HTML and index.html as two completely separate files and they could quite happily co-exist in the same directory.

So to avoid confusion all files and folders are in lowercase^†1.

†1		This confusion is sometimes only evident when you look at the content on the actual webserver (i.e. actually upload it to a webserver) especially if you are developing on a Windows machine.
		If you make a mistake with a file name whilst using a Windows development environment (let’s say you try to load an image called Fig-01-01.png when it should be fig-01-01.png); then it will work on the development machine (because Windows is not case sensitive when it comes to file names). When the file is uploaded to a UNIX web server, it won’t work; UNIX is case sensitive and won’t be able to find the file starting with a capital letter.

Spaces next. The thing with spaces is that these can be treated (encoded) differently by different web servers (even the Windows command line doesn’t like spaces in filenames, these have to be surrounded by quotes). The best thing to do is avoid spaces in file and folder names.

Use the dash to replace spaces i.e. 01-00-introduction.html not 01 00 introduction.html. It is perfectly possible to have underscores in file names — but don’t — it’s bad practice and there is some confusion (at least I was confused) when using it in host names (I’m not sure what a host name is, it’s different to a domain name, but I don’t know how).

Anyway, it’s dashes (hyphens) in place of spaces.

The folder structure starts with the root folder (again this is a UNIX term but is commonly used in web development), this is just the top level directory that lives somewhere on your machine and it holds all the content of the website.

On my machine it’s on a mapped NAS drive (network accessible storage — essentially, a hard drive connected to my network); it has the following path on my machine:

z:/ps-publications/1001-website/

The only file a website actually needs is one called: index.html

This is the file loaded by default if no specific file is given in the URL.^†2 I.e. typing www.practicalseries.com into a web browser will cause it to look for and load a file called index.html at that address.

other default file names
index.html is not the only default file name for a web site, the following all work:
index.html index.htm index.shtm index.php index.php5 index.php4 index.php3 index.cgi	default.html default.htm home.html home.htm Index.html Index.htm Index.shtm Index.php	Index.cgi Default.html Default.htm Home.html Home.htm placeholder.html
Note: the difference between lower and upper case in the starting letters
Web browsers look for files in the order listed above — starting top left with index.html and ending bottom right with placeholder.html.

†2		URL: Uniform Resource Locator — you know, a web page address like www.google.co.uk

Ok, we’ve got a root folder and one file — index.html (I’m using index.html, not any of the others; it is by all measures the standard file to use). The rest of the structure can be anything you want it to be.

I did some research at this point into how websites are generally structured. There are some vague conventions, nothing really definite, but I’ve adopted what I think is (fairly) good practice.

The root directory holds all the HTML files, every page on the website has its own HTML file that is essentially, that page (it may load other files, but the HTML file for that page is what the browser loads when it is directed to that page). The first file is the one we’ve already talked about: index.html.

I’ve chosen to organise the web pages into chapters and sections (the website is, if you remember, essentially a book). This page is in chapter 4, section 2 so its HTML page will start with 04-02 (all pages apart from index.html start like this, they are numbered cc-ss where cc is the chapter number and ss is the section number — both with leading zeros).

The number is followed by a short description (usually one word) that conveys the content of the chapter, in this case the word is “starting”. Thus this page has the full HTML file name:

04-02-starting.html

and it lives in the root directory along with index.html.

This website has a lot of pages and each one is numbered and named in this fashion.

For each of these pages, the HTML file holds the basic content of the page — this is the words (the text) that you see when you view the web page, but web pages also have other things that are peculiar to them: images, style sheets, JavaScripts &c. and most of these are in their own files. So now we need somewhere to keep all these other files.

All these files are stored in a separate folder, one for each web page. All of these individual page folders are stored within the folder:

01-pages

This itself is stored in the root folder (see Figure 4.6). Figure 4.7 shows a more detailed breakdown of the 04-02-starting folder:

The folder for each web page has the same name as the HTML file for that page (but without the extension).

• The index.html page also has a folder for its content (just like any other page). This folder is called 00-00-index (yes, I’ve given it a number just to keep everything in order)

On my machine, the path to the 04-02-starting folder would be:

z:/ps-publications/1001-website/01-pages/04-02-starting

There are four subfolders within each of the individual page folders. These are:

	Folder	Function
	01-local-css	This contains any cascading style sheet that is specific only to this page (as opposed to style sheets that are common across all pages), generally there are not many of these, usually only where a page runs a particular script that has an associated CSS file. If the page has no local CSS files, the folder will still exist, but will be empty.
	02-images	This contains all the images (with the exception of certain background images that are used by the common CSS files) that are used on the page. Generally, the images on a page are unique to that page. If the page has no images, the folder will still exist, but will be empty.
	04-data	This folder is used to hold data files containing page specific information (software examples, downloads, and any other information specific to the particular web page that doesn’t fall into the other categories).
	05-local-js	Every page has its own jQuery script file, this controls the slow scrolling to the various points on the page (figures, tables, sections &c.). These files are all unique; all are dependent on the configuration of the page.
	Table 4.1   Subfolders within the individual page folder for each web page

The website has two other storage areas; these both hold files that are common to all the web pages — a typical example being the CSS file that gives the common look and feel to each web page.

The first such folder is called 11-resources and this holds all the common files that have been developed (by me) for the website i.e. it is the stuff that I’ve written specifically for the web site.

The other folder is 21-global, this again contains common files for the website; the difference is I didn’t write the content; I got it from other people. This is things like fonts, jQuery plugins and certain CSS files; all of these things were written by other people and I’ve just used them under licence on the website.

Both these folders have similar structures (they hold similar things), examining each in turn, the 11-resources folder is shown in Figure 4.8. There are four subfolders within 11-resources.

These subfolders do the following:

	Folder	Function
		This contains the common CSS files available to all pages within the website. It also contains a subfolder (01-CSS-images) that holds any background images used within the CSS. The only image in it is the end-mark.svg file, the Yorkshire Rose, used to finish each web page:
	01-css	The CSS files are:
		style.css	This holds all the main heading, table, figure and body text styles for every web page
		grid.css	This contains the grid (column) styles used as the basic layout of every web page.
		prettify.css	This is the style sheet associated with the prettify jQuery plugin, it determines what colour is applied to the various elements of the code.
		This contains all the common images that are available for use on each web page, the only file currently in it is the flourish.svg image:
	02-images	It’s sometimes use to separate sections of text.
		This folder has a subfolder that contains all the “favicon” images, these are the small images the appear on the web browser tab and in bookmarks, they look like this:
	04-data	This folder is used to hold common data files (basically anything that’s not covered by the other folders); things like the zipped up copy of the website itself and some code examples .
	05-js	There is a common script file (script.js) that runs on every web page to implement the “sticky” navigation bar that appears at the top of the web page as you scroll down.
	Table 4.2   Subfolders and contents within the 11-resources folder

• The prettify.css file is associated with the Google Prettify jQuery plugin and as such you may think it should be under 21-global, the reason it’s not is that the Prettify plugin just adds some named styles to the code — I then wrote this style sheet so set those styles to something that resembles the Brackets method of colouring. So it’s a file I developed for this website and that is why it’s under resources and not global.

Next (and finally) the 21-global folder, this is shown in Figure 4.9.

There are three subfolders within 21-global.

	Folder	Function
		This contains the third-party CSS files, there are two:
	01-css	normalise.css	This sets various HTML element styles to make browsers render elements more consistently
		lightbox.css	Style sheet associated with the lightbox jQuery plugin, it configures annotation styles and shading
	03-fonts	This contains the style sheet that loads the fonts for the web pages. This is the ps-fonts.css file. It also has a subdirectory that holds the individual .woff files for each font installed.
	05-js	These are all the third party jQuery and JavaScript plugins that are needed for certain aspects of the website — hyphenation, displaying code fragment, a lightbox to display images and waypoints for enabling the “sticky” navigation bar
	Table 4.3   Subfolders and contents within the 21-global folder

There is a common numbering structure to the level 3 subfolders, and this is:

	Folder	Function
	01-css	Holds the CSS files and CSS background images
	02-images	Holds the images needed for the web page
	03-fonts	Holds the font CSS files and all the .woff files for each font
	04-data	Holds the downloadable files
	05-js	Holds the jQuery and JavaScript files
	Table 4.4   Common subfolder numbering

There is a lot to take in here, and it’s not necessary to understand it completely at this stage — basically, all I’ve done is put together some folders to keep thing in and I’ve tried to structure it in a logical way so that I can find things again when I need to.

As we start to build the web pages, it will become clearer and it’s fairly intuitive. I explain it all (even the inconsistences — where I’ve broken my own rules) as I go along.

Speaking of building web pages, let’s look at that next (it’s why we’re here after all).