Ant Smith

Technology

My Website Framework - Part 1: Fundamentals and Content Management

In april 2019 I 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.

    Now (in September 2020) I've over-hauled all of the software with the following aims:

  • Improve consistency in the presentation of long-form articles

  • Improve, simplify and clean underlying code (especially CSS)

  • Improve the 'mobile friendliness'

  • Improve Search Engine Optimisation

  • Make more use of images

  • Simplify the re-use of the framework

  • Improve integration with Facebook

I'm still very happy to share this work so here I'm going to explain how it all hangs togther; but first some more details about the latest changes…

I found long-form articles were including a lot of HTML, especially for lists and tables; creating this HTML over the course of years in different articles led to very different styling from article to article. So I wanted to created a standard format for lists and tables, that would also be easier to type than HTML - and which consequently would have common styling and features. Also, it wasn't possible to get embedded images to behave in the same way as framework native images - ie. that they should 'dim' on roll-over and expand to full screen on click.

    As I answered these problems a few other 'standard macros' occurred to me as well, namely:

  • Quotations, with linkable citations

  • Call-outs, or content with a title, image and description all boxed together in a floating element

  • Choruses, for poems, so they can be expanded or compressed (click on the chorus in Anxiety to see how this works)

  • Groups, indented and styled slightly differently to the main article flow

  • Literals, for displaying text as typed, even if it contains special (HTML) characters.

  • Audio Players, for creating a playlist of a set of audio files

Full details on the text-processor macros are now available in the 3rd article in this series: /articles/my-website-framework-3, but suffice it to say the framework now has a powerful text-processor should you want to use it; although raw HTML also continues to work fine.

The underlying code is now much simpler (although there is more to do in the photo section) and as a result also much faster.

The framework can now provide mobile icons, so the website looks better when presented as an icon, and Google now reports all pages as 'mobile friendly' - which is important to avoid Google down-grading the value of the pages in the website. Also all images now use the SRCSET functionality so a device never needs to fetch an image bigger than it can actually display, which really helps with page speed and limiting data bandwidth use.

I've also created a slideshow type display for photo galleries which provides swipe behaviour on mobiles. Future plans are to do something similar for text pages and to make these displays the default. At the moment you have to specifically select the slideshow, this is because they can be very big and so slow to load (and data hungry) - but next year I'll probably overcome those hurdles - watch this space I guess.

All pages on the website can now be given individual keywords, to help in getting them returned by searches. The entire site now also has every page included within 'sitemaps' - which greatly improves the coverage of the site in search engine indexes. I've removed the default 'every page requires parental guidance' so that pages get returned in general search results - to achieve this I've added a PGCheck which will mark a page as requiring parental guidance if the item's name (or its main image name) ends in '-nsfw'.

Now that images are more effiecient I make more use of them. Old text lists of related content (within a tag say) are now presented graphically, using the content's related image. I think it looks lovely, actually.

Also, you can now simply specify an accent colour for any site section in the section configuration - there's no need to fully understand the CSS structure and add all that livery type information in the domain.css file. You can still use the domain.css file for very specific local styling - in fact the name of the page's item is included in the <main> tag of every page, so individual items can be easilly targetted by styling rules - if you need that.

Finally, the Facebook integration needed a complete overhaul, so I did that too. If you want technical details my article on integrating Facebook is worth a skeg.

Much of this will become clearer as you read through the updated framework articles (below)... but hey, look, if you do find yourself using this framework (in whole or in part, or just as a reference) then PLEASE DO consider making a DONATION. There's a secure PayPal DONATE button in the footer of every single page - if you're looking for it...

The Framework

    There are 5 levels that need to be understood to take this software and re-use it:

  • Mechanics of the website, how it works for visitors

  • Creating the content for the pages

  • 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 (the mechanics) 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.

In terms of creating the content, take a look at the upcoming article - which I will link here when it's ready.

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 HTML-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++. I save the text files in UTF-8.

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).

    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'. (promo page list files, footer promo text files and keyword list files 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)

  • There is a range of macros that can be used in text files that provision complex HTML structures in a regular way

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.

Discoverability (and adult ratings)

There are three major changes in the framework (2020) that support enhanced discoverability.

Firstly, the framework no longer defaults to rating every page as adult. This broadens the audience but increases the publisher's dilligence. Works that contain '-nsfw' at the end of their filename will cause any associated pages to be ranked as adult.

Aggregation pages default to non-explicit, even if they happen to include content that is marked nsfw. It is assumed that one would need to see the entire content in order to be potentially offended. Adult images are always concealed by default on aggregation pages so there is only the concern that titles or early parts of the associated text may be offensive on an aggregation page. There is further work planned in this area.

Individual items (not photos) can be flagged as adult material by adding PG inside the associated keywords file.

In fact the second change to support discoverability is the addition of keyword files for items, so each page on the website can be precisely keyworded.

The third major change to aid discoverability is the addition of Site Maps, which list every URL withn the site. An index of sitemaps can be seen at /sitemap.xml

You will see here that each section of the site has its own sitemap, accessed via '/[section]/sitemap.xml - eg. /articles/sitemap.xml

