Learn to make stacks
Introduction
Introduction
This introduction aims to present the important concepts of stack design without getting technical.
The stack
A stack provides a graphical interface to generate code that will be used in a web page.
Enabling the development mode
A stack is actually a folder that looks like a file in the Finder.
To enable the development mode of a stack, you must modify the file extension of a stack from stack do devstack. This will have two consequences:
- The stack will been seen as a folder in the Finder
- The stacks addon will try to monitor the changes that occur in that folder.
Downloading an example devstack will help you understand what follows.
How to use a devstack
To use a devstack do the following:
- if not open, lauch Rapidweaver
- in the "Rapidweaver" menu, select the "Reveal Addons Folder" item
- inside the Addons folder, select the "Stacks" folder and open it
- either drag'n'drop or copy/paste the devstack folder into the "Stacks" folder
- quit Rapidweaver and relaunch
Once you have done this once, you can save time by leaving the "Stacks" folder open, or by creating an alias to it. This way, you can skip steps 1 to 3 above.
The devstack folder
The stack/devstack folder contains itself a folder named Contents, and this folder contains two elements
- a file named
info.plist - a folder named
Resources
The Resources folder
The folder contains the resource files that will we used by your stack. Thay may include many type of files (including icons or media for your stack), but the most important stacks are the stacks that contain code. This code may be html, css, javascript, php, essentially.
The important thing to know is that there are two kinds of code files
- those that are not modified by the stack user (in practice, think of them as assets or, sometimes, as libraries)
- those that can be modified by the user; they are called templates
The info.plist file
This PLIST is a description of the the stack content and interaction interface.
- The content description references the files that are in the
Resourcesfolder. - We describe below how the interface can be specified in the PLIST file
Stack interface: the controls
In the PLIST file, the customItems entry describes a list of interfaces elements. This interface will appear in the right vertical bar of the global stacks interface.
This right bar has generally two interface panes stacked of top of each other
- the default stack interface (which can be suppressed, and this has consequences on the code)
- the interface that is proper to the stack you develop
Below is the interface for the standard two colum stack:
You can see that the interface consists in
- some decriptive text
- two sliders
Each of these sliders are described as control elements in the PLIST file.
Each control has an ID. This ID is proper to each control of the stack. Now that we know that is controls have ID, let us see how this ID is used to connect the user input to the code output. This is possible by using macros in template files that reside in the Resources folder.
Template files
This are code files that have an extra feature: the code can be modified by the stack's controls through the usage of pseudo code that will be replaced by the values provided by the controls.
Example
Let us see a simple example where the user can modify some part of the code in the template file, by inserting some text that it has entered in a text input field. The example stack can be download here.
To make thing simple, we assume that the template file is an HTML file, and that we want the user to be able to modify some text in the HTML file
We need two things:
- an interface to retrieve the user input.
- pseudo code in the HTML template to inject this input
The control is described in the PLIST file. In the user interface, it is a text input field like this:
The PLIST entry for the control looks like this:
You can see that the control has
-
an
idwhich istheText(this will be used to generate code) -
a
titlewhich specifies which text will be put at the left of the input field (here it isYour text) -
a
typewhich isinput, which means that it is a text input
Check that all of this corresponds to the screenshot (except for the id that is hidden)
In the PLIST file, there is also the declaration of a template file that we will use to produce code. The declaration of the template file looks like this:
All we have to do is to edit the template file template.html and insert the following code:
<p>%id=theText%</p>When the stack addons renders the HTML content, it will see the paragraph tags <p> and </p>, and it will also detect the pseudo code %id=theText%. Seeing that, it will fetch the value of the control with ID theText (this value has been modified by the user), and will replace the pseudo code %id=theText% by the text value that was written by the user. In the screenshot, the user has entered Hello you.
The result will be a web page that displays a paragraph with text "hello you". Specifically, in the HTML file, the code <p>%id=theText%</p> will have been replaced by <p>Hello you</p>.
To sum it up, we have the following flow:
This concludes our introduction.
Project download
Download an example project with the example stack.
Requirements
Coding proficiency
Some knowledge of HTML is absolutely essential. Knowing a little CSS will certainly help you do satisfying work.
Programming languages such as Javascript or PHP will allow you to dynamically create content.
The w3schools site is an excellent free resource to start learning these languages. A few links:
Software
A good PLIST file editor is essential. We recommend PlistEdit Pro, which cost $30. It is well worth it.
You will need a web development environment. Available freely is Visual Studio Code which is a very good coding environment. If you want something less intimidating, there is Nova, which is an exclusively Mac app. It is priced at $100 for the first year of updates, and $50 every next year. It has been a good starting point for me.
If you want to test your website locally, especially if it uses PHP, I suggest you install Mamp which lets you test a locally stored website for free. If you feel like testing multiple web sites, I strongly suggest buying Mamp Pro.
