README.md in tramway-0.2.3 vs README.md in tramway-0.3

@@ -1,8 +1,15 @@
 # Tramway
 Unite Ruby on Rails brilliance. Streamline development with Tramway.
 
+* [Installation](https://github.com/Purple-Magic/tramway#installation)
+* [Usage](https://github.com/Purple-Magic/tramway#usage)
+  * [Tramway Entities](https://github.com/Purple-Magic/tramway#tramway-entities)
+  * [Tramway Decorators](https://github.com/Purple-Magic/tramway#tramway-decorators)
+  * [Tramway Form](https://github.com/Purple-Magic/tramway#tramway-form)
+  * [Tramway Navbar](https://github.com/Purple-Magic/tramway#tramway-navbar)
+
 ## Installation
 Add this line to your application's Gemfile:
 
 ```ruby
 gem "tramway"
@@ -41,14 +48,10 @@
     { name: :episodes, route: { namespace: :podcasts, route_method: :episodes } }, # `podcasts_episodes_path` link in the Tramway Navbar
   ]
 end
 ```
 
-### Tailwind components
-
-Tramway uses [Tailwind](https://tailwindcss.com/) by default. All UI helpers are implemented with [ViewComponent](https://github.com/viewcomponent/view_component).
-
 ### Tramway Decorators
 
 Tramway provides convenient decorators for your objects. **NOTE:** This is not the decorator pattern in its usual representation.
 
 *app/controllers/users_controller.rb*
@@ -95,10 +98,156 @@
 def show
   @user = tramway_decorate User.find(params[:id]), decorator: Users::ShowDecorator
 end
 ```
 
+### Tramway Form
+
+Tramway provides **convenient** form objects for Rails applications. List properties you want to change and the rules in Form classes. No controllers overloading.
+
+*app/forms/user_form.rb
+```ruby
+class UserForm < Tramway::BaseForm
+  properties :email, :password, :first_name, :last_name, :phone
+
+  def password=(value)
+    object.password = value if value.present?
+  end
+end
+```
+
+**Controllers without Tramway Form**
+
+*app/controllers/users_controller.rb*
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = User.new
+    if @user.save user_params
+      render :show
+    else
+      render :new
+    end
+  end
+
+  def update
+    @user = User.find params[:id]
+    if @user.save user_params
+      render :show
+    else
+      render :edit
+    end
+  end
+  
+  private
+
+  def user_params
+    params[:user].permit(:email, :password, :first_name, :last_name, :phone)
+  end
+end
+```
+
+**Controllers with Tramway Form**
+
+*app/controllers/users_controller.rb*
+```ruby
+class UsersController < ApplicationController
+  def create
+    @user = tramway_form User.new
+    if @user.submit params[:user]
+      render :show
+    else
+      render :new
+    end
+  end
+
+  def update
+    @user = tramway_form User.find params[:id]
+    if @user.submit params[:user]
+      render :show
+    else
+      render :edit
+    end
+  end
+end
+```
+
+#### Implement Form objects for any case
+
+*app/forms/user_updating_email_form.rb*
+```ruby
+class UserUpdatingEmailForm < Tramway::BaseForm
+  properties :email
+end
+```
+
+*app/controllers/updating_emails_controller.rb*
+```ruby
+def update
+  @user = UserUpdatingEmailForm.new User.find params[:id]
+  if @user.submit params[:user]
+    # success
+  else
+    # failure
+  end
+end
+```
+
+#### Create form namespaces
+
+*app/forms/admin/user_form.rb*
+```ruby
+class Admin::UserForm < Tramway::BaseForm
+  properties :email, :password, :first_name, :last_name, :etc
+end
+```
+
+*app/controllers/admin/users_controller.rb*
+```ruby
+class Admin::UsersController < Admin::ApplicationController
+  def create
+    @user = tramway_form User.new, namespace: :admin
+    if @user.submit params[:user]
+      render :show
+    else
+      render :new
+    end
+  end
+
+  def update
+    @user = tramway_form User.find(params[:id]), namespace: :admin
+    if @user.submit params[:user]
+      render :show
+    else
+      render :edit
+    end
+  end
+end
+```
+
+### Make flexible and extendable forms
+
+Tramway Form properties are not mapped to a model. You're able to make extended forms.
+
+*app/forms/user_form.rb*
+```ruby
+class UserForm < Tramway::BaseForm
+  properties :email, :password, :full_name
+
+  # RULE: in case password is empty, don't save
+  def password=(value)
+    object.password = value if value.present?
+  end
+
+  # EXTENDED FIELD: full name
+  def full_name=(value)
+    object.first_name = value.split(' ').first
+    object.last_name = value.split(' ').last
+  end
+end
+```
+
 ### Tramway Navbar
 
 Tramway provides DSL for rendering Tailwind Navgiation bar.
 
 ```ruby
@@ -160,9 +309,13 @@
     #   </a>
     # </li>
   end
 end
 ```
+
+### Tailwind components
+
+Tramway uses [Tailwind](https://tailwindcss.com/) by default. All UI helpers are implemented with [ViewComponent](https://github.com/viewcomponent/view_component).
 
 ## Contributing
 
 Install [lefthook](https://github.com/evilmartians/lefthook)