Sitemaps are created dynamically when needed, but it takes a lot of time to make them (upto a minute depending on how much content you have in a site section). For this reason they are 'cached' in a directory called sitemaps at the root of the webserver. Once changes to a section are complete, the sections sitemap should be deleted from this directory and re-created by visiting the section's sitemap URL. Otherwise the cached sitemaps will become stale and search engines will find it harder to discover new content.

I may add automatic updates of sitemaps as a future enhancement - buut I'm going to need a chron scheduler on my server to do that - which I might get when I release the https version of the framework, since then I'll be on better servers...

    Summary

  • Name files carefully, using lowercase characters, digits and hyphens only

  • Only use, .txt, .jpg, .mp3 and .mp4 files (and just the one .csv)

  • compress Images, Audio and Video

  • Use '-nsfw.jpg' for sensitive images, or '-nsfw.txt' for sensitive text content

  • Most text files start with a title

  • You can use HTML, and also special macros, inside text files

  • Make small changes at a time

  • keep a copy of the original file before making changes

  • Try to remember to update your sitemaps from time to time

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.

    Item sections also have 'aggregate' pages:

  • A top level page that lists all of the tags, collections and items within the section.

  • A '/tags' page that lists all of the items of all of the tags within the section

  • A '/tags/' page that lists all of the items of a tag in the section

  • A '/collections' page that lists all of the collections within the section

  • A '/collections/' page that lists all of the items of a collection in the section

Photo Gallery sections are designed for an image-led experience. You can add background text (similar to 'author's notes') and audio descriptions (similar to audio versions of items).

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.

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.

    They contain:

  • A main link (the panel title) - to the section of the promoted item

  • A secondary link (inside the panel) - to the promoted item itself.

  • Truncated text of the item

  • The image associated with the item

NB. The associated image can be supressed for any given section - if, for example, the content is meant to be textually immersive as with stories and articles.

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:

screenshot showing relationship between text files and page components

    The Buy section of the website is a Promo type section and it uses the content directory 'products2017'.

  1. The promo-list file defines the type and order of each promo panel

  2. The first promo is a static promo and uses 'promo1.txt'

  3. promo1.txt contains the info for the panel

  4. 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)

  5. The third line of the text file is a sub-title, this time there is no additional link so the forth line is blank.

  6. The rest of the file is a block of text for the promo.

  7. The related file promo1.jpg is placed in the panel, because it has the same base name as the static promo text file

  8. 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)

Oh, you can also place a hash character ('#') at the start of a line in the promo-list.txt file to supress a promo panel. This is useful if you want to temporarilly promote something else, knowing that the original panel will be reinstated at a later time.

    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: keywords

  • 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. You can also use the text-processor macros in these files.

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.

These author's notes files (as of 2020) start with a title to use in the panel on the page. This title was fixed as "Author's Notes" but that was too restrictive.

Also as of 2020, you can now save text files (of the same name as the main item) in the keywords directory. These files just list the keywords associated with the item, which are then added into the document head to help dumb 21st. century search engines understand the content. Note that the section name (eg. poetry) and the associated tag's name (if any, eg. Mental Health) will be added to the item's keywords automatically. If any of the provided keywords contain PG or Parental Guidance then the item's webpage will be rated adult.

Keyword files do not start with a title.

    There are 2 more sections available to you on a rich item page:

  • Other items in this collection or tag

  • In which other collections or tags this item can be found.

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

example of an item page.

Tags are an arbitary collection of items. Create a tag by saving a text file into the tags directory, where the filename is the name of the tag and the first line of the file is the tag's title (or display name). Each subsequent line is the name of an item (in this section) that belongs to the tag. Items can be listed in multiple files (i.e. belong to several tags) if you like. It doesn't matter what order you add items to a tag, lists of tagged items are always displayed in alphabetical order of the item's titles.

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.

Here's an example tag file (seasons.txt) for my seasonal poems:

Seasons
autumnal
in-the-summer
sing-to-me
spring
winter
winter-poem

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 collection's 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, as are the new text-processor macros).

Note that the works in a collection are displayed in the order defined by the file - they are not automatically alphabetised, as that would ruin the flow of the collection!

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

    Item: Summary
  • The main text of a rich item lives in a text file in the appropriate content directory

  • Additional information about the item can be stored in text files in the authorsnotes sub-directory, linked by filename - with a suitable title for the notes as the first line.

  • The image sub-directory contains associated illustrating images, linked by filename

  • The keywords sub-directory contains a text file (linked by filename) that lists the item's keywords

  • The media sub-directory contains associated audio and video files, linked by filename

    • 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

    • 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 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.

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. There is also an image file (linked by name) for each gallery (sub-directory) which 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.

And as of now (2020) you can also drop mp3 'audio descriptions' into a collection directory - using the same base filename as the image it describes.

Pages displaying images marked as nsfw (filename ends in '-nsfw.jpg') will be rated as adult in the page .

There's no way (yet) to add keywords to specific images.

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

    • an associated image for the gallery.

    • The collections sub-directories contain

    • the jpgs of the images in the collection

      • texts files for each image containing

      • a title for the image on the first line

      • a description for the image, if that is required

    • mp3 files for each image's audio description

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]

Technology