Ant Smith
donate to Ant Smith Print

Articles

My Website Framework - Part 1: Fundamentals and Content Management

I have just (april 2019) refactored all the software that creates the pages on this website so that the framework could be reproduced and used to create a new site (for a friend), which makes this website's framework readilly re-usable. I'm very happy to share this work so here I'm going to explain how it all hangs togther. There are 4 levels that need to be understood to take this software and re-use it:
  • Mechanics of the website, how it works for visitors
  • Managing the content of a site based on this framework
  • Generating the structure and look-and-feel of a the site based on this framework
  • Fundamentally changing or enhancing how the framework works

I really should go to the trouble of describing how the site works and all of its features, but you can discover that for yourself and frankly life is too short and these articles are already too long. Take a good look around antsmith.net before trying to make sense of what's presented here.

I'm not going to cover the last of these either; if you know enough about PHP programming to follow a discussion on rewriting the framework then you probably don't need it in the first place - plus it's all been written in a very 3GL way, since well, that's just how old I actually am!

I'll look first at how to manage content on a website powered by this framework. It may seem more logical to start with how you create the basic shape of a website, but that's a little more complex and things will probably make more sense if you understand the content management to begin with.

Some Fundamentals

Website as Publication

Okay, bear with me - this might be a little 'philosophical', but is I think important.

A website isn't just a loose collection of 'stuff' - in the same way that an album isn't just a collection of songs; a gallery doesn't just hang a bunch of pictures; an anthology isn't just a jumble of poems... all of these things have an element of curation or editorialisation. The presentation of the works together should make the whole more than the sum of the parts.

So far, the internet has done a decent job of democratising the publication of (and access to) knowledge. By sidestepping the political bias, commercial imperative, and intellectual elitism of publishing houses and record labels we can all of us (albeit within the strictures of the laws of our locality) publish just what the hell we like - Fucking Aces.

The barriers to entry thrown up by these conservative and capitalist organisations may well be primarilly intended as controlling forces of opression and exploitation, BUT they have/had a side-effect of also ensuring quality. All those extra beady-eyes would make damn sure that the published work was rich, something more than just the simple building blocks.

As self-publishers (owners of a website) we need to be responsible to the work. The key to that is to recognise there is a distinction between the work and the representation of the work.If you have a poem (or whatever) worth sharing then don't simply think of it as typographic marks on a page; poems (or whatever) are social constructs to which, one way or another, we give concrete form (I mean, not all poems even use words). The representation has two key components: The media (text, audio, imagery, video) and the context (what comes before, and after).

The upshot is, we don't just publish content to a website as though it were some scrapbook, but rather we use the content to help create bigger stories. An item, pretty much, cannot justify self-publication in itself - it has to add something to those bigger stories of the site.

On a practical level, that means a published item must be not just published but ideally also: well tagged, further discussed, illustrated, contributing to the AV etc...

The framework is designed to make it as easy as possible to publish an impression of a work, but also provides lots of opportunity to fully dress that impression so that the work, the ephemeral social construct, can make most, concrete, sense.

Okay, so it's understood, publication isn't just a technical task, it is a part of the artist/author's creative process. So let's get practical.

Files

