foolz/theme

An opinionated theme system where even the views can be classes, and everything is a plugin.

dev-master 2015-01-22 01:40 UTC

Requires

• php: >=5.3.0
• foolz/package: dev-master

Requires (Dev)

• foolz/cache: dev-master

Apache-2.0

• foolz

• theme
• template
• views

README

A theme system that abuses OOP to give you those features you've always dreamed of.

You will need PHP 5.4 for this to work. You can install it through Composer and Packagist.

What a mess!

Foolz\Theme works on top of Foolz\Plugin. This means it has built-in support for plugin-like stuff, that you can use or ignore at will. We use it to allow re-skinning and hooking links on the interface.

We created our own Theme system because other theme systems were nothing more than View managers, monolithic and raw.

This package aims to use a multi-level approach to themes, where you can go up and down in the system and build components at the very last moment - by interacting with the theme directly. The structure goes like this:

• Loader
• Theme
• Builder -> Global Parameter Manager
• View -> Local Parameter Manager

From the View you can bubble up to the Loader, grab the global parameters, enter other partials, and build them within the View.

Other features:

• Child themes: Instead of having to duplicate the entire theme directory, you can extend another theme and fallback on its files. You can also extend from an extended theme, with no limit.
• Asset Manager: compile LESS files on the fly.

Classes

Theme

The Theme object abstracts the content of the theme. These will be returned by the Loader, and you will be able to choose which to use.

• $theme->createBuilder()

  Returns a new builder. It's used to create the HTML.

• $theme->getAssetManager()

  Returns the asset manager. It's used to load and edit the content of the package that the user will download, like stylesheets and images.

Builder

The builder is used to create the HTML. It divides the job between layouts and partials, and provides a global parameter manager.

• $builder->getTheme()

  Returns the Theme that generated this builder object.

• $builder->getParamManager()

  Returns the parameter manager used to hold parameters for the views.

• $builder->createLayout($view)

  • string $view - The name of the layout with underscores

  Sets the layout and returns the View object.

• $builder->createPartial($name, $view)

  • string $name - A given name for the partial
  • string $view - The name of the layout with underscores

  Sets a partial with the given $name, and returns the View object.

• $builder->getLayout()

  Returns the currently set Layout.

• $builder->getPartial($name)

  • string $name - The given name of the partial

  Returns the partial with the given name.

• $builder->build()

  Builds the entire HTML with the given parameters.

Parameter Manager

Parameter managers are used to consistently store variables for use in the theme. The Builder has a global one, and every View has a local one.

• $pm->reset()

  Resets the object to its original state.

• $pm->getParams()

  Returns an array of parameters.

• $pm->getParam($key, $fallback = undefined)

  • string $key - The key for the value
  • mixed $fallback

  Returns the value stored with $key. The fallback is activated through func_num_args() so it works even when using null.

  Throws: \OutOfBoundsException - If the value was not set and a fallback is not available

• $pm->setParam($key, $value)

  • string $key - The key for the value
  • mixed $value - The value

  Sets a parameter

• $pm->setParams($array)

  • array $array - An array of parameters to set

  Takes an array and inserts every single parameter. Doesn't delete previous parameters.

View

The View returned by the Builder is usually a custom object extending \Foolz\Theme\View.

There's also a bunch of shortcuts to go to the above levels available (getBuilder, getBuilderParamManager, getTheme, getAssetManager)

It's compulsory to override the toString() method (not the __toString() magic method!) in order to output the HTML. This function should output HTML or return a string.

• $view->toString()

  Called when the HTML must be generated. It should contain the classic HTML building logic. $this can be used. No manual output buffering is necessary.

• $view->getType()

  Returns the type of View, either layout or partial.

• $view->getView()

  Returns the name of the View.

• $view->getParamManager()

  Returns the local parameter manager.

• $view->build()

  Builds and caches the HTML. Returns the HTML.

• $view->doBuild()

  Builds the HTML and stores it in a variable. Rebuilds the HTML every time it's called.

  CHAINABLE