Ant Smith

Technology

My Website Framework - Part 3: Text File Macros

The Framework creates content from several text files for: items (poems, stories, articles etc); collections of items; promotions of other content; and photographs.

There are two (content) files for items, the base file and then any additional author's notes. (In fact, there are many more possibilities if you implement richer pages, see my next article)

Collections use a single file - begining with a list of the items in the collection (terminated with '@@@') followed by a text description of the collection.

Promos can have a text file that firstly lists title and links, but then provides a full text description.

Photographs can have an associated text file that gives background information about the image.

All of this descriptive text (in any of these files) can be: simple plain text; HTML; or one or more of the 'macros' described here.

The purpose of these 'macros' is two-fold:

  • They ensure consistency in how content is displayed

  • They provide additional, sometimes powerful certainly complex, features

The full list of macros (currently) available is:

  • List macros:

    • ul-outline

    • ol-outline

    • ol-outline-numeric

    • ul-inline

    • ol-inline

    • ol-inline-numeric

  • image macros:

    • img

    • img-left

    • img-right

  • Callout macros:

    • callout

    • callout-left

    • callout-right

  • Grouping macros:

    • group

    • group-centre

  • Literal macros:

    • literal

    • literal-wrap

  • Other macros:

    • quote macro

    • table macro

    • chorus macro

    • audio-player

    • video-player

    • accordion

    • gallery-<name>

Examples

Lists

An unordered outline list

  • you can see has bullets

  • is displayed inside a white box

  • which has a black border

An ordered outline list

  1. Has alpha enumerators

  2. instead of bullets

  3. in the same boxed style display

A numeric ordered outline list

  1. Has numeric enumerators

  2. instead of apha enumerators

  3. but with the same boxed style

Inline lists

  • work just like outline lists

  • but do not have the boxed styling

  • They can be ordered or unordered (using enumerators or bullets)

  • and the enumerators can be alpha or numeric

The macros for these lists are:

###ul-outline

An unordered outline list

you can see has bullets

is displayed inside a white box

which has a black border

###

###ol-outline

An ordered outline list

Has alpha enumerators

instead of bullets

in the same boxed style display

###

###ol-outline-numeric

A numeric outline ordered list

Has numeric enumerators

instead of apha enumerators

but with the same boxed style

###

###ul-inline

Inline lists

work just like outline lists

but do not have the boxed styling

They can be ordered or unordered (using enumerators or bullets)

and the enumerators can be alpha or numeric

###

You'll notice from the top of this article that lists can be embedded inside lists, like so:

Here's a list of lists

  • The outer list is in the inline style

  • but it includes inner lists:

  • The first inner list

    1. is an ordered outline list

    2. using alpha enumerators

  • The second inner list

    1. is also an ordered outline list

    2. but this time using numeric enumerators

We can nest other things, like images inside a list:

Outline outer list

  • Inline inner list 1

    • line 1.1

    • line 1.2

    • line1.3

  • alt text here image in a list
  • Inline inner list 2

    • line 2.1

    • line 2.2

    • line2.3

You can always nest one macro inside of another so that things like lists of lists, lists of images, lists in tables, tables of images etc… are all possible

Here's the macro for that last 2-level list with image:

###ul-outline

Outline outer list###ul-inline

Inline inner list 1

line 1.1

line 1.2

line1.3###

###img

articles,images/my-website-framework-3

alt text here image in a list

100######ul-inline

Inline inner list 2

line 2.1

line 2.2

line2.3

###

###

Images

alt text here image in a list

Here's an image that floats left, with the following paragraphs flowing (on the right) with it.

Look at this long paragraph flowing round the image

An image grouped with some text. An image grouped with some text. An image grouped with some text. An image grouped with some text. An image grouped with some text. An image grouped with some text. An image grouped with some text. An image grouped with some text.

And another paragraph.And another paragraph.And another paragraph.And another paragraph.And another paragraph.And another paragraph.And another paragraph.

