4Getting started

Brack­ets is re­ally all we need to start build­ing and cod­ing the web­site, but be­fore we do this, we need some­where to keep the web­site i.e. a folder struc­ture that we can keep all the HTML, CSS, Java script and image files in.

This folder struc­ture is, in essence, the web­site. It is this folder struc­ture and its con­tents that will be even­tu­ally up­loaded to a server some­where and will then be viewed by the mil­lions of web users that have been wait­ing for just such a web­site.

A folder struc­ture is not a re­quire­ment, it is per­fectly pos­si­ble to just stick all the files in a sin­gle folder and the web­site will look and work just the same and the user would never know the dif­fer­ence. How­ever, im­pos­ing a folder struc­ture (par­tic­u­larly on a large web­site—which I think this is be­com­ing) leads to bet­ter or­gan­i­sa­tion—it’s gen­er­ally eas­ier to find things if there is an easy to fol­low struc­ture to the site (and then there is my struc­ture—just kid­ding).

This is broadly how I’ve struc­tured the web­site (Fig­ure 4.6):

Fig­ure 4.6   Basic folder struc­ture of the web­site

You’re prob­a­bly look­ing at it and think­ing “my God, he’s given every­thing a num­ber—what kind of anally re­ten­tive idiot is this?”—Well I’m an en­gi­neer. En­gi­neers like to num­ber things, it’s buried deep within us.

There are some con­ven­tions for nam­ing files and fold­ers on a web­site and these seem to be widely fol­lowed (within rea­son, you can al­ways find ex­cep­tions on the web). These con­ven­tions are:

1. Al­ways use lower case when nam­ing files and fold­ers

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

3. Only use the char­ac­ters [a-z], the num­bers [0-9] and the dash/hy­phen [-]

I think these con­ven­tions stem from the fact that a lot of web servers (the things that host the web­site) are based on UNIX; mean­ing that files and folder names are case sen­si­tive.

In Win­dows there is no dis­tinc­tion be­tween a file called Index.​HTML and one called index.​html (or in­deed one called InDeX.​hTmL or any com­bi­na­tion thereof). If you tried to copy Index.​html into a folder that con­tained index.​html it would re­place the lat­ter with the for­mer.

UNIX on the other hand would treat Index.​HTML and index.​html as two com­pletely sep­a­rate files and they could quite hap­pily co-exist in the same di­rec­tory.

So to avoid con­fu­sion all files and fold­ers are in low­er­case^†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 (en­coded) dif­fer­ently by dif­fer­ent web servers (even the Win­dows com­mand line doesn’t like spaces in file­names, these have to be sur­rounded by quotes). The best thing to do is avoid spaces in file and folder names.

Use the dash to re­place spaces i.e. 01-00-in­tro­duc­tion.html not 01 00 in­tro­duc­tion.html. It is per­fectly pos­si­ble to have un­der­scores in file names—but don’t—it’s bad prac­tice and there is some con­fu­sion (at least I was con­fused) when using it in host names (I’m not sure what a host name is, it’s dif­fer­ent to a do­main name, but I don’t know how).

Any­way, it’s dashes (hy­phens) in place of spaces.

The folder struc­ture starts with the root folder (again this is a UNIX term but is com­monly used in web de­vel­op­ment), this is just the top level di­rec­tory that lives some­where on your ma­chine and it holds all the con­tent of the web­site.

On my ma­chine it’s on a mapped NAS drive (net­work ac­ces­si­ble stor­age—es­sen­tially, a hard drive con­nected to my net­work); it has the fol­low­ing path on my ma­chine:

z:\ps-pub­li­ca­tions\1001-web­site\

The only file a web­site ac­tu­ally needs is one called: index.​html

This is the file loaded by de­fault if no spe­cific file is given in the URL.^†2 I.e. typ­ing www.practicalseries.com into a web browser will cause it to look for and load a file called index.​html at that ad­dress.

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 oth­ers; it is by all mea­sures the stan­dard file to use). The rest of the struc­ture can be any­thing you want it to be.

I did some re­search at this point into how web­sites are gen­er­ally struc­tured. There are some vague con­ven­tions, noth­ing re­ally def­i­nite, but I’ve adopted what I think is (fairly) good prac­tice.

