Ruby rails: overview

Overview Diagram

# https://example.com/my_controller/action_1
#
#   routes:       {project}/config/routes.rb
#   controllers:  {project}/app/controllers/my_controller.rb
#   views:        {project}/app/views/my_controller/action_1.html.erb
#   models:       {project}/app/models/users_model.rb

         +---------------------------------------------------------------------------------------------+
         |                                                                                             |
         |                                                                                             |
         |                             +->  MyController.action_1()  ---> action_1.html.erb  \         |
         \/                           /                                                       \        |
                                     /                                                         \       |
(user-clicks-link) -->  url-routes -+-----> MyController.action_2()  ---> action_2.html.erb  ---+------+
                                     \                                                         /
                                      \                                                       /
                                       +->  MyController.action_3()  ---> action_3.html.erb  /

                                               |     /\
                                               |      |
                                               |      |
                                               +      +
                                                \    /
                                                 \  /
                                                  \/
                        
                                        UserModel    GroupModel
                                          |  /\       |  /\ 
                                          |  |        |  |  
                                          \/ |        \/ |  
                        
                                 +-----------------------------------+
                                 |                                   |
                                 |             Database              |
                                 |                                   |
                                 +-----------------------------------+

• request - an HTTP request is made from a browser
• routing decides which controller gets receives http-request (often multiple routes point to the same controller)
• actions are methods on controller-classes. They collect info from models and provide it to a view.
• models represent database tables/table-row info.
• views are html files, pre-processed with variables provided by controllers/actions.

Intro to Environments

Rails configuration is divided into environments (3x by default).
Secrets, database data, etc. can be configured differently for each of these environments.
In a default rails project, there are 3:

• production
• testing
• development

# Check current environment
Rails.env == "production"

# Set rails environment
env RAILS_ENV=testing rails console

How to Read Documentation

binding.pry

If you are writing new code, binding.pry is the fastest path to development.

Use ls to list available methods/constants (categorized by source), and show-source -ld <method> to show the docs/method-signature.

I also highly recommend the pry-rails extension, which adds useful helpers like show-models and show-routes.

Overview Documentation

The overview documentation is excellent, start here. It has the easiest to follow documentation, and goes into a fair amount of detail.

API Documentation

If you know the namespace you are working with, the API documentation begins

Each toplevel rails namespace includes an overview within it's API documentation.
This is really useful.

The digging through the API is confusing, a table-of-contents would be very useful. Generally, the top of each module has an overview (several headers), and the bottom of the file contains standardized headers (namespace, methods, included modules, etc).

Important Headers
Namespace	other modules/classes/etc within the same namespace as class
Methods	public methods
Class Public Methods	class methods
Instance Public Methods	methods defined on the instance?