teapotio/base-theme-bundle

This package is abandoned and no longer maintained. No replacement package was suggested.

ThemeBundle for Symfony2

v1.0.0 2015-05-25 03:24 UTC

Requires

• php: >=5.3.2
• symfony/symfony: >=2.3

MIT

• Thomas Potaire

• theme

README

Bundle for Symfony2

Provides powerful tools to create alternative themes for your projets. It will allow you to build themes for your website or a set of bundles.

Why would you use this bundle?

• Javascript, stylesheet and template files are located in a given folder.
• The bundle will look for your assets combine them together, no more headaches.
• You can separate the output of your bundles in multiple themes letting you override other people's theme easily.
• You can create components by grouping files together (see 5. Advanced usage)

Important notes:

• By default, assets are loaded in a random order (see chapter Configuration > File order)

Todo:

1. Allow assets (images, icons, fonts) to be installed using console assets:install.

• Integrate translation files to the theme.
• Double-check if assetic filters work.

Installation

1. Download the bundle

In your composer.json, add the following:

{
    "require": {
        "teapotio/base-theme-bundle": "dev-master",
    }
}

Then update your project:

php composer.phar update

2. Add the bundle to the AppKernel class

Your AppKernel should be located in the app folder of your project.

<?php
...
public function registerBundles()
{
    $bundles = array(
        ...
        new Teapotio\Base\ThemeBundle\TeapotioBaseThemeBundle(),
        ...
    );
...

3. Configure the bundle

Add the following to your config.yml file.

teapotio_base_theme:
    directories: [] # List of folders that contains your themes
    themes: [] # List of themes that are enabled

Note: The order matters, the first template found is the one used. If you want to override a theme with your own, your theme must be define before the other theme.

Example:

teapotio_base_theme:
    directories:
        - Resources/themes # Path relative to the app folder (example: YourProject/app/Resources/themes)
        - @TeapotioSiteBundle/Resources/themes # Supports namespace
    themes:
        - rainbow_override # Theme that overrides part or all of the "rainbow" theme
        - rainbow
        - simplified

4. Create your first theme

Define the folder where you will host your theme and add your theme to the list of enabled themes.

For the example we'll name the theme "teapotio_rocketstorm" (it's good practice to have your theme prefixed with the name of your github account that way theme collision can be avoided) and we'll save the theme in app/Resources/themes so the configuration could look like the following:

teapotio_base_theme:
    directories:
        - Resources/themes
    themes:
        - teapotio_rocketstorm

A. Template

In your project, you are likely to use the following to render a template:

return $this->render('YourBundle:Controller:action.html.twig', array());

All you have to do is create a template in your theme like the following: app/Resources/themes/teapotio_rocketstorm/YourBundle/Controller/action.html.twig

The string passed to the render method should be the path of your template in your theme (it includes the bundle name).

That's it!

B. Assets

During development, run the following command:

php app/console assetic:watch

If assets are located in your theme, you will notice that the command exports them into one file named after your theme.

Assets can be located anywhere in your theme.

Example:

• app/Resources/themes/teapotio-rocketstorm/YourBundle/Controller/action.css
• app/Resources/themes/teapotio-rocketstorm/YourBundle/Controller/action.js

In your HTML, add the following:

<!-- at least one CSS file must be defined for the file to be generated -->
<link href="/css/themeteapotio_rocketstorm.css" rel="stylesheet" media="screen" />
<!-- at least one JS file must be defined for the file to be generated -->
<link href="/css/themeteapotio_rocketstorm.js" rel="stylesheet" media="screen" />

Special characters are replaced by underscore (regex replace /[^\w+]/ with _).

Voilà!

C. Configuration (optional)

Create a file theme.yml at the root of your theme folder.

theme: ~

File order

You should expect that your assets are loaded in a random order. If you need to make sure that certain assets (such as jQuery) are loaded in a certain order then you can list these assets within an assets key in your theme config file like the following:

theme:
    assets:
        scripts: [] # A list of scripts (such as Javascript) that must be loaded in a specific order
        stylesheets: [] # A list of stylesheet (such as CSS) that must be loaded in a specific order

For example:

theme:
    assets:
        scripts:
            - assets/js/jquery.js
            - assets/js/flight.min.js
        stylesheets:
            - assets/css/bootstrap.css

It will load jquery.js and flight.min.js before any other files.

Don't forget to clear the cache when you make a change to this file.

5. Advanced usage

You can create HTML components easily by grouping the different files together

<!-- app/Resources/themes/teapotio_rocketstorm/components/modal.html.twig -->
<div class="Modal">
</div>

/* app/Resources/themes/teapotio_rocketstorm/components/modal.css */
.Modal {
    display: block;
    border: 1px solid #000;
}

/* app/Resources/themes/teapotio_rocketstorm/components/modal.js */
$(document).ready(function () {
    // Do the needful
});

For your CSS files consider using SuitCSS and for your JS files consider using FlightJS. Both libraries will help you create coherent components.