Theme Variables

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