Skip to content

Commit

Permalink
Browse files Browse the repository at this point in the history
Merge remote branch 'stevenheidel/master'
  • Loading branch information
parndt committed Feb 17, 2011
2 parents 1a70fe0 + 9ce9035 commit b93a9e0
Show file tree
Hide file tree
Showing 40 changed files with 1,760 additions and 275 deletions.
1 change: 0 additions & 1 deletion .gitignore
Expand Up @@ -8,7 +8,6 @@ tmp/**/*
# Documentation
doc/api
doc/app
doc/*
.yardoc
.yardopts

Expand Down
21 changes: 0 additions & 21 deletions authentication/license.md

This file was deleted.

17 changes: 0 additions & 17 deletions authentication/readme.md

This file was deleted.

21 changes: 0 additions & 21 deletions base/license.md

This file was deleted.

21 changes: 0 additions & 21 deletions core/license.md

This file was deleted.

21 changes: 0 additions & 21 deletions dashboard/license.md

This file was deleted.

23 changes: 23 additions & 0 deletions doc/authentication.md
@@ -0,0 +1,23 @@
# Authentication

## About

At the heart of Refinery's user management is the authentication engine located in ``authentication/``

What this really is is just a standard [Devise](http://github.com/platformatec/devise)
install extended with a few extra features like "I forgot my password" and hooked directly
into the heart of Refinery's engine system.

Devise allows you to easily integrate with other systems too.
So you could be logged in into another system using devise and easily stay logged
in between the two systems without having to login twice.

## Adding New Users

New users can be easily added by going to the 'Users' area admin and clicking on "Add New User".

## Limiting and Granting Access

Each user has a set of engines they're allowed to see.
You can control which engines each user can see by checking and unchecking the
checkboxes next to the engine name when editing or adding a new user.
66 changes: 43 additions & 23 deletions core/crud.md → doc/crud.md
Expand Up @@ -4,11 +4,14 @@

__Most controllers Refinery and other apps do four common things, create, read, update and delete stuff.__ Instead of writing the same logic for these actions over and over again we wrap all this functionality up into what we called ``crudify``.

``crudify`` takes these four basic actions and extends them to allow easy paging, searching and sorting too.
``crudify`` takes these four basic actions and extends them to allow easy paging,
searching and sorting too.

Although this single file is included in Refinery, you could take just this single file and use it in any app you like.
Although this single file is included in Refinery, you could take just this single
file and use it in any app you like.

The best part about ``crudify`` is that this gives you a smart default and if there is anything you want to work differently just override that method.
The best part about ``crudify`` is that this gives you a smart default and if
there is anything you want to work differently just override that method.

## Where is it located?

Expand Down Expand Up @@ -48,7 +51,9 @@ If you used the Refinery generator you're plugin will already be using ``crudify

Default value is ``title``

This is the human readable value you want ``crudify`` to use throughout. Just choose an attribute that is on your model that is short and descriptive to what the model is.
This is the human readable value you want ``crudify`` to use throughout.
Just choose an attribute that is on your model that is short and descriptive to
what the model is.

#### Example

Expand All @@ -62,9 +67,12 @@ On a ``team_member`` model you'd probably want to use an attribute like ``name``

Default value is ``position ASC``

This is the position that is used when listing out what you're crudifying. If you have ``:sortable`` set to ``true`` you probably want to have your ``:order`` set to ``position ASC`` so it uses the order you have set when sorting.
This is the position that is used when listing out what you're crudifying.
If you have ``:sortable`` set to ``true`` you probably want to have your ``:order``
set to ``position ASC`` so it uses the order you have set when sorting.

If you have a news area, it makes more sense to sort by ``posted_at``. So you might set it like this
If you have a news area, it makes more sense to sort by ``posted_at``.
So you might set it like this

:order => "posted_at DESC"

Expand All @@ -74,33 +82,36 @@ Default value is ``nil``

This will filter down the list of items you have when you're asking for all records.

An example here is say you're crudifying a photos table that uses attachment_fu. Attachment_fu creates several photo records, 1 for the main photo and others for it's "children" thumbnails. Those thumbnails have a parent id set.

So when viewing a list of the images you have you don't want it to show all the thumbnails too, you just want to each see unique image listed so you need to apply some conditions to hide the thumbnails.

You do that like this:
Say you want to filter only by items that are top-level (have no parents):

:conditions => {:parent_id => nil}

### ``:sortable``

Default value is ``true``

Enabling ``:sortable`` gives you several handy methods which "just work" with sortable JavaScript lists. One of the methods is ``update_positions()`` which handles saving the new position items have been sorted into.
Enabling ``:sortable`` gives you several handy methods which "just work" with
sortable JavaScript lists. One of the methods is ``update_positions()`` which
handles saving the new position items have been sorted into.

### ``:searchable``

Default value is ``true``

When this option is ``true``, the routes are modified so when you go to the next page of results the search continues on.
When this option is ``true``, the routes are modified so when you go to the next
page of results the search continues on.

### ``:include``

Default value is ``[]``

For performance optimisation, sometimes you might want to eager load other related models to this one. For example a ``news_post`` might below to a ``user`` who wrote the post. But in our index view we're printing out the name of each user.
For performance optimisation, sometimes you might want to eager load other related
models to this one. For example a ``news_post`` might below to a ``user`` who wrote
the post. But in our index view we're printing out the name of each user.

Instead of having to look up each user for each of the ``news_posts`` we iterate over, the ``:include`` option allows you to load the ``news_post`` and user all at the same time which'll allow you to save on expensive database queries.
Instead of having to look up each user for each of the ``news_posts`` we iterate
over, the ``:include`` option allows you to load the ``news_post`` and user all
at the same time which'll allow you to save on expensive database queries.

Here's an example of that.

Expand All @@ -120,17 +131,20 @@ Here's an example of that.

Default value is ``true``

The ``:paging`` option tells ``crudify`` you don't just want one big long list but rather to break it out into pages and support paging methods uses [will_paginate](http://wiki.github.com/mislav/will_paginate/).
The ``:paging`` option tells ``crudify`` you don't just want one big long list
but rather to break it out into pages and support paging methods uses [will_paginate](http://wiki.github.com/mislav/will_paginate/).

### ``:search_conditions``

Default value is ``nil``

Similar to the ``:conditions`` options, ``:search_conditions`` just apply these conditions when delivering search results.
Similar to the ``:conditions`` options, ``:search_conditions`` just apply these
conditions when delivering search results.

## Easy Accessor Methods

``crudify`` automatically writes up finder methods for the model you're crudifying. The easier way to explain this is with an example.
``crudify`` automatically writes up finder methods for the model you're crudifying.
The easier way to explain this is with an example.

Say we have a pages controller that is going to manage pages.

Expand All @@ -145,7 +159,8 @@ In this controller, automatically I have these methods:
find_page()
find_all_pages()

So say I wanted to change the way all pages are found, all I do is override the ``find_all_pages`` method.
So say I wanted to change the way all pages are found, all I do is override
the ``find_all_pages`` method.

class PagesController < ApplicationController

Expand All @@ -159,7 +174,9 @@ So say I wanted to change the way all pages are found, all I do is override the

## Overriding or Extending Crudify

Before overriding anything, the best thing to do is check out how the default works. Read the ``vendor/plugins/refinery/lib/crud.rb`` and see what code it's injecting into your controller.
Before overriding anything, the best thing to do is check out how the default works.
Read the ``vendor/plugins/refinery/lib/crud.rb`` and see what code it's injecting
into your controller.

Pick the method you want to override and then override it in your controller.

Expand All @@ -171,7 +188,8 @@ Let's go back to the example above with the pages controller.

end

Say every time someone deletes a page I want my ``NotificationMailer`` to email me to say someone just deleted a page.
Say every time someone deletes a page I want my ``NotificationMailer`` to email
me to say someone just deleted a page.

When I look in the ``crud.rb`` file I see that my controller has this added to it

Expand All @@ -180,7 +198,8 @@ When I look in the ``crud.rb`` file I see that my controller has this added to i
redirect_to admin_#{plural_name}_url
end

To override this all I would is create my own delete method that works the same but just with my mailer code on it.
To override this all I would is create my own delete method that works the same
but just with my mailer code on it.

class PagesController < ApplicationController

Expand All @@ -189,7 +208,8 @@ To override this all I would is create my own delete method that works the same
def destroy
if @page.destroy
flash.notice = "'#{@page.title}' was successfully deleted."
NotificationMailer.deliver_page_deleted(@page) # sends me an email to say a page was deleted
NotificationMailer.deliver_page_deleted(@page) # sends me an email to
say a page was deleted
end
redirect_to admin_pages_url
end
Expand Down
File renamed without changes.

0 comments on commit b93a9e0

Please sign in to comment.