New Feature: Variables

We will not normally cover development and designer functionality in the Graffiti blog, but in this case, there is a very helpful feature coming in Beta 2 which will not be properly documented for a little while.

Introducing: Variables

Variables is a feature that lets developers and designers define dynamic areas of content in a theme.

That was a mouth full, but we can make it simpler with an example. The image below is from the Graffiti home page. We have have a couple of areas on the home page where we have content that doesn't really fit very well in a post, but we still want to be able to edit it every once in a while.

Graffiti CMS Home Page

The first step needed to use this new feature is to add a new file your theme directory called, theme.config. Within this XML file you will define of the Variables needed for your theme. Below is a list of attributes you can specify for each variable.

Require Attributes

  • id – the programmatic name of the field. This is used to render the value of the field throughout the theme
  • text – the name of the field that will be shown on the configuration form

Optional Attributes

  • dataType – the type of this field, supported values are: Bool, Int, Double, String, Date, Time, DateTime, Guid, Color, Unit, Url, and Html (default: String)
  • sortOrder – The order number of this field. This controls the ordering of fields within a similar category on the configuration form (default: defined order)
  • defaultValue – The default value for this field (default: blank)
  • descriptionText – The description of this field that will be shown on the configuration form (default: blank)

To help you get started, please download this sample theme.config.

While defining new Variables is a bit messy/technical, using them is very easy. All you need to do is enter $macros.Variable(id) anywhere in your theme's view files where you would like the content to render. As an example, $macros.Variable("bgColor"). Also note, if necessary, you can re-use the same Variable more than once in the same view and across multiple views.

Configuring Global Fields

OK, so far you have learned how to define a Variable and how to add it your theme. However, calling them a variable is really meaningless unless of course their values can be variable. This is really where this feature shines. While you need to understand a bit about how theming works to define and implement variables, there is absolutely no additional knowledge needed to make use of them.

To change their values, simply navigate to to Control Panel > Presentation > Themes. For those of you who used beta 1, you will see a new option under each theme called Configure.

Theme Choice

Once you click configure you will be brought to a new screen which will let you (or your users and clients) make changes to their Variables. From here all they need to do is click save and the changes will be persistent and displayed on their site.

Here are a couple of examples:
Style Options
Ad Config

Please be on the look out for some more documentation on this very powerful new feature. If you have questions in the meantime, please post them over on our forums.

#1 Brendon Schwartz on 1.17.2008 at 2:05 PM

Great new feature, it is totally needed for splash pages and home pages. When can we get our hands on Beta2! I can't wait to upgrade my sites.

Also if you could make the variables editable without going to the main control panel that would be killer.

#2 Scott Watermasysk on 1.17.2008 at 2:18 PM

Hi Brendon,

We did consider doing in line editing, but in the past this has caused a lot of issues. It is really dependent on JavaScript and Styling which we control 100% in the control panel, but have zero control over in the public part of the site.

Who knows, maybe someone will whip up a cool add-on. :)

Thanks,

Scott

Recent Posts