pList Editor

If you create your own websites using Stacks, pList Editor is not adding any value as it is only required when building your own stacks. But hey, have you ever thought about creating your own stack to reuse a piece of custom HTML or JS you found somewhere on the internet? If you want to easily reuse that code in your websites in the future, why not packaging the code into a custom stack to make it easier to reuse in the future?

You obviously need the Stacks plugin for Rapidweaver or the new upcoming standalone Stacks 6 App (in Beta) to use the pList Editor. Other than that you just need a text editor to copy and paste the the content into the Info.plist within your stacks bundle.

Not at this point and to be honest, it is rather self-explanatory stack as long as you know what a Info.plist is all about. Other than that, there are just a few things to get started:

• when running pList Editor in Stacks 5.1 using Rapidweaver, you always have to install the pList Theme as well in order to correctly preview Info.plist
• when running pList Editor in Stacks 6 you can just select the base theme that comes with Stacks 6
• when entering text into settings within pList Editor, make sure you only use characters that are allowed within a regular XML. See the table below on how to deal with those characters by escaping them
• when using a an imageTransform property, you must not use %1%, %2%, etc as a image reference within the control as those will be automatically replaced by Stacks when generating the XML content, which will lead to a corrupt XML file. Workaround: create the pList as normal and add those missing image references directly within the Info.plist file.
• in general don't use any template variables inside the pList Editor as those will get expanded as well
• other than that, you can't do anything wrong as the pList Editor always takes care to create a complete and correct Info.plist depending on what assets and controls being used

If you want to create your own stacks today, the goto location for more details is the Stacks API documentation provided by YourHead Software. As the new Stacks 6 App is on the horizon, there are going to be some major enhancements to the Stacks API which are not yet reflected in the current documentation. Stacks 5.1 for Rapidweaver supports API version 13, wheras the Stacks 6 App will support API version 15 and higher.

General

• Always start with a minimal and tested stack bundle that contains all required files needed.
• Create a copy of a working bundle and modify the individual files as needed.
• Create a new Stacks project and add a page for each individual .plist file you want to create. Put the pList Editor stack on each of these pages and setup the stack accordingly.
• Preview a pList and copy the XML into the respective Info.plist.
• Make sure you just modify one aspect of the stack at the time and preview the changes.
• In order to make changes to your stack almost instant instead of restarting Stacks every time, rename your stacks bundle e.g. mystack.stack to mystack.devstack - Please note: you can only have 20 such dev stacks at a time and need to switch back some of those before enabling new ones.

Templates

• Use template files named by their respective scope i.e. each.html, page.html, etc.
• Carefully use the template language the Stacks API supports:
  • Make sure all the properties being used in a template are defined in the Info.plist.
  • Make sure you have all the necessary %[endif]% tags for an opening %[if]% tag. if not, you will find those tags showing up in your final code.
  • Expressions always require a %()% around them. This could become very complex in case you have multiple conditions per if-endif statement.
  • Don't use kebab-case style property names like %id=a-new-property%. Even though this would work in Stacks 5.1 today, Stacks 6 is around the corner supporting a new template language which will not support this naming scheme, which makes migrating such property names difficult. Use underscores instead of dashes or camel-case, i.e. %id=a_new_property% or %id=aNewProperty%.

Properties

• There are two ways of using Select, Checkbox and Button controls within a template:
  • either use their value to switch between sections using %[if]% %[else]% %[endif]% sections
  • or use their state value directly within a template via the trueValue and falseValue capability to redefine the standard value other than True or False e.g. a CSS utility class bg-primary
  • In both cases it is good to name those properties in a way that express the semantics as a switch or a feature
• You can enable properties based on the value of another property via the enable feature in the Info.plist.
• This allows for changing the HUD depending on another control like a button, checkbox or select element.
• If you want to enable certain properties based for instance on a select property value, there are multiple ways to do that.
  • Either you create multiple copies of the dependant property and always test for a different select property value or
  • You can use the contains or match condition to look for matching values which potentially allows for less property copies required.
• At this point there is no way to depend the visibility of a property based on more than one other property. In case you need to do that you might need to make a compromise that in some cases properties are eventually shown in the HUD even though it makes no sense.
• Sometimes splitting up a stack in multiple stacks or sub stacks you could eventually work around this limitation, but there is no golden rule right now.
• If you don't group a property into a specific group, it will be shown in a group named by the stack name, which will only show up at the end of all other groups, while groups normaly appear in the order of definition in the Info.plist
• If you want put properties into a group with the stack name and you want them to show up at the normal order or even at the top, just add an extra space to the stack name.

Compatibility

• Stacks does a pretty good job maintaining compatibility with previous sdtack versions while adding new features over time. But there are a few things to keep in mind:
  • Adding %slice%, %html% or %text% at a later point to an already existing template is no proplem as long as you add it to the end. If introduced before an existing %slice%, %html% or %text%, all already used stacks are impacted as the content of previous %slice%, %html% or %text% are now mixed up showing up in the wrong element.
• Changing property types at a later stage while keeping the name is not always a good choice for existing stacks as some property types can show a weird behaviour. Keep in mind, its not the new stacks, but already placed stacks on a page that are in trouble.
• To deal with such issues, you could create a new version of your stack which only is available for new projects and all previously used stacks are still using the older version of the stack. This is done by marking the old stack a deprecated in the Info.plist and create a new version with a different gundle identifier. Just changing the version number doesn't help here. Deprecated leaves the stack available for existing projects, but hides the stack in the library.

Let's imagine you have a project with a couple of custom stacks. The best way to organize around your various Info.plist files required for those stacks is setting up a normal stacks project and put a pList Editor stack on each individual page representing a single Info.plist for each of your stacks.

Just name the page after the respective stack the Info.plist belongs to and even move pages under other pages to visually represent child stacks. Organizing things along those concepts, all of you Info.plist are in one place and easily accessible.

Unfortunately Stacks itself doesn't provide you any debug tools to check an invalid Info.plist. If something is wrong with your custom stack or its Info.plist, it is either not shown in stacks library or Stacks tells you that your stack is no longer available and can not be rendered.

When it comes to the Info.plist you can use Apples plutil terminal command, which is standard on every modern Mac. In your terminal just enter the following commands in your stacks bundle

% cd Contents
% plutil Info.plist

which first enters the Contents directory, then checks the contained Info.plist file and returns OK or in case of an error you get a detailed error message with the respective line number. Syntax errors should not be an issue when using pList Editor, but not correctly encoded characters could invalidate the XML as well. To encode special characters correctly, just use the following replacements

Absolutely yes. As more details become available about the new Themes and Layout API, pList Editor is going to support those .plist features as well. Themes and layouts use the same basic concepts as normal stacks. At this point pList Editor already supports the known features of the currently available Stacks 6 beta.

Even though pList Editor is free, it is not open source at this point. This might change in the future. If you have some ideas or improvents you wanna see within pList Editor, feel free to contact me.