Here's what the macro for a left floating image looks like:

###img-left

articles,images/my-website-framework-3

alt text here image in a list

200

###

Tables

We can display tables. Which can contain other things like images and lists. If the table is too wide for the screen (often the case on mobile) then tapping a row pops-up the detail of that row (which might otherwise have been off-screen). Tables also have 'zebra styling' so alternate rows have slightly different background shading - to make it easier to read the table:

(click or tap any table row to enlarge)

col 1col 2
12
34
56

Here's the macro for that table:

###table

col 1@@@col 2

1@@@2

3@@@4

5@@@6

###

A more complex example creates a table that contains images and lists, such as:

col 1col 2col 3
123
4
image in table
6
7
  • 8.1

  • 8.2

9

That's quite a complicated table. Here's the macro that creates it, which is explained more fully later..:

###table

col 1@@@col 2@@@col 3

1@@@2@@@3

4@@@^^^###img

articles,images/my-website-framework-3

image in table

60###@@@6

7@@@^^^###ul-inline

8.1

8.2###@@@9###

###

We can even embed tables in lists:

table inlist

  • list entry 1

  • col 1col 2
    12
    34
    56
  • List entry 3

To get an idea of how these special features make text files easier to write and more consistent, you can see here the standard HTML needed to make this 'table in a list' followed by the macro version:

Here's the HTML

<div class="user-ul-outline">

<p class="user-text">table inlist</p>

<ul class="user-ul-outline">

<li class="user-ul-outline-item">

<p class="user-text">list entry 1</p>

</li>

<li class="user-ul-outline-item">

<div class="user-table-container">

<table class="user-table" id="myTable2">

<thead class="user-table-header">

<tr id="tr-2-1" class="user-table-head-row tablehead">

<th class="user-table-heading">col 1</th>

<th class="user-table-heading">col 2</th>

</tr>

</thead>

<tbody class="user-table-body">

<tr id="tr-2-2" class="user-table-data-row even-row tablerow">

<td class="user-table-data">1</td>

<td class="user-table-data">2</td>

</tr>

<tr id="tr-2-3" class="user-table-data-row odd-row tablerow">

<td class="user-table-data">3</td>

<td class="user-table-data">4</td>

</tr>

<tr id="tr-2-4" class="user-table-data-row even-row tablerow">

<td class="user-table-data">5</td>

<td class="user-table-data">6</td>

</tr>

</tbody>

</table>

<div id="myModalTable2" class="modal table">

<div id="tablediv2"></div>

</div>

</div>

</li>

<li class="user-ul-outline-item">

<p class="user-text">List entry 3</p>

</li>

</ul>

</div>

And here's the macro version:

###ul-outline

table inlist

list entry 1

###table

col 1@@@col 2

1@@@2

3@@@4

5@@@6

###

List entry 3

###

I admit, macros can get a tad ugly, especially for tables

BUT they are a lot smaller, and I think more readable, than the raw HTML

as well as giving advanced functionality (like the table pop-up)

AND consistency of styling...

Callouts

'Aside' type information can be put into a 'call-out' that floats either on the left or on the right side of the page, with other content wrapping around it. Call-outs have a heading, an image and then more content (which can be a list or just text or whatever)

Callout

demonstrating a callout

text of callout,

and the callout has a list

  • list a

  • list b

a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.a long paragraph.

And the call-out macro:

###callout-right

Callout

/me.jpg

demonstrating a callout

text of callout,

###ul-inline

and the callout has a list

list a

list b

###

###

Quotations

We also have standard quotations

so said ant

###quote

so said ant

We also have standard quotations

###

Choruses

To see how Chorus works in action check out Anxiety - or see this little example below... The idea is by default you only see the chorus in full the first time, later choruses just say 'CHORUS' - BUT if you click on 'CHORUS' the display changes to show the full chorus everytime -

CHORUS:

a chorus is a repeated block of text with the heading 'chorus'

The first chorus is displayed with it's heading

