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.

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

    • player

Here, are examples of each:

    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 outline ordered 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

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:

    1. The first inner list

    2. is an ordered outline list

    3. using alpha enumerators

    1. The second inner list

    2. is also an ordered outline list

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

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.

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 moble) 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 2col 3
123
4
image in table
6
7
  • 8.1

  • 8.2

9

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

    table inlist

  • list entry 1

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

We also have standard quotations

so said ant

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

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 the simple table in a list that we have just above; followed by the macro that I use in my text files:

Here's the html for the simple table in a list above (inside a literal macro):

<ul class="user-ul-outline">
   <p class="articles user-text">table inlist</p>
   <li class="user-ul-inline-item">
      <p class="articles user-text">list entry 1</p>
   </li>
   <li class="user-ul-inline-item">
      <div class="user-table-container">
         <table class="user-table" id="myTable1">
            <thead class="user-table-header">
               <tr id="tr-1-1" class="user-table-head-row" onmousedown="tableHiLight(55)">
                  <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-1-2" class="user-table-data-row even-row" onmousedown="showTablePopUp(1,2)">
                  <td class="user-table-data">1</td>
                  <td class="user-table-data">2</td>
               </tr>
               <tr id="tr-1-3" class="user-table-data-row odd-row" onmousedown="showTablePopUp(1,3)">
                  <td class="user-table-data">3</td>
                  <td class="user-table-data">4</td>
               </tr><tr id="tr-1-4" class="user-table-data-row even-row" onmousedown="showTablePopUp(1,4)">
                  <td class="user-table-data">5</td>
                  <td class="user-table-data">6</td>
               </tr>
            </tbody>
         </table>
         <div id="myModalTable1" class="modal table">
            <div id="tablediv1"></div>
         </div>
      </div>
   </li>
   <li class="user-ul-inline-item">
      <p class="articles user-text">List entry 3</p>
   </li>
</ul>

And here's the macro version of the same table in a list:

###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 readable, than the raw HTML

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

AND consistency of styling...

We can also create an audio playlist:

  • States of matter-imony
  • Mortician
  • I can't believe it's not punk rock...
  • You're the very definition of
  • Plaything
  • Strange Girl
  • I will do things

The first EP from The GameCat recorded at live venues and studios around London through 2010 and 2011.

we can also group things togther

Which means they get indented

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

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 otherpages 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

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 - each of which can contain other macros if you nneed 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

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 furtehr macros, but they will be displayed in their raw format - which is kind of the point really.

Examples

Here's the first section of this article presented in a literal block, so you can see exactly how these things work:

Here, are examples of each:

###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:
###ul-inline
Here's a list of lists
The outer list is in the inline style
but it includes inner lists:
###ol-outline
The first inner list
is an ordered outline list
using alpha enumerators
###
###ol-outline-numeric
The second inner list
is also an ordered outline list
but this time using numeric enumerators
###
###

We can nest other things, like images inside a list:
###ul-outline
Outline outer list###ul-inline
Inline inner list 1
line 1.1
line 1.2
line1.3###
###img
/me.jpg
alt text here image in a list######ul-inline
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&mldr; are all possible

###img-left
/me.jpg
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.

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 moble) 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:
###table
col 1@@@col 2@@@col 3
1@@@2@@@3
4@@@^^^###img
/me.jpg
image in table
100###@@@6
7@@@^^^###ul-inline

8.1
8.2###@@@9###

'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-right
Callout
/me.jpg
demonstrating a callout
text of callout, 
###ul-inline
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.

###ul-outline
table inlist
list entry 1
###table
col 1@@@col 2
1@@@2
3@@@4
5@@@6
###
List entry 3
###

###quote
so said ant
We also have standard quotations
###

To see how Chorus works in action check out <a href="/poems/anxiety">Anxiety</a> - 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###

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 the simple table in a list that we have just above; followed by the macro that I use in my text files:

Here's the html for the simple table in a list above (inside a literal macro):
###literal
<ul class="user-ul-outline">
   <p class="articles user-text">table inlist</p>
   <li class="user-ul-inline-item">
      <p class="articles user-text">list entry 1</p>
   </li>
   <li class="user-ul-inline-item">
      <div class="user-table-container">
         <table class="user-table" id="myTable1">
            <thead class="user-table-header">
               <tr id="tr-1-1" class="user-table-head-row" onmousedown="tableHiLight(55)">
                  <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-1-2" class="user-table-data-row even-row" onmousedown="showTablePopUp(1,2)">
                  <td class="user-table-data">1</td>
                  <td class="user-table-data">2</td>
               </tr>
               <tr id="tr-1-3" class="user-table-data-row odd-row" onmousedown="showTablePopUp(1,3)">
                  <td class="user-table-data">3</td>
                  <td class="user-table-data">4</td>
               </tr><tr id="tr-1-4" class="user-table-data-row even-row" onmousedown="showTablePopUp(1,4)">
                  <td class="user-table-data">5</td>
                  <td class="user-table-data">6</td>
               </tr>
            </tbody>
         </table>
         <div id="myModalTable1" class="modal table">
            <div id="tablediv1"></div>
         </div>
      </div>
   </li>
   <li class="user-ul-inline-item">
      <p class="articles user-text">List entry 3</p>
   </li>
</ul>
###

And here's the macro version of the same table in a list:
###literal
###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 readable, than the raw HTML
as well as giving advanced functionality (like the table pop-up)
AND consistency of styling...

We can also create an audio playlist:
###player
poems2,states-of-matter-imony
poems2,mortician
poems2,i-cant-believe-its-not-punk-rock
poems2,youre-the-very-definition-of
poems2,plaything
poems2,strange-girl
poems2,i-will-do-things
@@@
The first EP from The GameCat recorded at live venues and studios around London through 2010 and 2011.
###

###group
we can also group things togther
Which means they get indented

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
###

Also note, macros can define their own styling. Just as we can have an <b>img</b> or <b>img-left</b> macro you can add any text you like after a macro name, providing you then supply styling information inside <b>domain.css</b>; 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 otherpages in this site) always open in the current browser tab.

An <a target="_blank" rel="nofollow" href="http://calmcarl.uk">external link</a> - will open a new browser tab. An <a href="/poetry">internal link</a> - will load the page in the current browser tab

###
###

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

Technology