The root di­rec­tory holds all the HTML files, every page on the web­site has its own HTML file that is es­sen­tially, that page (it may load other files, but the HTML file for that page is what the browser loads when it is di­rected to that page). The first file is the one we’ve al­ready talked about: index.​html.

I’ve cho­sen to or­gan­ise the web pages into chap­ters and sec­tions (the web­site is, if you re­mem­ber, es­sen­tially a book). This page is in chap­ter 4, sec­tion 2 so its HTML page will start with 04-02 (all pages apart from index.​html start like this, they are num­bered cc-ss where cc is the chap­ter num­ber and ss is the sec­tion num­ber—both with lead­ing zeros).

The num­ber is fol­lowed by a short de­scrip­tion (usu­ally one word) that con­veys the con­tent of the chap­ter, in this case the word is “start­ing”. Thus this page has the full HTML file name:

04-02-start­ing.html

and it lives in the root di­rec­tory along with index.​html.

This web­site has a lot of pages (Appendix xxx list them all), and each one is num­bered and named in this fash­ion.

For each of these pages, the HTML file holds the basic con­tent 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 pe­cu­liar to them: im­ages, style sheets, Java scripts &c. and most of these are in their own files. So now we need some­where to keep all these other files.

All these files are stored in a sep­a­rate folder, one for each web page. All of these in­di­vid­ual page fold­ers are stored under the

01-pages

folder, and this is stored in the root folder (see Fig­ure 4.6). Fig­ure 4.7 shows a more de­tailed break­down of the 04-02-start­ing folder:

Fig­ure 4.7   01-pages folder struc­ture

The folder for each web page has the same name as the HTML file for that page (but with­out the ex­ten­sion).

• 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 ma­chine, the path to the 04-02-start­ing folder would be:

z:\ps-pub­li­ca­tions\1001-web­site\01-pages\04-02-start­ing

There are four sub­fold­ers within each of the in­di­vid­ual page fold­ers. 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 peculiar 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.2   Subfolders within the individual page folder for each web page

The web­site has two other stor­age areas; these both hold files that are com­mon to all the web pages—a typ­i­cal ex­am­ple being the CSS file that gives the com­mon look and feel to each web page.

The first such folder is called 11-re­sources and this holds all the com­mon files that have been de­vel­oped (by me) for the web­site i.e. it is the stuff that I’ve writ­ten specif­i­cally for the web site.

The other folder is 21-global, this again con­tains com­mon files for the web­site; the dif­fer­ence is I didn’t write the con­tent; I got it from other peo­ple. This is things like fonts, jQuery plu­g­ins and cer­tain CSS files; all of these things were writ­ten by other peo­ple and I’ve just used them under li­cence on the web­site.

Both these fold­ers have sim­i­lar struc­tures (they hold sim­i­lar things), ex­am­in­ing each in turn, the 11-re­sources folder is shown in Fig­ure 4.8. There are four sub­fold­ers within 11-re­sources.

Fig­ure 4.8   11-re­sources folder struc­ture

These sub­fold­ers do the fol­low­ing:

	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 here 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 here 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); currently this is the pdf file of this document, 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.3   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 fi­nally) the 21-global folder, this is shown in Fig­ure 4.9.

Fig­ure 4.9   21-global folder struc­ture

There are three sub­fold­ers 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 Java script 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.4   Subfolders and contents within the 21-global folder

There is a com­mon num­ber­ing struc­ture to the level 3 sub­fold­ers, 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 Java script files
	Table 4.5   Common subfolder numbering

There is a lot to take in here, and it’s not nec­es­sary to un­der­stand it com­pletely at this stage—ba­si­cally, all I’ve done is put to­gether some fold­ers to keep thing in and I’ve tried to struc­ture it in a log­i­cal way so that I can find things again when I need to.

As we start to build the web pages, it will be­come clearer and it’s fairly in­tu­itive. I ex­plain it all (even the in­con­sis­tences—where I’ve bro­ken my own rules) as I go along.

Speak­ing of build­ing web pages, let’s look at that next (it’s why we’re here after all).