Developers

License

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

What's New

Propel 1.5 is a backwards compatible evolution of Propel 1.4 (the version bundled with symfony 1.3 and 1.4), which adds some very interesting features. Among these features, you will find the new Propel Query API, which is essentially a Criteria on steroids. Check out the WHATS_NEW page in the Propel trac to see the full list of changes.

Admin Generator Extensions

The plugin comes bundled with a new admin generator theme named 'admin15'. This theme provides additional features based on the new Propel 1.5 query objects, and is backwards compatible with sfPropelPlugin's admin generator theme.

To enable this theme, edit your generator.yml and change the theme property from admin to admin15, as follows:

Hydrating Related Objects

The admin15 theme doesn't use the Peer classes anymore, therefore settings referencing the Peer classes are ignored in this theme. This includes peer_method, and peer_count_method. The new theme provides a simple alternative for these settings, called with. Add each of the objects to hydrate together with the main object in the with setting list:

list:
display: [title, Author]
with: [Author]

The admin generator will then execute the following query to display the list, effectively executing a single query instead of 1+n queries:

$books = BookQuery::create()
->joinWithAuthor()
->paginate();

Of course, you can add as many with names as you want, to hydrate multiple objects:

list:
display: [title, Author, Publisher]
with: [Author, Publisher]

Tip: Before adding relations to the with setting, check that you don't already have a filter on the foreign key column that already makes the query to list all the related objects. If it's the case, then Propel's Instance Pooling will make the with superfluous, as each call to a related object will not trigger an additional query anyway.

Additional Query Methods

You can execute additional query methods in the list by setting the query_methods parameter. For instance, in a list of Books, to limit the list of published books, setup your list view as follows:

list:
display: [title]
query_methods: [filterByAlreadyPublished]

The admin generator will then execute the following query to display the list:

Now you can add a partial column and use the virtual NbReviews column in the list:

<?phpecho$book->getVirtualColumn('NbReviews')?>

Sorting On A Virtual Column

The new theme provides an easy way to make virtual columns sortable in the list view. Just declare the corresponding fields with is_sortable to true, and the generated module will look for an orderByXXX() method in the generated query. For instance, to allow a book list to be sortable on the author name:

The generator will execute BookQuery::orderByAuthorLastName() instead of BookQuery::orderByAuthor() in that case.

Filtering The List With GET Parameters

The admin generator doesn't allow to filter the list using GET parameters. This neat feature used to be supported in previous versions of the generator, and is supported again in the admin15 theme.

All you have to do to filter a list view is to prepend a query string to the URL, describing the filters in a filters array. For instance, to link to the book list view filtered by Author, try the following link:

This is very useful for partial lists, to link admin modules together.

Cross-Linking Admin Modules

In lists, related object columns often have to link to another admin generator module. For instance, in a list of Books, a column showing the Author name usually needs to link to the edit view in the author module for the current book author. You can implement this feature using a partial column:

# in generator.yml
list:
display: [title, _author]

The partial column code is a one-liner, but it's quite tedious to repeat it many times:

You no longer need a partial for such simple cases. This should unclutter the templates/ directory of your admin generator modules.

Easy Custom Filter

Adding custom filters becomes very easy once you can take advantage of the generated Propel query classes. For example, in a list of Books, the default filters offer one text input for the book title, and a second one for the book ISBN. In order to replace them with a single text input, here is what you need to do: