Theme Variables

This page is aimed at theme developers and people who want to know more about how Showkase works. Theme variables hold data for use in templates. Some variables are provided automatically by Showkase and some need to be defined by the theme developer.

What are Theme Variables?

Showkase publishes a web site by reading values from variables and plugging them into templates or passing them to gallery viewers. Theme developers can define their own variables and use additional ones provided by Showkase. The variable content can come from the theme, from the Showkase user or from the Showkase system.

A valid variable name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. No other characters are permitted. Variable names are case-sensitive. Variables starting with ss_ for showkase system are recognized by Showkase and used for special purposes.

Variable Scope

Global Variables

Global variables are provided by the Showkase system, begin with an ss_prefix and can be used in templates as required. Example: ss_navLinks. Global variables are not exposed for user edits. A full list of global variables is given below.

Site Variables

Site variables are available to all themes and all page types. They are set-up in the site.ini file within each theme, begin with an ss_ prefix and can be used in templates as required. Example: ss_siteHeader. They may be exposed to the user in the Site customize screen. A full list of site variables is given below.

Theme Variables

Theme variables are available within a particular theme and apply to all page types. They can be defined by the theme designer and set-up in the theme.ini file. They can be exposed for user edits in the theme customize screen. Theme variables are usually used for style settings such as colors or fonts which are specific to a particular theme but do not change from page to page.

There are some special theme variables which are used to pass data from the theme to the Showkase system. A list of special theme variables is given below.

Viewer Variables

Viewer variables are available within a particular theme and apply to a particular viewer. Each viewer has its own ini file within the theme, for instance viewers/juicebox.ini. These variables can be exposed for user edits in the Customize Viewers screen. Each variable name must be exactly the same as the corresponding viewer setting and is case-sensitive. Showkase will look to see if the content of each variable differs from the viewer default. If so it will pass the content to the viewer configuration file such as gallery.xml or config.xml.

There are currently no special viewer settings variables and no special prefixes.

Page Variables

Page variables are available to the template for a particular page type. Each page type has its own ini file inside the theme pagetypes folder, for instance pagetypes/basic.ini. Variables can be exposed to user edits in the corresponding page customize screens. Use page variables for data that needs to change from page to page such as a title or page body content.

There are some reserved page variable names which are used to pass data from one theme to another, for instance ss_pageTitle. A list of special page variables is given below.

Variable Precedence

A variable may be defined in more than one place and can be exposed in the corresponding screens for user edits. For instance it is possible to allow the user to set a background image for the theme as a whole and to override it for individual pages. Variables defined in one of the levels listed below will be overridden by the same variable set in a more specific level further down the list (higher numbered levels override lower).

  1. Site (site.ini)
  2. Theme (theme.ini)
  3. Viewer (e.g. viewers/juicebox.ini)
  4. Navigation (nav.ini)
  5. Page (e.g. pagetypes/juicebox.ini)

Using Showkase Variables

To access a variable in one of your templates, you should start the variable name with a dollar sign and surround it with {brace} characters. For instance:

  <div class="footer">
    {$ss_siteFooter}
  </div>

Some variables are simple strings, others are arrays or objects for use in advanced themes. Here is a more advanced example which uses a Smarty foreach loop to generate a set of div elements containing images:

<section class="gallery">
  {foreach $ss_images as $image}
    <div class="gallery-item">
      <div class="image">
        <a href="{$image->linkUrl}"
          target="_blank"
          title="link: {$image->linkUrl}">
          <img alt="" src="{$image->imageAbsUrl}">
        </a>
      </div>
      <h3>{$image->title}</h3>
      <p>{$image->caption}</p>
    </div>
  {/foreach}
</section>

Defining New Variables

All the ini files have the same format. Each variable definition starts with the variable name enclosed in bracket characters, followed by a series of settings for that variable. A valid variable name starts with a letter or underscore, followed by any number of letters, numbers, or underscores. No other characters are permitted. Variable names are case-sensitive. Here is a simple example for a theme variable that will not be exposed for user edits:

[galleryWidth]
value = "100%"

Here is a more complex example of a variable that will be exposed for user edits:

[select1]
exposed = "true"
section = "Select"
type = "select"
value = "1"
label = "Select example"
tooltip = "Choose a number 1 to 3"
values[] = "1"
values[] = "2"
values[] = "3"
options[] = "one"
options[] = "two"
options[] = "three"

The user will see an html select element with the label "Select example". The form element will be placed within a fieldset having the legend "Select". The user can choose "one", "two" or "three" and the user choice will be saved in $select1 as "1", "2" or "3" respectively. The default value is "1". The tooltip will be displayed when the user hovers over the label.

Here is a fictional ini file containing one of each type of variable. Lines starting with a semi-colon are comments.

;;;;;;;;;;;;;;;;;;;;;;;;;
; Example page ini file ;
;;;;;;;;;;;;;;;;;;;;;;;;;

; plain text input (default variable type)
[pageTitle]
exposed = "true"
section = "Page body"
type = "text"
value = "Example ini file"
label = "Page title"
tooltip = "Title for this page"

