search

bshaffer / sfHadoriThemePlugin

symfony admin generator with a beautiful theme and clean generated code.
MIT License
21 stars 6 forks source link

readme

sfHadoriThemePlugin

sfHadoriThemePlugin is an admin generator with a beautiful-built in theme. Hadori provides basic functionality for an administrative interface, while keeping the generated code readable and beautiful. For that reason, Hadori does a lot, but she doesn't try to do everything. When you need to break from the norm, Hadori provides you with spectacular generated code to let you hit the ground running.

Installation

With git

git submodule add git://github.com/bshaffer/sfHadoriThemePlugin.git plugins/sfHadoriThemePlugin
git submodule init
git submodule update

With subversion

svn propedit svn:externals plugins

In the editor that's displayed, add the following entry and then save

sfHadoriThemePlugin https://svn.github.com/bshaffer/sfHadoriThemePlugin.git

Finally, update:

svn update

Setup

  1. Before doing anything, you must install the sfThemeGeneratorPlugin. To do this, follow the Installation steps in the README.

  2. In your config/ProjectConfiguration.class.php file, make sure you have the plugin enabled.

    $this->enablePlugins('sfHadoriThemePlugin');

  3. run the "publish assets" task to to symlink your web directory to the web assets of your plugins.

    $ php symfony plugin:publish-assets

Generate the Theme

  1. Run the "theme generate" task for the hadori theme

    $ php symfony theme:generate hadori

  2. Complete the options asked by the generator

    Application to generate theme:
$ frontend
Model for this theme:
$ sfGuardUser
Module for this theme [sf\_guard\_user]: 
$ (enter)

  3. (optional) Configure your assets. jQuery is included in each module by default, but you may want to change this

    # /path/to/generated-module/config/view.yml
all:
  stylesheets:     [/sfHadoriThemePlugin/css/theme.css, /sfHadoriThemePlugin/css/hadori.css]
  javascripts:     [/sfHadoriThemePlugin/js/jquery-1.4.2.min.js, /sfHadoriThemePlugin/js/hadori.js]

  4. (optional) Look at the layout.php.sample file for an example layout. It lives in data/sample/layout.php.sample. Using this layout for your generated modules will apply the Hadori theme. This will also apply to your login form.

Configuration

The generator.yml allows for several options you will be familiar with, with the addition of many new ones. Configuration is as follows:

Customizing the List View

Where before, you may have specified the getTableMethod parameter, now you override the getBaseQuery() function in your actions.class.php. By default, this returns a Doctrine_Query object from your table via the createQuery() function. Override getBaseQuery to add WHERE clauses and other customizations. Just be sure the method returns a Doctrine_Query instance, and you're set!

// override getBaseQuery and join in the User table
protected function getBaseQuery()
{
  $query = parent::getBaseQuery();
  $a     = $query->getRootAlias();
  $query->select($a.'.*, u.first_name, u.last_name')
      ->leftJoin($a.'.User u');

  return $query;
}

Forms and Filters

If you are familiar with the built-in symfony admin generator, you may be asking yourself "How do I configure my form and filter fields?". The answer is simple: Use the form framework provided with symfony. There is no longer a disconnect between your form fields and the fields in your admin generator! Rejoice! Configuring your forms like so:

// lib/form/doctrine/MyModelForm.class.php
class MyModelForm extends BaseFormDoctrine
{
  public function configure()
  {
    $this->useFields(array('title', 'body', 'description'));
  }
}

Hadori knows to only use these fields. But don't forget to run $ php symfony cache:clear, otherwise you'll receive a 500 error when you view your form. This is the same for filters:

// lib/filter/doctrine/MyModelForm.class.php
class MyModelFormFilter extends BaseFormFilterDoctrine
{
  public function configure()
  {
    $this->useFields(array('title', 'body', 'description', 'created_at', 'updated_at'));
  }
}

Only the fields used in your filter form will be available as filters. Remarkable!

Tokens and Smart Linking

Tokens: Hadori Tokens work much the same way as they do in the built in admin generator. All tokens are wrapped in double-percents (%%). Any value that does not match a configuration parameter is thought to be a getter on an object.

Smart Linking: Using relationship aliases in Hadori will automatically link to the show page for those objects as long as a route exists following the convention table_name_show. This means any related objects with a Hadori module will be linked automatically. Here is an example configuration:

list:
  display:  [title, Author, created_at]

The above example will automatically the Author field to the show action for that object (@author_show).

Exporting

Hadori gives you the ability to export subsets of your data to a csv file. This feature is activated by default. You can configure your fields in the same way you configure fields in the list view: using the display configuration.

Custom Exporting: Adding custom columns in the data export can be done two ways. The first is the simplest: Add a getter for that column on your model, and include this in the display configuration.

  // MyModel.class.php
  class MyModel extends BaseMyModel
  {
    //...
    function getTagNames()
    {
      return implode(',', $this->getTags()->toKeyValueArray('id', 'name'));
    }
  }

  // generator.yml
  export:
    display: [title, created_at, tag_names]

The second method is to extend the sfExportManager class and add magic methods to it. This is great if you have a lot of logic required for your export and you'd like to keep that logic out of your model class.

  // MyModelExportManager.class.php
  class MyModelExportManager extends sfExportManager
  {
    public function exportField($object, $field)
    {
      if($field == 'tag_names')
      {
        return implode(',', $this->getTags()->toKeyValueArray('id', 'name'));
      }

      return parent::exportField($object, $field);
    }
  }

  // generator.yml
  export:
    display:        [title, created_at, tag_names]
    manager_class:  MyModelExportManager

To disable exporting, follow the steps below.

  1. Disable the export mode in the generator.yml. Do this by setting export to false

    edit:    ~
new:     ~
export:  false

  2. Turn off the export route by setting the with_export option in routing.yml to false:

    my_admin_route:
  class: sfHadoriRouteCollection
  options:
    # ...
    with_export:          false

Security

Set the use_security_yaml_credentials to true (true by default) to synchronize your module's security.yml file with the generator's credentials. This will automatically hide actions to users without appropriate credentials.

Styling Login Form

This part will only work if you are using sfDoctrineGuardPlugin. Follow these steps to style your login form with the Hadori theme:

Set your application to use the sfDoctrineGuardPlugin login form in your settings.yml:

# app/YOUR-APP/config/settings.yml
all:
  .settings:
    login_module: sfGuardAuth
    login_action: login

Copy over the layout.php.sample file in data/sample as your base application template.

# cd /path/to/project
cp plugins/sfHadoriThemePlugin/data/sample/layout.php.sample apps/YOUR-APP/templates/layout.php

Set your application's stylesheets to the plugin's stylesheets:

# app/YOUR-APP/config/view.yml
default:
  stylesheets:
    - /sfHadoriThemePlugin/css/theme.css
    - /sfHadoriThemePlugin/css/hadori.css

This will already get you a decent looking login form, but if you want to go the extra mile, copy over the _signin_form.php.sample file into your application.

# cd /path/to/project
mkdir -p apps/YOUR-APP/modules/sfGuardAuth/templates
cp plugins/sfHadoriThemePlugin/data/sample/_signin_form.php.sample apps/YOUR-APP/modules/sfGuardAuth/templates/_signin_form.php

Generated Code

View the sfThemeGeneratorPlugin README for more options on how to customize this theme.

Upgrading from the Original Symfony Admin Generator

View the docs article For information on how to upgrade to Hadori from the original symfony admin generator.

Credits

Thanks to Travis Roberts for the hadori stylesheets.