Before going on, make sure that you have a PLIST file editor at your disposal. The following screenshots are made using PlistEdit Pro. Make also sure that you have downloaded our example project with companion devstack.

From time to time, it will be useful to read some documentation on the Stacks API. For your convenience there is a page with a list of links to various pages of the online documentation.

Making a header stack

We are going to make a stack that creates HTML headers with various options.

To do so, we will modify the previous example stack.

The first thing to do is to edit the template.html file and replace the character p with, let us say, the string h3. Instead of creating a paragraph, the stack will now create a header of level 3. The effect of the change of code should be immediate in Rapiweaver; if not, quit and relaunch.

Adding a level selection.

It would be nice if the user could choose the header level in a menu, like in the default header stack. This requires a new control in the stack, i.e. a menu.

The menu element interface is called select in the Stacks API. The documentation for it is here. If you look a the documentation, there may be some terms that are not familiar to you. The category of terms that we are going to describe next is part of the plist format nomenclature.

The PLIST elements

As in many programming environments, the purpose of the PLIST syntax is to provide a way to describe simple or more complex sets of data. We will describe here the simplest elements of this syntax.

Basic data types

In this tutorial, we will only use three kinds of building blocks for our PLIST data:

• String
• Boolean
• Number

Complex data types

We will use two type of complex data types:

• Array: this is a list of elements of the same type
• Dictionary: this is a list of elements with various types

Creating a new control

In your interface, create a new element inside the customItems array, or better, duplicate the only control that exists in the example (an input control).

PlistEdit Pro shortcuts

• to create a sibling to an elemnent, hit ⌘K
• to create a new child, hit ⇧⌘K
• to duplicate an element, hit ⌘D

Once you have created this new sibling, use the central popup menu in the editor to change the item type to Dictionary:

then expand the Dictionary entry. Then create to String childs of the Dictionary element

• create the id element with value headerLevel
• create the type element, which must be select, according to the Stacks documentation

Now, let's have a look at the Stacks API documentation for the select type. We see the following entries in the doc, each described by the name of its corresponding key (we already know to key values: id and type):

items

This is, logically, the entry for the list of items of the menu. Since there may be severel menu items, and that all menu items are similar, it is an Array of menu items. Now, since each item must include the menu item text and the menu item value, each menu item is a complex entry. It is actually an entry of type Dictionary, with two children:

• the menu label, which is a String
• the menu value, that will be the code that will be injected into the web page

So what will be the value of each menu item in the stack? It will be a code string, with value h1, h2, etc. This means that the value is of type String, and that it must contain the string hx, where x is the level number. Here is how your control entry should look with only the first menu item in the code

To create the other entries, copy the menu item entry and paste it five times. Then modify each menu item to reflect the choice of header level, from 1 to 6.

Add also an entry in the control Dictionary of type title that will describe the choice to the stack user.

Don't forget to save the PLIST file.

Fantastic, the menu works, but it does not change the header type!

This is because we have not changed the template.html code file. But we know what to do, because this is similar to what was done in the first example. So, open your file, and replace each instance of h3 by the pseudo code %id=headerLevel%. And it works!

Adding some style

What about chosing the alignment of the header? The user will have the choice between left, right and center alignment. The user interface will also be a menu.

However, this time, we will not modify an HTML element, but rather its style. This is done by using CSS code.

CSS has its own syntax, and CSS code can be located in three places

• in an external file with the .css extension
• inside the head of an HTML file
• inside the HTML tag of an element; in this case, the styling applies only to the element and takes precedence over any other instance of css styling.

Since we want to let the user choose an alignment for each header stack, we will use the last method.

The syntax for this kind of styling is (we take the example of a h3 element):

<h3 style="your css code here">I am the header text<h3>

There remains to put the right CSS code for text alignment. There is a good description at w3schools. Since it does not makes much sense for a header, we will not use the justify option.

You should have no trouble to build the menu interface in the PLIST file. As for the code for the HTML template, it should look like this:

<%id=headerLevel% style="text-align: %id=headerAlign%">%id=theText%</%id=headerLevel%>

assuming that headerAlign is the id of your select sontrol.

Miscellaneous

Before closing this lesson, we would like to highlight a few important properties in a stack PLIST file.

ID

CFBundleIdentifier

This is the unique id of your stack. This is how your stack is referenced in the Stacks plugin. It must be unique and is structured like a reverse URL. For instance, the example 2 stack has the following CFBundleIdentifier: com.webmagic.stack.example2. It follows the pattern

com.<company>.stack.<your_private_stack_id>

CFBundleShortVersionString

This is the version of the stack.

Basic info

author

You.

copyright

Y'know....

title

The name of your stack as displayed in the stack library.

tags

Keywords to search for in the the stack library

The rest

is here

Project download

It's here