sfHadoriThemePlugin - 1.1.0

bshaffer

You are currently browsing
the website for symfony 1

Visit the Symfony2 website


« Back to the Plugins Home

Signin


Forgot your password?
Create an account

Tools

Stats

advanced search
Information Readme Releases Changelog Contribute
Show source

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:

  • General Options

    These are options directly underneath param in the generator.yml configuration file

    • i18n

      Whether or not to wrap interface strings in the i18n __() function. Defaults to false.

    • sortable

      If your model has the csDoctrineActAsSortable behavior, set this to true to enable "promote" and "demote" actions in the list view. Defaults to false.

    • use_security_yaml_credentials

      Any actions declared in security.yml will only be available to the logged-in user if they possess that credential

    • class_label

      The human-readable label for your class. Defaults to the model_class parameter.

    • route_prefix

      This should be the same as specified in routing.yml for the module. This will ensure everything is linked up correctly.

    • actions_base_class

      This class will be extended by the action class generated in cache. Defaults to sfActions.

  • Form Options

    These are options underneath form in the generator.yml configuration file [param > config > form]

    • class

      The sfForm class to use when creating and editing your object. Defaults to the generated doctrine form class (MyModeForm)

  • Filter Options

    These are options underneath filter in the generator.yml configuration file [param > config > filter]

    • class

      The sfFormFilter class to use when filtering the list view. Defaults to the generated doctrine form filter class (MyModeFormFilter)

    • default

      An array of filter name-value pairs to filter your list view by default. ex: default: [is_active: true, type: 'client']

  • List Options

    These are options underneath list in the generator.yml configuration file [param > config > list]

    • title

      Text in the list view's h2 tag

    • display

      Columns to show in the list view table. Defaults to the first five columns in the object's table. See Fields Options below.

    • actions

      Actions to display at the bottom of the list view table. Defaults to [new, export]. See Action Options below. ex: actions: [save, back]

    • batch_actions

      Actions to display in the batch actions dropdown of the list view. Defaults to [delete]. These actions apply to all checked items in the list table. ex: batch_actions: [delete]

    • object_actions

      Actions available to each row of the list view table. Defaults to [show, edit, delete]. See Action Options below. ex: object_actions: [show, edit, delete]

    • pager_max_per_page

      Number of results to show in each list view table page. Defaults to 10.

    • sort

      A sort array to sort your list view by default. ex: sort: [last_name, asc]

  • New Options

    These are options underneath new in the generator.yml configuration file [param > config > new]

    • title

      Text in the new action's h2 tag

    • actions

      Actions available to the new form. Defaults to [save, save_and_add, cancel]. See Action Options below. ex: actions: [save, back]

  • Edit Options

    These are options underneath edit in the generator.yml configuration file [param > config > edit]

    • title

      Text in the edit action's h2 tag

    • actions

      Actions available to the edit form. Defaults to [save, delete, cancel]. See Action Options below. ex: actions: [save, back]

  • Show Options

    These are options underneath show in the generator.yml configuration file [param > config > show]

    • title

      Text in the show action's h2 tag

    • display

      Object properties to show in the definition list. Defaults to all columns. See Fields Options below.

    • actions

      Actions available to the show form. Defaults to [edit, cancel]. See Action Options below. ex: actions: [edit, back]

  • Export Options

    These are options underneath export in the generator.yml configuration file [param > config > export]

    • title

      Text to render in the h2 tag

    • display

      Fields available for export. See Fields Options below.

    • help

      Text to display above the export preview table. ex: help: The table below represents the data that will be exported

    • manager_class

      The class to use when exporting your objects. Defaults to the sfExportManager class included in the admin generator. Read more about this in the Export section below.

    • filename

      The name of the downloadable export file. You do not need to include an extension.

  • Action Options

    It is possible to configure actions under actions in the generator.yml configuration file [param > config > actions], which will be configured for all actions of that name. These can also be configured under each context individually. The following options are available to each action.

    • label

      The text displayed for the link. ex: edit: { label: 'Edit %%class_label%%' }

    • route

      Route name for the action's URL. It is recommended to use without the '@'. ex: approve: { route: comment_approve }

    • object_link

      Set to true if this action corresponds to an sfDoctrineRoute of type object. This will use an object instance as the sf_subject when generating the route. ex: approve: { route: comment_approve, object_link: true }

    • action

      The route option is recommended, but this option can be used when a specific route does not exist, but the action does. ex: promote: { action: promote }

    • credentials

      The credentials required to see this action. This follows the same syntax as security.yml. ex: delete: { credentials: [[Assistant, Administrator]] }

    • method

      The HTTP method to use when this action is clicked. Default is get. ex: delete: { method: delete }

    • confirm

      Prompts the user with a message before executing the action. ex: delete: { confirm: Are you sure? }

    • HTML Attributes

      All other options are passed through to the link_to function, allowing you to set HTML variables here. ex: delete: { id: delete-action, class: delete }

  • Field Options

    It is possible to configure actions under fields in the generator.yml configuration file [param > config > fields], which will be configured for all fields of that name. These can also be configured under the list and show context individually. The following options are available to each fields.

    • label

      This text will be displayed in the header for the list view table and in the definition term tag in the show table.

    • credentials

      The credentials required to view this field. This follows the same syntax as security.yml. ex: num_registrations: { credentials: [Planner, Administrator] }

    • date_format

      If the field value is a valid date string, format it according to PHP Date Format Characters

    • type

      Can be Text, Date or Boolean. Typically set by the database column type, but can be set manually to display fields in a custom way.

      • Type Boolean displays the value as a green check or a red X.
      • Type Date formats the value based on the date_format parameter, Y-m-d by default
      • Type Text displays the string value with no modification
      • to do - Type Object links to the show action for the object if a theme exists for it

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 model's table by calling the createQuery() function. Override this to add where clauses and other customizations. Just be sure that method returns a Doctrine_Query instance, and you'll be all set!

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/form/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.

  • Configuration Parameters: Anything in generator.yml

    edit: { title: Edit %%class_label%% }

  • to_string: a special token for getting at the object's __toString() method

    show: { title: Showing %%to_string%% }

  • getters: anything not matching the previous two tokens is assumed to be an object getter

    delete: { confirm: Are you sure you want to delete '%%full_name%%'? } - will call $object->getFullName()

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

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.

Credits

Thanks to Travis Roberts for the hadori stylesheets.