; html5 number input
[someWidth]
exposed = "true"
section = "Gallery"
type = "number"
min = "0"
max = ""
step = ""
value = "25"
label = "Enter width in px"
tooltip = "Enter a positive whole number"

; Text input with color picker
[foregroundColor]
exposed = "true"
section = "Colors"
type = "hexcolor"
value = "FFFFFF"
label = "Foreground color"
tooltip = "Enter a hex color (no prefix) or user the picker"

; Text input with color picker and separate opacity input
[textColor]
section = "Colors"
type = "rgbacolor"
value = "rgba(255,255,255,1)"
exposed = "true"
label = "Text color"
tooltip = "Enter a hex color (no prefix) and an opacity value"

; img tag src attribute with browse library button
[img1]
exposed = "true"
section = "Images"
type = "imagesrc"
value = "Image test"
label = "Image Url"
tooltip = "Enter image url or browse the library"

; html select form element
; the values array defines the return values
; the options array defines options displayed to the user in a drop-down list
; the options array must set all options or none
; if the options array is omitted then the drop-down list will show the values
[select1]
exposed = "true"
section = "Select"
type = "select"
value = "1"
label = "Select example"
tooltip = "Choose a number 1 to 3"
values[] = "1"
values[] = "2"
values[] = "3"
options[] = "one"
options[] = "two"
options[] = "three"

; html checkbox
; returns string "off" or "on".
; return values default to "false" or "true" if values array is omitted.
[checkbox1]
exposed = "true"
section = "Checkboxes"
type = "checkbox"
value = "off"
values[] = "off"
values[] = "on"
label = "Checkbox example 1"
tooltip = "Check for on"

; html radio buttons
[radio1]
exposed = "true"
section = "Radio"
type = "radio"
value = "option1"
label = "Radio test"
values[] = "option1"
values[] = "option2"
options[] = "Option 1"
options[] = "Option 2"
tooltip = "Choose an option"

; html textarea input
; double line breaks are automatically replaced with p tags
; can be used as a simpler alternative to the editor field type
[textArea1]
rows = "10"
cols = "40"
exposed = "true"
section = "Text area"
type = "textarea"
value = "test"

; WYSIWYG editor
; returns html
[pageBody]
exposed = "true"
section = "Page body"
type = "editor"
label = ""
value = "<p>Enter your page body content here</p>"

Variables and Theme Changes

Site Variables

Site variables such as ss_pageHeader are always carried-over from theme to theme.

Theme variables

Theme variables are stored under the theme name and will never be carried forward from theme to theme. So if the user switches theme, makes some changes and then switches back, the original theme.ini settings will be restored.

Viewer Settings

Viewer variables are stored per theme per viewer type and will not be carried forward if the user changes theme or changes viewer. When the user switches back then the saved values for the current theme and current viewer type will be used in publishing the site.

Page variables and Theme Changes

Page variables are a little more complex because sometimes we want data to be carried forward from theme to theme and sometimes we don’t. For instance, page body content is typed-in by the user and it would be tedious for the users to have to type it all in again every time they change theme. On the other hand an unpredictable value for gallery width coming in from another theme could wreak havoc with your design.

The variable names have an effect on whether data is carried over from one theme to the next. For persistent data, such as the page body, you should use the recommended ss_ variable names listed below. If all themes use these variable names consistently then user content will be carried-over smoothly from theme to theme.

In other cases, you will want to make sure that your own settings are not overwritten when the user switches from another theme to yours. In this case it's best to start your variable name with a prefix derived from your theme name, mytheme_img1Src. Note that the prefix must follow the rules for variable names.

Global System Variables

The following variables are provided automatically by ShowKase and do not need to be defined in an ini file. Do not use these names for any variables that you define yourself.

