User:Arthus/ThemeConfig

From Habari Project

Jump to: navigation, search

Currently, few themes offer exemplary configuration. This proposal aims to rectify that by providing a simple and uniform method of themes to provide configuration.

This configuration is through the theme.xml file and is accessible through simple PHP calls.

Contents

Configuration XML

The configuration XML defines what variables a theme uses, what their types are, their defaults. The following is a fictional example.

<?xml version="1.0" encoding="UTF-8" ?>
<theme>
	<name>K2</name>
	<author>K2 Team</author>
	<url>http://getk2.com/</url>
	<version>1.0</version>
	<template_engine>rawphpengine</template_engine>
	<description>A port of the popular design K2 and first Habari "theme"</description>
	<license url="http://www.apache.org/licenses/LICENSE-2.0.html">Apache Software License 2.0</license>
 
	<config>
		<section caption="Style">
			<field name="background" type="color" default="FFFFFF" caption="Background Color" />
			<field name="logo" type="image" width="500" height="100" default="images/logo.png" caption="Logo" />
			<field name="width" type="range" default="300" min="200" max="500" caption="Content Width" />
			<field name="sidebar" type="select" default="r" caption="Sidebar Alignment">
				<option value="r">Right</option>
				<option value="l">Left</option>
			</field>
		</section>
		<section caption="Content">
			<field name="home" type="text" default="Home" caption="Home Label" />
			<field name="elsewhere" type="text" caption="External Link">
				<validator type="url" />
			</field>
			<field name="about" type="textarea" caption="Blurb" />
		</section>
	</config>
</theme>

Each <field> has a variety of attributes, which also vary based upon the field type.

name
Unique identifier of field, to be called within theme
caption
The field caption, for use in display
type
The field type
default
The default field value, if not included will default to "null" – for images, this is a file relative to the theme directory
description
A short field description, used in the admin UI
width
The image width (for images), which will be passed to the image uploader/cropper
height
The image width (for images), which will be passed to the image uploader/cropper
min
For range sliders, this is the minimum allowed value
max
For range sliders, this is the maximum allowed value
expandable
If set to true, the field can have multiple values. Defaults to false.

Field Types

There are a variety of field types available, all of which have different attributes.

color
A hexadecimal color, which will render a color picker in the UI
image
An image, which the user can upload and crop
text
A one-line text field
url
A url, which will be validated automatically
textarea
A multiline text area
range
An integer, which will render a slider in the UI (useful for pixel widths, etc.)
select
A dropdown which will allow the choice between different preset options

Validators

A field can add validators (such as url) by including a <validator> block within, along with a type attribute which specifies the validator to use.

This example would validate any input to be a proper URL:

		<field name="elsewhere" type="text" caption="External Link">
			<validator type="url" />
		</field>

Sections

Fields can optionally be wrapped in <section> tags. These tags will translate into fieldsets when the theme is generated.

The caption attribute will be used to label the fieldset, while its ID will be a serialized version of the caption.

Retrieving Options

Options are retrieved using the Theme::get_option($name) function or Theme::out_option($name) function.

<li>$theme->out_option('home');</li>

If the user has set the option, it will be returned. If the option is unset, the default will be returned. If there is no default, null will be returned. If the field is expandable, an array of values will be returned.

A further idea is to have some advanced CSS tool which would allow variables to be embedded in the stylesheets, but I am holding off on that.

Personal tools