The framework is file based. By sticking a text file in the right place you get to have a whole new page on the website. If you stick a JPG image file of the same name into another place then that page will have an image on it as well. This is super simple, but because of how computers work there are somethings to be cautious of. So here's some simple rules/guidelines for naming the files that contain your content:
  • do not use uppercase letters content is related by file name, you can have a page with a text file poem, a jpg illustrating image, an audio recording out of the studio and a video recording from a live performance if you like. These will all turn up together on the same page IF AND ONLY IF the filenames used match exactly. If you rigourously only use lower case you will get way fewer puzzling moments wondering why the Blue-PIlls.mp3 isn't available on the Blue-Pills page.
  • Feel free to also use digits (0-9) and hyphens (-) but do not use anything else whatsoever. Eg. No brackets, hashes, commercial-at characters etc... ((#@). Other characters will go wrong oneway or another at some point.
  • Do use hyphens a filename like 'buy-freedom.txt' is better than 'buyfreedom.txt'. Filenames will often appear in the page URL (or address) and search engines will readilly consider a hyphen to be synonimous with a space and that helps them to understand the words that are being employed
  • Check Your Extensions they should be lowercase too, so always '.jpg' for an image (for example) never '.JPG'

The framework allows you to put words, pictures, audio and video onto your website. To keep things simple (i.e. to make sure as many people as possible have the technology needed to receive the content) the framework only uses HTML4-friendly file types. So...

Videos must be in '.mp4' format.
Audios must be in '.mp3' format.
You might want to invest in some desktop media conversion utility to help here - which is a good idea anyway as such tools will typically also let you compress such files to something efficient for web delivery. It's a really expensive waste of bandwidth to have large video files on a website. 3 minutes of mp4 shouldn't really be even as big as 20MB.

Images must be jpegs ('.jpg') and again should be reasonably sized. Most people will use HD Monitors on the desktop (1920x1080px) or much smaller screen resolutions on tablet or mobile. So it's a little pointless paying to store high-resolution digital images on your web servers. The framework will downscale images for presentation anyway. In photo galleries I tend to standardise on images of 2048px square maximum and I use 1024px square images elsewhere on the site. Also note, your webserver has limited memory (typically 128Mb) available to the framework (and its PHP scripts) and so there's a good chance that larger image files will just cause the page to fall over in a crumpled heap. I save images with harsh jpg compression so most images are <250kb (they go up to 500kb on occassion).

Some images might be 'not suitable for work'. If the filename ends with '-nsfw.jpg' instead of '.jpg' these will be handled specially. They will still match with other ('.txt') filenames but they will be displayed masked out, requiring a mouse-click (or tap) to reveal the image. NSFW images will not appear in social media sites when pages are shared. This is all about being good web citizens and never suprising anyone with nudity (I also use NSFW for horrific images, not just nudity). NB. NSFW masking is not employed in the single image view in a photo gallery's collection as the visitor can only have arrived there by having already seen the warning. For an example of NSFW masking see this image from my Project 269 work:


Words are stored in simple text files ('.txt'). I create these using Windows' Notepad++. If you try and use MSWord you'll end-up with all kinds of horrible characters on your pages as MSWord helpfully automatically converts simple hyphens into things like en-dashes or em-dashes. I save the text files in UTF-8. It's possible I could sort this out one day so that saving from MSWord is trouble free but the text files are so very simple (and typically small) it just hasn't been worth my trouble as yet...

The framework can also handle '.html' files when it's looking for an item's main text file. This really is just for convenience when content has been saved from an existing webpage (maybe from an old blog). Aside from the file extension both are treated equally.

What goes inside the text file depends on what the file is used for. This will be described for each use of text files later (managing the content) but do note that:
  • Mostly, the very first line in the file is the Display Name or Title. This ensures we can have well formed titles (with apostrophes and the like) and don't just use the file name as a 'kind of good enough title'. (authorsnotes and gallery textfiles do not contain titles)
  • Even though they are just text files you can use HTML inside of them, which makes them very flexible indeed (take a look at Weird Scenes EP as an example of what can be achieved)

Changes

The simplicity and flexibility of the framework means that you have to take good care. If you get mis-matches in your filenames, content you expect won't appear (nor will it if you put the file in the wrong place). Ill-formed HTML inside of text files will utterly screw a page up. So take care. Taking care means, make small changes - don't do everything at once. Do a little bit and upload it to see if it's working how you expect. If you're updating an existing file, get into the habit of making a copy of it first, so that if you do screw things up you can at least revert to where you were at.

If you're just working on one file the simplest approach is to rename it on the webserver before uploading the modified version. Then when you know the modified version is good, delete the renamed version on the webserver.

If the modified version is all screwey, delete the webserver and local modified versions. THEN restore the name of the original file on the webserver and download it again. If you're working on a bunch of files, just take a local copy of the entire directory before you start, so you can recover the original versions of any files in the directory if you need to while working. Ultimately you'll find that you're swapping between three different locations all that have similar files in them:
  • The live, published, files on the web server
  • The master files on your local machine
  • Copies of the master files in-case you need to revert

It's super easy to get confused, which is why there are lots of website builders out there that manage all this for you - but they have their own complexities and costs. This whole framework is about simplicity, portability, flexibility and cost - the down side is you need to be careful and vigilant regards exactly what you're doing.

Summary

  • Name files carefully, using lowercase characters, digits and hyphens only
  • Only use, .txt, .html, .jpg, .mp3 and .mp4 files (and just the one .csv)
  • compress Images, Audio and Video
  • Use '-nsfw.jpg' for sensitive images
  • Most text files start with a title
  • You can use HTML inside text files
  • Make small changes at a time
  • keep a copy of the original file before making changes

Managing the Content

In my website site there are 10 different sections (10 items in the site menu bar). Even though the content in each section is quite distinct (stories are fundamentally different to poems!) sometimes they have remarkably similar properties. Whilst poems and stories may well be distinct content they are concretely represented in very similar ways, both are primarilly presented as words on a page possibly with illustrating images, audio and video. So whilst the template site has 10 distinct sections, there only 4 different kinds of presentation:
  • Highlights or Promos
  • Rich Items
  • Photo Galleries
  • Special one-offs

Promo sections each create a single page on the website which contains a bunch of panels with headings,links,words and pictures etc. The home page, BUY page and Projects page are all of this type and if you compare them you'll see the similarities.

Rich Item sections create an overview page from where each item can be accessed on a page of its own, so you can end up with plenty of pages inside a rich item section. In my website the rich Item sections are Poetry, Stories, Articles, Audio and Video; all very different content but if you compare them the presentational similarities will be very clear.

Photo Gallery sections are designed for an image-led experience. There's very little in the way of added text and no audio or video content associated with photos.

Special sections are just that, special pages, one-offs. They're handcoded on an as needed basis and as such aren't further considered here. The Memes section is a one-off and if you want to create your own one-offs, there's an example a least.

It's possible the framework will develop with more section types, but for now in order to manage the content on a website powered by this framework you only need to understand Promos, Rich Items and Photo Galleries.

Each section of the website, irrespective of the type of the section, has a directory at the root of the site where the content lives. So the poetry section of the template site gets its content from the /poems2 directory at the root of the webserver (we'll see later how the poetry section knows where it's content lives). The Stories section looks into the '/stories2017' directory, etc...

How the content is stored inside the directory for a section of the website depends on the type of the section, so I'll explain here how that works for each type of section:

Promo Content

Promo sections are a single page with a bunch of panels on them.

The content directory will contain one text file called promo-list.txt - there is no title in this file, each line defines (in turn) the promo panels that appear on the page.

A line in this file can be simply a local address of a promotable item, e.g.

So most things just need a local URL in the promo-list file for a promo to be created. You can't create section promos (e.g. just 'poetry' as the URL) because sections don't have any media or descriptions of their own from which to automatically create a promotion. Similarly you can't create automatic promotions for 'promo' type sections of the website nor for 'bespoke' type sections.

BUT you can create manual (static) promotions to anything you like.

Static promotions are defined in additional text files in the Promo section's content directory (with an associated jpg, mp3 or mp4 if you like). We'll see what those manual promotion text files look like in a minute. Once you've made a manual promotion you reference it in the promo-list file by including it's name and it's styling - e.g.
promo1 products

Where 'promo1.txt' is the manual promo text file and 'products' is the styling to be used (more on styling in a minute).

Promo pages can also display your twitter feed. Just include a line with the word 'twitter' in the promo-list file.

You can also place a message on a promo page underneath all the promos. Add a line to the promo-list file that starts with the word 'footer' and which then references a text file you have placed in the content directory. E.g.
footer promo-footer

Where promo-footer.txt is a simple text file containing the footer message.

Here's a full example promo-list file:
poetry/another-world/tag/mental-health
photography/art/architecture/peter-jones-department-store-01
articles/mirror-tessellation-photography-by-example
stories/rescue-dog
video/plaything
audio/weird-scenes
promo1 projects
promo2 memes
promo3 products
twitter
footer promo-footer

you can see that there will be 11 promo sections on a promo page using this promo-list file (there's 11 lines in the file):
  • A poem in a tag context
  • A specific image from a gallery's collection
  • A story, a video and an audio item
  • 3 static promos in different styles
  • A twitter feed
  • and a footer message

The 3 promos are using 3 different styles called 'projects' (purple), 'memes' (brown) and 'products' (cyan).

There are 10 styles that have been pre-defined thus (these definitions can be changed, and more styles can be created):
  • poetry : Deep Red
  • photography: Orange
  • projects: Purple
  • stories: Green
  • memes: Brown
  • articles:Blue
  • video: Pink
  • audio: Yellow
  • products: Cyan
  • home: Grey

The automatic promos (from local URLS in the promo-list file) take their styling from the section that they link to.

We create as many panels as we like, in a defined order and with a given styling (trim colour). We can have more than one static promo in each style if we like, and we can have as many automatic promos as we want.

As discussed, the content of static promo panels comes from what we put inside the text file that the promo-list references (plus any associated jpg, mp3 or mp4 we store in the content directory). I.e. if we want to include an image in the promo2 panel we defined above (in the example promo-list file) we save a jpg into the same directory called promo2.jpg.

Aside from an image, audio or a video (or none!) all static promo panels include:
  • A main title
  • A link for the main title
  • A sub-title
  • A link for the sub-title
  • Some text

Only the Main Title is required. Everything else is optional.

And this is exactly, line by line, what goes into a static promo file.

Links in a static promo can be local, so if you're promoting 'http://www.antsmith.net/poetry' in the www.antsmith.net website you only need write 'poetry'.
If you use local links, then when you click them the target page will open in the same browser tab.
Remote links (that start something like http://www...) will open in a new tab.

This picture illustrates how it all hangs together for the first promo panel on the 'Buy' (products) page of www.antsmith.net:
  • 1. The Buy section of the website is a Promo type section and it uses the content directory 'products2017'.
  • 2. The promo-list file defines the type and order of each promo panel
  • 3. The first promo is a static promo and uses 'promo1.txt'
  • 4. promo1.txt contains the info for the panel
  • 5. The first line of the text file is the main panel title, and the second line defines an off-site link for this promo (in this example)
  • 6. The third line of the text file is a sub-title, this time there is no additional link so the forth line is blank.
  • 7. The rest of the file is a block of text for the promo.
  • 8. The related file promo1.jpg is placed in the panel, because it has the same base name as the static promo text file
  • 9. Notice how the automatic promotion of the poetry collection 'Dark Matter' is also included (this one line in promo-list creates that entire panel with no need for an additional static promo file)

Promo: Summary
  • Promo type website sections are a single page with a collection of promo panels
  • The panels are defined in order, line-by-line, in the promo-list file in the website section's content directory
  • Promos can be created automatically by providing a local link to an item (with or without a tag or collection context) OR
  • a local link to a tag or collection context (i.e. without an item context) OR
  • a local link to a photo type section's Galleries, Collections or Images
  • A twitter feed panel can be created by specifying 'twitter' on a line in the promo-list file
  • A footer message can be created by adding 'footer [footer text filename]' to the promo-list file, with the message held in the referenced file.
  • A static promo can be created by adding '[promo file name] [style]' to the promo-list file
  • There are 10 predefined styles.
  • A static promo file contains a title on the first line and then optionally:
  • Text Line 2: Title link
  • Text Line 3: Sub-title
  • Text Line 4: Sub-title link
  • Remainder: Text in the promo
  • A static promo can include an image, audio or video media by including an appropriate file in the content directory of the same base name as the static promo text file.

Rich Item Content

The content directory for a Rich Item type of website section contains the following items:
  • Directory: authorsnotes
  • Directory: collections
  • Directory: images
  • Directory: media
  • Directory: tags
  • text files: one for each rich item that appears in the section

Clearly, these textfiles in the root of the content directory are where you put the text of the rich item you are presenting, be that a poem, a story, an article or anything else. Don't forget that audio and video items can be handled just like rich text items. You don't really just want to slap an audio player on a page, you definitely want to give it a bit of a description or background context too so that people feel impelled to actually play it. The same is true of video, but because video can show a frame (in a way that audio cannot) the need to give a text description of what is being published may feel less natural; but it isn't.

The first line in each of these files is the true and full well formed title of the item. The rest of the file is the text of the item: the lines in a poem, the words in a story, maybe the transcript of an audio track, or perhaps the production credits of a video. Or in fact any text you like, including HTML. This is the main body of text for the item that appears on the page.

If there's an illustrating image (and there should be, it really helps when sharing your webpages on social media) then they get stored in the images sub-directory with, as you might expect, the same basic file name as the main text file for the item.

Any audio or video that represents (or further illustrates) the rich item gets stored in the media sub-directory.

You'll see from the illustrative screenshot below that you can also add 'Author's Notes'. This is intended for background or biographic (or other) information about the work. It is unlikely you'll need these where the work is primarilly represented by an audio or video file (i.e. in an Audio or Video specific website section) since you'll already have used the main text file for that purpose. But when the work is primarilly represented by the main text file (as you would with a poem or story) then here is the opportunity to provide those richer insights.

There are 2 more sections available to you on a rich item page:
  • Collection Details
  • In what other contexts you can find this item

You can see them lower down on the right hand side of the page.

Collections group works together just like tags do, but there are some important differences. You can think of a collection as being similar to a published anthology (or perhaps a musical album). They are highly curated and typically of their time. A finite and definite set of works are collated in a specific order. There's usually some further description of the collection (over and above any author's notes about individual works) as in a preface or forward for a published work, or sleeve/jacket notes for a musical album. Collections also typically have their own imagery (book cover or album artwork). Collections are very rich. They don't have to be online representations of real world productions, but it is easiest to understand them in that way.

The collections sub-directory will contain one text file and one image file for each collection of materials in the associated website section. There can be as many collections as you like.

Here's an example text file defining a collection:
Dark Matter

https://www.facebook.com/pg/The-Black-Light-Engine-Room-Press-1381073815549642/about
night-terror
misplaced
spring
if-i-could-bleed-the-blue-from-out-of-the-sky
surviving-or-thriving
winter
jumbled
the-disappeared
###
Dark Matter is a series of chapbooks from The Black Light Engine Room press. Each book in the series features 2 poets and aims to give more space to feature their work following on from contributions to the Black Light Engine Room magazine.

Volume 9 features Ant with Kirsten Luckins, (both represented by Apples and Snakes) and in this collection Ant has presented a series of works more aimed at the page than the stage to provide a new insight into his work.

As you might expect, the first line is the full title of the collection.

If the collection is available to buy as a physical product or download, the next line will have a link to the online shop where it can be bought.
If the product is made in collaboration with others (maybe a publishing house) then the third line can have a link to their web presence.
If either of these links are given then you will see Buy or Find Out More buttons on the item page (Buy always takes precedence if both links are given).

Following these links (i.e. from line 4 in the collection text file) there is a list of the works (filenames) that are in the collection, in the appropriate order. The framework doesn't know how long this list will be so once all works have been listed we whack a line into the file just containing '###' as an end of list marker. Everything else that then follows in the file is treated as the text description of the collection (and as ever HTML is allowed).

Collections then are a little bit of work, but they really are worth it!

The framework will also group items by 'tag'. Unlike collections Tags are a little unruly. New works get added to them all the time, you can never really be certain how many works will end up being in a tag (well, until you die and stop tagging new works anyway). So we let them be just that, uncertain vague concepts that group 'stuff' together. They have no imagery or description associated with them. A tag is just a group of items that share 'something' in common. They are defined by creating a text file in the tag sub-directory of the content directory. As ever, the first line is the proper display form of the tag (with capitals and spaces etc) followed by a list of the items that are in the tag (we don't need an end of list marker this time, as there is nothing else to follow in the file). You should aim to ensure tag files order their referenced poems alphabetically; the framework will not do that for you.

Here's an example tag file (seasons.txt) for my seasonal poems:
Seasons
autumnal
in-the-summer
sing-to-me
spring
winter
winter-poem

Item: Summary
  • The main text of a rich item lives in a text file in the appropriate content directory
  • The image sub-directory contains associated illustrating images, linked by filename
  • The media sub-directory contains associated audio and video files, linked by filename
  • Additional information about the item can be stored in text files in the authorsnotes sub-directory, linked by filename
  • Items can be curated into collections
  • Collections are defined by a collection text file in the collections sub-directory
  • Collections can be illustrated with an image, stored in the collections sub-directory and linked to the text definition by filename
  • The collection text file starts with the collection title
  • The next 2 lines provide off-site links for buying the collection or visiting the collaborating producer
  • Each item in the collection is then listed line by line
  • The list of items is terminated by '###'
  • The rest of the file provides the collection's description.
  • Items can be grouped into tags
  • Tags are defined by a text file in the tags sub-directory
  • The first line in a tag text file is the display name of the tag
  • The rest of the tag file is a list of items in the tag
  • The list of items should be ordered so that the items are navigated alphabetically

Photo Content

You'll be glad to know, I'm sure, that managing the content of Photo Galleries is much more straight forward than what we have looked at so far... This is partly because of the nature of engaging photographs; their whole purpose is to tell an immersive story themselves without any of the additional illustrations that words sometimes demand.

In this framework a photographic section is split into 'Galleries' - just as the nation's cultural archive of images are divided between places like The National Gallery, The Tate etc. Each gallery then comprises a series of collections, again just as a real Gallery organises itself (eg. Room 19 in the National is their Land and Water collection). Actual images can be viewed once you've gone to the right collection of the right gallery.

This organisation (images inside of a gallery's collections) works much better for large sets of images than other choices. Arranging images by 'Title' or 'Tag' requires a commonly understood lexicon - but photographs don't use language (they use imagery!) so those approaches are never wholly consisitent, complete nor coherent...

A photo type content section therefore contains a (master) 'galleries' sub-directory. Inside this there is one additional sub-directory for each gallery and a text file that describes what the gallery specialises in. The text file and sub-directory are linked by name (so there is the 'art' subdirectory decribed by the 'art.txt' text file). There is also an image file (again linked by name) which is typically a copy of some image in the gallery, which illustrates the gallery's intent.

The gallery sub-directory is super simple. It just has one further sub-directory for each collection in the gallery.

The collection sub-directory is also super simple. It just has the image files of the photographs in the collection. As of now (april 2019) you can also drop text files in here (linked to a given image by filename). If you do so then the first line of the text file will be used as the image title and the rest of the file will turn up as a description to the right of the image on the single image page.

There's one further piece of content management for photo galleries. In the base content directory (where the 'galleries' sub-directory lives) there is a 'data' sub-directory. In there you can save a textfile called buy-links.csv. The first line must contain:
name,link

Each successive line can than contain a pair of image filename & purchase link:
acton-town,https://www.redbubble.com/people/antsmith/works/14749947-acton-town-tube-station
aldgate,https://www.redbubble.com/people/antsmith/works/14750017-aldgate-tube-station

The image filename doesn't need the extension ('.jpg').

The framework will then display a 'Buy' button on any page where the image is also available to buy.

If you are unfortunate enough to use the same filename for different images in different collections/galleries you will find that they both display the same Buy link. Try to avoid reusing filenames. The best way to do that is to give each image the best, most meaningful, filename you can manage... While we can mostly provide good quality titles in various textfiles, the actual filenames do turn up in the URLs (the addresses) of the pages because URLS (like files) have trouble with special characters. Dont be dismissive of filesnames because of their limitations.

Photo: Summary
  • The content directory contains one 'data' and one 'galleries' sub-directory
  • The data sub-directory contains one-file called buy-links.csv which allows images to be linked through to online shops.
  • The galleries sub-directory contains one further sub-directory for each collection in the gallery
  • The galleries sub-directory also contains an associated image and textfile description of the gallery.
  • The collections sub-directories contain the jpgs of the images in the collection
  • The collections sub-directories may also contain texts files for each image
  • These text files contain a title for the image on the first line
  • The rest of the text file contains a description for the image, if that is required...


That's everything there is to managing this framework's content. It's now necessary to think about how such content can be best structured in a website. Eg. Should poems and stories be seperate sections or not? How should photos be grouped? What are the different promo type pages needed? How should all of it look???

Keep reading to find the framework download link... [Next Article]

Articles