Subsequent choruses display the heading only

UNLESS YOU CLICK the chorus or its heading!

And look here's a repeat of the chorus above:

CHORUS

###chorus

a chorus is a repeated block of text with the heading 'chorus'

The first chorus is displayed with it's heading

Subsequent choruses display the heading only

UNLESS YOU CLICK the chorus or its heading!

###

And look here's a repeat of the chorus above:

###chorus###

###

Groups

we can also group things togther

Which means they get indented (on large screens)

and blank lines insert a bit of space

whereas normally blank lines are just ignored

Good for displaying poetry”in a section that hasn't enabled 'Group_Lines'

See Part 2 for more on line grouping

and we can

centre group things

if we like

###group

we can also group things togther

Which means they get indented (on large screens)

and blank lines insert a bit of space

whereas normally blank lines are just ignored

Good for displaying poetry”in a section that hasn't enabled 'Group_Lines'

See Part 2 for more on line grouping

###

###group-centre

and we can

centre group things

if we like

###

Playlist Players

We can also create an audio playlist:

  • Shorty : States Of Matter Imony
  • Shorty : Mortician
  • Shorty : I Cant Believe Its Not Punk Rock
  • Shorty : Youre The Very Definition Of
  • Shorty : Plaything
  • Shorty : Strange Girl
  • Shorty : I Will Do Things

###audio-player

poetry,shorty,states-of-matter-imony

poetry,shorty,mortician

poetry,shorty,i-cant-believe-its-not-punk-rock

poetry,shorty,youre-the-very-definition-of

poetry,shorty,plaything

poetry,shorty,strange-girl

poetry,shorty,i-will-do-things

###

Video playlists work the same, but use the macro 'video-player'.

Accordions

An accordion loads additional text files on to a page inside a 'roll-up/drop down' device. Here's an example, using a few of the 'author notes' I've written for some of the articles:

Example Accordion

And the macro that created this:

###accordion

Example Accordion

articles,my-website-framework-3,bookcase

articles,my-website-framework-3,circus

articles,my-website-framework-3,marketing-tips

###

Galleries

Here's a set of images from my 2020 Calendar

I've added these usinga gallery macro, thus:

###gallery-calendar

articles,2020-calendar-collection,

###

Other notes

Also note, macros can define their own styling. Just as we can have an img or img-left macro you can add any text you like after a macro name, providing you then supply styling information inside domain.css; but I think there's already plenty to go at with what has been predefined in The Framework.

BTW here's some links - links to places off-site automatically open in a new browser tab, but local links (to other pages in this site) always open in the current browser tab.

An external link - will open a new browser tab. An internal link - will load the page in the current browser tab

The macros are very powerful but have the disadvantage that only The Framework understands them If you ever want to move your content onto a different Content Management System you will need to convert all these macros into their HTML equivalents. The framework has a utility to help with this called the text-reader. For example this article can be converted to pure HTML by using the following address in the browser:

http://antsmith.net/framework/text-reader.php?file=articles2017/my-website-framework-3

Click THIS LINK to see it in action.

The output is pure HTML with out styling and without javascript. It's not very useful, except for if you need to get the pure HTML for any reason...

Macro Formats

