teapotio

Discussion boards for vibrant communities

Theming

Theming is simple with Teapotio.

You can take an existing theme and override any part of it. For that very reason, this doc will first explain where the default theme is located.

The default theme

Located in Teapotio/SiteBundle/Resources/themes, the output is composed of multiple themes:

  • teapotio-forum-base
    This theme includes all basic components.
  • teapotio-forum-profile
    This theme includes all user related templates (profile and settings page, the user's avatar).
  • teapotio-forum-security
    This theme includes all templates related to login, signup, forgot password and reset password forms.
  • teapotio-forum-classic
    This theme includes everything else: the forum features.

Each of these themes are defined in config_default.yml of the same bundle and the assets are included in html.html.twig.

Creating a theme

The easiest way to create your own theme is take another theme and override it to fit your needs.

Copy the following code in your config.yml file:

teapotio_base_theme:
  directories:
    - # Add the path to your bundle's theme
    - @TeapotioSiteBundle/Resources/themes
  themes:
    - # Add the name of your theme here
    - teapotio-forum-classic
    - teapotio-forum-security
    - teapotio-forum-profile
    - teapotio-forum-base

For example, if your theme name is mytheme-acme and your bundle name is AcmeBundle. The directory will be @AcmeBundle/Resources/themes and the theme name will be mytheme-acme.

Working with themes

Template layer

From now on, you can override any templates by simply creating a new one using the same path as the original.

The original template's path:
@TeapotioSiteBundle/Resources/themes/teapotio-forum-classic/TeapotioSiteBundle/layout/html.html.twig
becomes:
@AcmeBundle/Resources/themes/mytheme-acme/TeapotioSiteBundle/layout/html.html.twig

Asset layer

To build your assets run the command console assetic:dump or console assetic:watch while you are developing.

The command will concatenate all your assets located in your theme into a single CSS or JS file.
This CSS or JS file will be named after your theme, for instance, if your theme is named mytheme-acme your assets will be concatenated into thememytheme_acme.css and thememytheme_acme.js.

To avoid class naming collisions, it's important that you follow a certain naming convention for your themes.

The default theme is using SuitCSS for its naming convention but you can use any other out there.

This feature is available as a standalone bundle so you can include it in your project. Follow the bundle's README.md to learn how to install it.

The page structure

Each page is dynamically loaded while navigating through the forum. Using the include and extends features of Twig templating engine we can easily create such system.

The page structure is as follow:

layout/html.html.twig [1]
page/controller/action.html.twig [2]
wrapper/base.html.twig [3]
partial/base.html.twig [4]
partial/controller/action.html.twig [5]

Notice the numbers next to the template path. To simplify the syntax, numbers will be used and file extension will be omitted below.

When a user first visits a page, it will render action[2] (left column). This template extends html[1] (head and body HTML tags) and includes its corresponding partial template action[5].

The partial template action[5] is the content of the page. When a user navigates to another page it will dynamically load and render this partial template instead of the page template action[2].

The partial template action[5] extends the base partial template partial/base[4] which extends wrapper/base[3].

Partials include the content specific to the requested page. For instance, a header would not be part of a partial but a pagination would.

Templates [3] and [4] are particularly useful to define common features between a set of partials.