Quick Start

Cull Front is a simple 32bit Windows console program, with no dependencies.

Installation

There is no installation process. Just download and unzip the Cull Front zip file here into a new folder. Set a system PATH to the executable; cullfront.exe so that you can use it from any location on your computer. Cull Front is NOT a GUI program. So double-clicking on the executable in Windows explorer will confuse you — you may even think it is not working as it will start and close quite fast. You need to go old-school: You have to start the program from the command-line of a Windows CMD console window.

Summary

Cull Front loads a "build" file to do its work. Think of it like a csv file, with each row defining the build of one HTML file. Each row contains 5 values — each representing a file name. It can be a fully qualified or partly qualified path. If no path is given, the current working folder is searched. The five values MUST be within "quotation marks".

By default, if you do not specify the filename as an argument on the command line, it tries to load the file build.cull.txt from the current working folder. Note that it is strongly recommended to end the filename in .cull.txt

As the extension is after all ".txt", it is easily loadable into text editors.

The first value in a build is the filename of the HTML to be generated

The rest of the of the values are filenames needed for four types of files need for that build. These are explained below.

The four files specified for a build

Four files have to be always specified on each line of the build file (One line represents one build)after the filename of the HTML file to be built. These filenames are comma-delimited and they must be enclosed in quotation marks. The last two files are actually optional; so if you do not have use for those, specify them as empty strings i.e. "".

If you are creating a multi-page SaaS application or a multipage HTML website, you would have multiple lines in that build file; each line representing each of the pages of your SaaS application. Each of these files are pseudo-CSV files where the first value on the line represents the element ID. Cull Front depends on the fact that every HTML element that is needed for the functionality has to have a unique ID. You can have elements without IDs if they do not contribute to the functionality, by using the templating feature of this system.

  1. First File There is a "tree" file which defines the tree structure, without pulling me into the actual tree shape. Instead each line of the file represents one fragment of the tree. It starts with the element ID of the "root" of that fragment and has an array of the IDs of the main children of that starting root element. If any child has its own children, then that would be seen in some other row of that file. (The order does not matter) Here is an example: NOTE: The special character "!" represents the <head> element and "~" represents the <body> element. These two are not given any ID. The children of an element are placed within square brackets (as an array) Those two fragments are necessary for Cull Front to produce any data; because it will first process the <head> fragment, and then the <body> fragment, and stitch them up together to form the final HTML.

"!",["t1","schtmx","scalpine","sc1","sty1"]
"~",["txa","input_3","txa","hr_1","form1","txc"]
"form1",["input_1","input_2","div_1"]
"div_1",["txa","span_1","pr1"]

  1. Second File This is an "elem" file which defines what tag is used for a particular element id, and what would be the list of attributes for that element. An example is shown below: The first value of each line contains the element id. The second is for the tag name that element stands for. The third is for the list of attributes. As seen below , the attributes are given inside a [...] array(or list) There are 3 types of elements in that list: It is usually nv(STRING,STRING) which represents NAME=VALUE as seen in most HTML attributes. Or it is just n(STRING) which represent element attributes that do not have values. E.g. "readonly" etc. It also can be v(STRING) which is a special invention of mine. It represents the innerHTML used as a special child in the HTML element Note that I have used a special HTML element I invented (not seen in regular HTML syntax) called "t" This is for a special case where only the first v(...) attribute is used either directly as a string OR -- if that string starts with the '@'char, it is picked up from a template file, and the contents of that template file is inserted as the string. This feature makes it very powerful as explained later.

"schtmx","t",[v("@htmx_script.txt")]
"scalpine","t",[v("@alpine_script.txt")]
"txa","t",[v("Hello Mary Lou")]
"form1","form",[nv("method","POST"),nv("action","/gohere")]
"t1","title",[v("Sabu's First")]
"sc1","script",[nv("src","https://aa.com")]
"~","body",[nv("onload","dothis()"),v("So long easy rider...")]
"pr1","pre",[v("Hello there")]
"sty1","style",[v("@main.css")]
"txb","t",[v("@hello.txt")]

  1. Third File The third element of the build line, is an "HTMX" file which is specifically to handle special HTMX attributes. If this file is not to be processed, give an empty string "". This is also a pseudo CSV file. Each row starts with an element ID, and an example is shown below. In this example the first value contains the element ID. The 2nd one is the "hx-trigger", third is the type of HTTP request that needs to be done, fourth is the action of that request, the fifth is the target on which the output is to be deposited, the sixth is what is the swapping type to be done. The last is an array (in square brackets) containing special attributes that are quite similar to regular HTML attributes, that is sometimes used.