To use a macro firstly type three hash (#) characters then add the macro name (as per the full list at the top of this article, followed by 'return'. Close a macro with a further three hash characters.

Between the opening and closing hash characters provide the detail needed by the macro:

Lists

The first line is the list header (isn't bulleted)

Subsequent lines are the listed items

All of these lines can contain other macros if you need them

Images

The first line is the path* to the image

The second (optional) line is the image's alt text

The third (optional) line is the image width

*this should be expressed as: section,relative-path

Section is the section of the site (the part of the URL that is used, e.g. poetry) where the image will be found. Relative path (eg. images/image) identifies a specific jpg in that section. You don't need to add '.jpg' since the framework only uses jpg images it can add that bit on. This method of identifying an image means we don't have to use absolute directory names (eg. poems2) - so these files will still work if you move all of your underlying content.

Callouts also reference images in this way.

Callouts

The first line is the title

The 2nd line is the path to the image

The 3rd line is the image alt text

The 4th line is the image width

The remainder is the callout text - which can include further macros.

Quote

The first line is the text of the citation

The remainder is the quotation text - which can include further macros.

Table

Tables are a bit complex (sorry).

The first line gives the column headings. Each heading is seperated by three commercial-at characters (@@@)

Subsequent lines are the rows of the table with one element for each column. Each element is seperated by @@@

If you want to insert a further macro into a table cell you need to add three carats (^^^) before the triple-hash macro marker.

Chorus

The contents are the text of the chorus - additional macros are not supported.

Groups

The contents are the text of the group - additional macros are supported.

Literal

The contents are the text to be displayed. You can include further macros, but they will be displayed in their raw format - which is kind of the point really.

Audio-player

Each line identifies a specific mp3 to be included in the player.

The lines provide either of:

  • section,gallery,collection,file

  • section,item,file

...depending on whether the file is located in a 'photo' type section of the website or else an 'item' type section.

The player will only play mp3s, so you don't need to add the '.mp3' extension to the file name.

The mp3 file can be accompanied (in the same location) by a text file and an image file of the same name as the mp3 file. These support the features of the player (display of associated image and transcript).

You can cause the current-track transcript to be displayed by adding a container for it, thusly:

<div id="lyric-a1" class="lyric hide-overflow"></div>

This container relates to the first audio playlist player on the page ('lyric-a1'). If you have more than one audio playlist player you will use subsequent ID's (eg. 'lyric-a2') to display there current track 'transcript'.

The associated text file doesn't have to be the transcript, it can be any infomation you want to display when the track plays.

Video-player

The video player works exactly the same as the audio player except that it doesn't display 'transcripts' or associated images (since the visitor will be watching the video not looking at such extras).

You can still provide an associated text file, so that an appropriate title can be supplied.

Accordion

Accordions are fold-up text containers. They include additional text files on a page inside an accordion device. The contents of the macro are a set of lines that identify a set of text files - in just the same way as the players work (section,gallery,collection,file OR section,item,file).

These text files can also contain rich content macros, so they can present sophisticated materials.

gallery-name

Photo Collection pages get automatic display of albums of images in the collection. The same display device can be used to present any set of images - most likely incidental images uploaded into section/images/<item>/.

There are 3 possibilities for adding items to the display:

  • add all the files found at the standard location, creating albums for any sub-directories found there.

  • add all the files from an indicated album in the standard location

  • add a specific image file.

Essentially this means potentially large groups of images can be added without having to laboriously list each one (as one must in the players and the accordions).

To add all of the images and albums related to an item just specify the site section and item name:

###gallery-ex1

poetry,shorty,

###

To add all of the images of a single album specify the section, item and album:

###gallery-ex2

poetry,shorty,scrapbook

###

To add a specific image don't specify a specific item - just say which site section the image is found, leave the item empty and then provide the full relative path to the image:

###gallery-ex3

poetry,,images/shorty/scrapbook/the-independent-13-08-2015

poetry,,images/shorty/bible-launch/dan-hunt

###

Notice in this last case I have added two things to the display of the images; two individual specific images. The list of things to add can be as long as you like and each line can be whichever of the variants you like. So you could add all of the images from an album along with a few other one-off incidentals, if you wanted to.

Also notice you can have as many of these photo display devices (which in themselves are called galleries!) on the page as you want. Give each one a different name (gallery-ex1, gallery-ex2... in my examples).


In my Next Article you can read about where to upload additional rich media so that the advanced macros (audio and video playlist players, accordions and galleries) can find the content.


Get The Framework

Download The Framework

So you can download this framework for free here.

Or you could take a moment to value the efforts and hit the DONATE button in the footer of the page first.

It kinda depends on what kind of a person you want to be...


More in Technology

Technology