README.markdown in soundcloud-auth-0.1.1 vs README.markdown in soundcloud-auth-0.1.2

- old
+ new

@@ -1,42 +1,42 @@ -SoundcloudAuth +SoundCloudAuth =========== -SoundcloudAuth aims to provide a complete authentication and API access solution for creating SoundCloud applications in Rails. It provides a generator and all of the necessary components to use Soundcloud as the sole authentication provider for an application using OAuth. +SoundCloudAuth aims to provide a complete authentication and API access solution for creating SoundCloud applications in Rails. It provides a generator and all of the necessary components to use Soundcloud as the sole authentication provider for an application using OAuth. ### Major Props -SoundcloudAuth is largely influenced and in a lot of ways identical to [Michael Bleigh's](http://github.com/mbleigh) amazing [TwitterAuth](http://github.com/mbleigh/twitter-auth) plugin. I've used TwitterAuth so many times on my Twitter app development that I found it sorely missed when I tried to tackle the SoundCloud platform. All props and donations should be forwarded to Michael. +SoundCloudAuth is largely influenced and in a lot of ways identical to [Michael Bleigh's](http://github.com/mbleigh) amazing [TwitterAuth](http://github.com/mbleigh/twitter-auth) plugin. I've used TwitterAuth so many times on my Twitter app development that I found it sorely missed when I tried to tackle the SoundCloud platform. All props and donations should be forwarded to Michael. Installation ============ -You can include SoundcloudAuth as a gem in your project like so: +You can include SoundCloudAuth as a gem in your project like so: config.gem `soundcloud-auth`, :lib => `soundcloud_auth` Or you can install it as a traditional Rails plugin: script/plugin install git://github.com/leemartin/soundcloud-auth.git -Note that because SoundcloudAuth utilizes Rails Engines functionality introduced in Rails 2.3, it will not work with earlier versions of Rails. +Note that because SoundCloudAuth utilizes Rails Engines functionality introduced in Rails 2.3, it will not work with earlier versions of Rails. Usage ===== -To utilize SoundcloudAuth in your application you will need to run the generator: +To utilize SoundCloudAuth in your application you will need to run the generator: script/generate soundcloud_auth -This will generate a migration as well as set up the stubs needed to use the Rails Engines controllers and models set up by SoundcloudAuth. It will also create a User class that inherits from SoundcloudUser, abstracting away all of the SoundCloud authentication functionality and leaving you a blank slate to work with for your application. +This will generate a migration as well as set up the stubs needed to use the Rails Engines controllers and models set up by SoundCloudAuth. It will also create a User class that inherits from SoundcloudUser, abstracting away all of the SoundCloud authentication functionality and leaving you a blank slate to work with for your application. Finally, it will create a configuration file in `config/soundcloud_auth.yml` in which you should input your OAuth consumer key and secret as well as a custom callback for development (the 'oauth_callback' option is where SoundCloud will send the browser after authentication is complete). Usage Basics ------------ -SoundcloudAuth borrows heavily from [Restful Authentication](http://github.com/technoweenie/restful-authentication) for its API because it's simple and well-known. Here are some of the familiar methods that are available: +SoundCloudAuth borrows heavily from [Restful Authentication](http://github.com/technoweenie/restful-authentication) for its API because it's simple and well-known. Here are some of the familiar methods that are available: * `login_required`: a before filter that can be added to a controller to require that a user logs in before he/she can view the page. * `current_user`: returns the logged in user if one exists, otherwise returns `nil`. * `logged_in?`: true if logged in, false otherwise. * `redirect_back_or_default(url)`: redirects to the location where `store_location` was last called or the specified default URL. @@ -44,32 +44,28 @@ * `authorized?`: override this to add fine-grained access control for when `login_required` is already called. Accessing the SoundCloud API ------------------------- -The `User` class will have a `soundcloud` method that provides a generic dispatcher with HTTP verb commands available (`get`, `put`, `post`, and `delete`). These are automatically initialized to the `base_url` you specified in the `twitter_auth.yml` file, so you need only specify a path. Additionally, it will automatically append a .json extension and parse the JSON if you don't provide. +The `User` class will have a `soundcloud` method that interfaces with the [SoundCloud Ruby API Wrapper](http://wiki.github.com/soundcloud/ruby-api-wrapper/) allowing you to easily access the [SoundCloud API](http://wiki.github.com/soundcloud/api/). Check out the [Wiki](http://wiki.github.com/soundcloud/ruby-api-wrapper/getting-started) for more info. - user.soundcloud.get('/me') - # => {'username' => 'leemartin', 'full_name' => 'Lee Martin' ... } + user.soundcloud.User.find_me - user.soundcloud.put('/me', 'user[website]=http://lee.ma/rtin') - # => {'username' => 'leemartin', 'website' => 'http://lee.ma/rtin'} + user.soundcloud.Track.find(:all) -If SoundCloud returns something other than a 200 response code, SoundcloudAuth will catch it and try to raise a salient error message. The exception class is `SoundcloudAuth::Dispatcher::Error`. - -Customizing SoundcloudAuth +Customizing SoundCloudAuth ----------------------- -There are a number of hooks to extend the functionality of SoundcloudAuth. Here is a brief description of each of them. +There are a number of hooks to extend the functionality of SoundCloudAuth. Here is a brief description of each of them. ### Controller Methods -SoundcloudAuth provides some default controller methods that may be overridden in your `ApplicationController` to behave differently. +SoundCloudAuth provides some default controller methods that may be overridden in your `ApplicationController` to behave differently. * `authentication_failed(message)`: called when SoundCloud authorization has failed during the process. By default, simply redirects to the site root and sets the `flash[:error]`. * `authentication_succeeded(message=default)`: called when SoundCloud authorization has completed successfully. By default, simply redirects to the site root and sets the `flash[:notice]`. * `access_denied`: what happens when the `login_required` before filter fails. By default it stores the current location to return to and redirects to the login process. Copyright --------- -**SoundcloudAuth** is Copyright (c) 2010 [Lee Martin](http://lee.ma/rtin), released under the MIT License. +**SoundCloudAuth** is Copyright (c) 2010 [Lee Martin](http://lee.ma/rtin), released under the MIT License.