README.md in simple_command_dispatcher-3.0.2 vs README.md in simple_command_dispatcher-3.0.3
- old
+ new
@@ -1,18 +1,18 @@
[](https://github.com/gangelo/simple_command_dispatcher/actions/workflows/ruby.yml)
-[](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher)
-[](https://badge.fury.io/rb/simple_command_dispatcher)
+[](https://badge.fury.io/gh/gangelo%2Fsimple_command_dispatcher)
+[](https://badge.fury.io/rb/simple_command_dispatcher)
[](http://www.rubydoc.info/gems/simple_command_dispatcher/)
[](http://www.rubydoc.info/gems/simple_command_dispatcher/)
[](https://github.com/gangelo/simple_command_dispatcher/issues)
[](#license)
# Q. simple_command_dispatcher - what is it?
# A. It's a Ruby gem!!!
## Overview
-__simple_command_dispatcher__ (SCD) allows you to execute __simple_command__ commands (and now _custom commands_ as of version 1.2.1) in a more dynamic way. If you are not familiar with the _simple_command_ gem, check it out [here][simple-command]. SCD was written specifically with the [rails-api][rails-api] in mind; however, you can use SDC wherever you would use simple_command commands.
+__simple_command_dispatcher__ (SCD) allows you to execute __simple_command__ commands (and now _custom commands_ as of version 1.2.1) in a more dynamic way. If you are not familiar with the _simple_command_ gem, check it out [here][simple-command]. SCD was written specifically with the [rails-api][rails-api] in mind; however, you can use SDC wherever you would use simple_command commands.
## Update as of Version 1.2.1
### Custom Commands
SCD now allows you to execute _custom commands_ (i.e. classes that do not prepend the _SimpleCommand_ module) by setting `Configuration#allow_custom_commands = true` (see the __Custom Commands__ section below for details).
@@ -27,35 +27,35 @@
Command classes (and the modules they reside under) are named *__according to their file name and respective location within the above folder structure__*; for example, the command class defined in the `/api/my_app1/v1/authenticate_request.rb` file would be defined in this manner:
-```ruby
+```ruby
# /api/my_app1/v1/authenticate_request.rb
-module Api
- module MyApp1
- module V1
- class AuthenticateRequest
- end
- end
- end
+module Api
+ module MyApp1
+ module V1
+ class AuthenticateRequest
+ end
+ end
+ end
end
```
-
+
Likewise, the command class defined in the `/api/my_app2/v2/update_user.rb` file would be defined in this manner, and so on:
-```ruby
+```ruby
# /api/my_app2/v2/update_user.rb
-module Api
- module MyApp2
- module V2
- class UpdateUser
- end
- end
- end
+module Api
+ module MyApp2
+ module V2
+ class UpdateUser
+ end
+ end
+ end
end
```
The __routes used in this example__, conform to the following format: `"/api/[app_name]/[app_version]/[controller]"` where `[app_name]` = the _application name_,`[app_version]` = the _application version_, and `[controller]` = the _controller_; therefore, running `$ rake routes` for this example would output the following sample route information:
@@ -79,12 +79,12 @@
=begin
# Uncomment this code if you want to namespace your commands in the following manner, for example:
#
# class Api::MyApp1::V1::AuthenticateRequest; end
#
-# As opposed to this:
-#
+# As opposed to this:
+#
# module Api
# module MyApp1
# module V1
# class AuthenticateRequest
# end
@@ -136,14 +136,14 @@
# Optionally set our configuration setting to allow
# for custom command execution.
SimpleCommand::Dispatcher.configure do |config|
config.allow_custom_commands = true
-end
+end
```
-```ruby
+```ruby
# /app/controllers/application_controller.rb
require 'simple_command_dispatcher'
class ApplicationController < ActionController::API
@@ -152,29 +152,29 @@
protected
def get_command_path
# request.env['PATH_INFO'] could return any number of paths. The important
- # thing (in the case of our example), is that we get the portion of the
- # path that uniquely identifies the SimpleCommand we need to call; this
+ # thing (in the case of our example), is that we get the portion of the
+ # path that uniquely identifies the SimpleCommand we need to call; this
# would include the application, the API version and the SimpleCommand
# name itself.
command_path = request.env['PATH_INFO'] # => "/api/[app name]/v1/[action]”
command_path = command_path.split('/').slice(0,4).join('/') # => "/api/[app name]/v1/"
end
private
-
+
def authenticate_request
# The parameters and options we are passing to the dispatcher, wind up equating
# to the following: Api::MyApp1::V1::AuthenticateRequest.call(request.headers).
- # Explaination: @param command_modules (e.g. path, "/api/my_app1/v1/"), in concert with @param
- # options { camelize: true }, is transformed into "Api::MyApp1::V1" and prepended to the
+ # Explaination: @param command_modules (e.g. path, "/api/my_app1/v1/"), in concert with @param
+ # options { camelize: true }, is transformed into "Api::MyApp1::V1" and prepended to the
# @param command, which becomes "Api::MyApp1::V1::AuthenticateRequest." This string is then
# simply constantized; #call is then executed, passing the @param command_parameters
# (e.g. request.headers, which contains ["Authorization"], out authorization token).
- # Consequently, the correlation between our routes and command class module structure
+ # Consequently, the correlation between our routes and command class module structure
# was no coincidence.
command = SimpleCommand::Dispatcher.call(:AuthenticateRequest, get_command_path, { camelize: true}, request.headers)
if command.success?
@current_user = command.result
else
@@ -189,11 +189,11 @@
As of __Version 1.2.1__ simple_command_dispatcher (SCD) allows you to execute _custom commands_ (i.e. classes that do not prepend the _SimpleCommand_ module) by setting `Configuration#allow_custom_commands = true`.
In order to execute _custom commands_, there are three (3) requirements:
1. Create a _custom command_. Your _custom command_ class must expose a public `::call` class method.
2. Set the `Configuration#allow_custom_commands` property to `true`.
- 3. Execute your _custom command_ by calling the `::call` class method.
+ 3. Execute your _custom command_ by calling the `::call` class method.
### Custom Command Example
#### 1. Create a Custom Command
```ruby
@@ -203,20 +203,20 @@
module MyApp
module V1
# This is a custom command that does not prepend SimpleCommand.
class CustomCommand
-
+
def self.call(*args)
command = self.new(*args)
if command
command.send(:execute)
else
false
end
end
-
+
private
def initialize(params = {})
@param1 = params[:param1]
end
@@ -243,11 +243,11 @@
# In your rails, rails-api app, etc...
# /config/initializers/simple_command_dispatcher.rb
SimpleCommand::Dispatcher.configure do |config|
config.allow_custom_commands = true
-end
+end
```
#### 3. Execute your _Custom Command_
Executing your _custom command_ is no different than executing a __SimpleCommand__ command with the exception that you must properly handle the return object that results from calling your _custom command_; being a _custom command_, there is no guarantee that the return object will be the command object as is the case when calling a SimpleCommand command.
```ruby
@@ -255,11 +255,11 @@
require 'simple_command_dispatcher'
class SomeController < ApplicationController::API
public
-
+
def some_api
success = SimpleCommand::Dispatcher.call(:CustomCommand, get_command_path, { camelize: true}, request.headers)
if success
# Do something...
else
@@ -304,6 +304,5 @@
The gem is available as open source under the terms of the [MIT License](http://opensource.org/licenses/MIT).
[simple-command]: <https://rubygems.org/gems/simple_command>
[rails-api]: <https://rubygems.org/gems/rails-api>
-