"div_1","keyup changed delay:500ms, search","hx-post","/search","#search-results","",[nv("hx-indicator",".htmx-indicator")]

  1. Fourth File The fourth element of the build line is for the "AlpineJS*" file which is to insert special AlpineJS* attributes. If this file is not to be processed, give an empty string "". This is also a pseudo-CSV file. Here is an example below. Again, the first value is for the element ID. The 2nd is a list of attributes that is used by AlpineJS*.

"div_1",[nv("x-data","{aa:true}"),n("x-cloak"),nv(":click","dothat()")]

More details

You can keep the four files in different folders if you so want. (For e.g. if you want other people to work on those files, then you may want to keep the respective file with the folder of the respective person who maybe working on it) In such a case, make sure that the filename given in the build file contains that path. This is the reason why it is critical that all the four filenames specified on each line of the build file must be within quotation marks.

In the above elements file (the 2nd file) you may have seen data such as nv("name","value"), v("@hello.txt") and n("readonly") These are for HTML attributes. Let me explain more details of such attributes. 

nv("class","myclass") will turn up as <... class="myclass" ...> in the HTML
n("readonly") will turn up as attributes without values...In this case: <input readonly> 
v("this is a text") will be used as an innerHTML string. If that string starts 
with '@' it is considered as a template file, and the content is read from 
that file. Explained later.

The attributes can be specified in any order. In fact, all the lines of all the files can be written in any order. It is agnostic to the order. This is very useful as the designer is not forced to think of the order in which to write. But please note that the array of children elements specified for each element should be in the correct order. That is the only place where the ordering matters.

Note that all such lists in all the above files can even be empty -- in which case you need to write it as a pair of empty square brackets: 

[ ]

Readability Also note that for readability and more terseness, you need not put quotation marks around the element id on each line (i.e. the first value of the row) This flexibility is ONLY for the first value. For the rest of the line, quotation marks, commas, parenthesis and square-brackets must be all as shown in the above examples.

As the element ID is always at the beginning of the line in all the four files, you can rapidly reach the element you want in all the files. Just train your eye to look at the beginning of the lines.

Templates

Once the above files are ready, you may also need one more type of file: Those are text files for pieces of text aka "templates". The templates that you regularly keep using for all your projects would be kept in the "templates" folder present in the same location as that of the executable. But there would usually be some custom templates also; specifically to the page you are building. These templates can contain HTML elements and I can see people copy-pasting from various sources on the Internet. As this project evolves, I would be making some templates that everyone can use in their projects. I am hopeful others would also make them. One powerful feature of Cull Front is that it can; in do what I call "magic insertions" into the template just-in-time. For e.g. You may have a standard template for the top navigation bar. Now you would not know in advance what would be the links placed in that particular navigation bar. There is a special "magic insertion" feature documented in the appendix which can dynamically insert a smaller fragment at the correct place just before the HTML is written out.

How does Cull Front recognize such templates? Whenever the value of an attribute is given as in this example: v("@hello.txt") ; Cull Front will try to read the file specified after the '@' sign. (Hello.txt in this example) If a path is not given for the filename, it will attempt to load the contents first from the "templates" folder present in the same folder as the cullfront.exe executable. If that is missing, Cull Front will load the contents from the file present in the current folder.

Settings

Apart from the above files, Cull Front also would want to load 2 other files — those are for handling the settings used internally during the build process. One file is called cullfront.settings.txt and the other is called singletons.dat.txt

Read the appendix for more details. Reasonable defaults are available in the standard zip file that you download. These two files must be in the same folder as that of cullfront.exe

How does it carry out the build?

The way Cull Front works is that it first figures out the complete HTML by culling together info from the tree file and the elems file. Once that string is processed an almost complete HTML is produced, it then proceeds to insert the HTMX as needed by searching for the correct id="" in the string. Once that is done, on similar lines, the AlpineJS* attributes are also inserted.

The reason why the first 2 files are processed before the last two, is because one can write HTMX or AlpineJS* into attributes that may be presented in the strings inside template files (using the special "t" tag I invented) This is a very powerful feature.

Cull Front can make use of system templates (kept in the "templates" folder of the executable) and that is where it will first search. If a file by that name is missing, it searches for the template file in the current folder. The string inside these template file can contain HTML -- thus it can contain fragments of the eventual HTML DOM tree.

Hence, there may be more elements in the final output than what may be specified in the tree file of the build -- as some extra elements may come from the fragments picked up from inside the template string. So the author of the build, can actually insert HTMX as well as AlpineJS* even inside those templated fragments too.

*Though I used the term "AlpineJS" it is not necessary that you are tied to AlpineJS — you can use other JS libraries that use the same strategy as AlpineJS i.e. using specially invented attributes for HTML elements.

PreviousOverviewNextAn example

Last updated