$ss_showkaseVersion: string
Showkase version number
$ss_showkaseBuild: string
Showkase build time
$ss_pageVersion: string
Version string for viewer pages. Empty for non-viewer pages
$ss_hostName: string
Host name as returned by php $_SERVER['HTTP_HOST']
$ss_siteUrl: string
Absolute url for web site content. Empty for root installation
$ss_themeUrl: string
Absolute url of theme directory relative to current page. Useful for links to css, scripts etc.
$ss_themesUrl: string
Absolute url of directory that contains all themes
$ss_viewersUrl: string
Absolute url for directory holding cached viewer code
$ss_pageRef: integer
Unique reference number for the current page.
$ss_pageUrl: string
Absolute url of current page starting with a slash
$ss_pageType: string
Page type such as 'juicebox', 'basic', etc.
$ss_navName: string
The text to show in the navigation menu for the current page.
$ss_navWeight: floating point number
Heavy weights ‘sink’ lower in the nav menu.
$ss_navShow: string "true"/"false"
$ss_navShow = "false" hides the page in the nav menu
$ss_indexShow: string "true"/"false"
$ss_indexShow = "false" hides the page in index pages
$ss_parentPage: integer
Pages that are not a member of a group have $ss_parentPage = 0. Group members have $ss_parentPage set to the unique reference number of their group parent.
$ss_ogTitle: string
Page title for use in OpenGraph tag
$ss_ogImageUrl: string
Image url for use in OpenGraph tag
$ss_SEOContent: html string
Search engine gallery content
$ss_nav: object
Reserved for future expansion
$ss_activeNavLinks: string
Html code for nav menu including active subnav
$ss_allNavLinks: string
Html code for nav menu including all subnav
$ss_navLinks: string
Html code for nav menu switchable between all subnav and active links only
$ss_showAllSubNav: boolean string
Switch for $ss_navLinks
$ss_allGalleryLinks: array of galleryLink objects
Can be used to create gallery index pages
$ss_allGalleryLinks[0]: object
First gallery link
$ss_allGalleryLinks[0]->navName: string
Gallery name as in nav menu
$ss_allGalleryLinks[0]->galleryUrl: string
Gallery url relative to page
$ss_allGalleryLinks[0]->thumbUrl: string
Thumbnail url relative to page
$ss_allGalleryLinks[0]->thumbWidth: string
Thumbnail width px
$ss_allGalleryLinks[0]->thumbHeight: string
Thumbnail height px
$ss_allGalleryLinks[1,2...]: object
Similar to $ss_allGalleryLinks[0]
$ss_groupGalleryLinks: array of galleryLink objects
Similar to $ss_allGalleryLinks for galleries that the user has grouped under the current page
$ss_images: array
Array of gallery image objects
$ss_images[0]: object
First gallery image
$ss_images[0]->imageAbsUrl: string
Absolute image url (starting with a slash)
$ss_images[0]->width: string
Image width px
$ss_images[0]->height: string
Image height px
$ss_images[0]->thumbUrl: string
Thumbnail url relative to page
$ss_images[0]->linkUrl: string
Url to go to when user clicks on image
$ss_images[0]->linkTarget: string
Target attribute for image link
$ss_images[0]->title: string
Image title
$ss_images[0]->caption: string
Image caption (maps to description in TiltViewer)
$ss_images[1,2...]: object
Similar to $ss_images[0]
$ss_customNavUrl: text
Url for custom navigation links (link pages)
$ss_customNavTarget: text
Target attribute for custom navigation links (link pages)
$ss_viewersUrl
Url for viewer code cache

Site System Variables

The following variables names are reserved for use in the theme site.ini file and can be exposed for user edits in the Showkase Site customize screen.

$ss_siteTitle
Web site name to show on pages screen and in html <title> tag.
$ss_siteHeading
Page header text
$ss_siteSubHeading
Page sub-heading text
$ss_siteHeaderLink
Url for anchor link on page header
$ss_siteFooter
Text for page footer
$ss_metaKeywords
Comma separated list of keywords for html meta tag
$ss_pageDescription
Text for description meta tag
$ss_googleAnalyticsId
Google analytics web property ID

Theme System Variables

The following names have special interpretations when set in a theme.ini file. You should not use these names for any of your own variables.

ss_indexThumbWidth: integer
Width of thumbnail image created by Showkase (may be overridden by calculated value)
ss_indexThumbHeight: integer
Default image height (may be overriden by ss_indexThumbFormat)
ss_indexThumbColumns: integer
User setting for number of columns in gallery index page
ss_indexThumbFormat: integer
User setting for thumbnail height as a percent of width
ss_totalIndexThumbWidth: integer
Showkase calculates actual thumb width as ss_totalIndexThumbWidth/ss_indexThumbColumns if these variables are set in the theme.

Page Variables

Variables for all page types

The following reserved names will guard against loss of data when the user changes theme. They are not set-up automatically. They must be set-up in the appropriate page type ini file if used in templates.

$ss_pageTitle: string
Individual page title
$ss_pageDescription: string
Description for inclusion in meta tags. Overrides the site level description if set
$ss_pageBody: html string
Main page text or descriptive text on a gallery page
$ss_figure1Src, figure2Src etc: string image src attribute
Images to be displayed in the page but outside the page body, e.g. an image for the About page.

Contact page variables

Contact details should follow the vcard format. The following names will help to guard against loss of data when the user changes theme.

$ss_vcardFn: string
Full name
$ss_vcardOrg: string
Organisation name
$ss_vcardPostOfficeBox: string
Post office box
$ss_vcardExtendedAddress: string
Additional (Building, business park, etc)
$ss_vcardStreetAddress: string
Street address
$ss_vcardLocality: string
Town or city
$ss_vcardRegion: string
State or county
$ss_vcardPostalCode: string
Postal code
$ss_vcardCountryName: string
Country
$ss_vcardEmail1: string
Email address
$ss_vcardEmail2: string
Second email address
$ss_vcardTel1Type: string
First phone type, e.g. Voice, Home, Message, Work, Preferred, Fax, Cell, Video, Pager, Car
$ss_vcardTel1Value: string
First phone number
$ss_vcardTel2Type: string
Second phone type, e.g. Voice, Home, Message, Work, Preferred, Fax, Cell, Video, Pager, Car
$ss_vcardTel2Value: string
Second phone number
$ss_vcardTel3Type: string
Third phone type, e.g. Voice, Home, Message, Work, Preferred, Fax, Cell, Video, Pager, Car
$ss_vcardTel3Value: string
Third phone number