In this codelab we are going to learn how to navigate the Shopify codebase by adding a working controller and view to the admin in your development environment.
Basic knowledge
- Basic understanding of Rails
- Basic understanding of Ruby
- Basic understanding of git and github, see Making your first PR
- Have your Shopify development environment set up, see Making your first PR
Installed on your machine:
- Web browser
- Code editor, see recommended tools
- Shopify codebase
Before we dive in let's take a look around the code base and get our bearings first.
- Navigate and open up the Shopify project in your editor. Ensure that you have run
dev up
. - If you look at the root folder you should see a list of folders that looks like this:
app/
bin/
borg/
buildkite/
ci/
config/
db/
eagerlib/
lib/
log/
node_modules
private/
public/
script/
test/
tmp/
vendor/
- Drilling into the app directory we see more of Shopify itself:
app/
assets/
controllers/
admin/
api/
concerns/
customers/
services/
styleguide/
experiments/
exporters/
helpers/
jobs/
liquid/
mailers/
middleware/
models/
presenters/
serializers/
services/
tasks/
validators/
views/
admin/
carts/
checkouts/
services/
...
wolverine/
bin/
borg/
buildkite/
ci/
config/
routes.rb
db/
Explanation:
- app/models: This is where all domain classes live. They are usually
ActiveRecord::Base
subclasses (classes that interact with the databases). - app/controllers: This is where the controller classes live. These handle loading and presenting the data for a request. Controllers are further organized by area such as admin, customers, services etc.
- app/views: These are the html (or html.erb to be more specific) views for the controller actions. These are organized in a similar manner as the controllers.
- config/routes.rb: This is the file that is responsible for linking the incoming request to the controller that will serve it. See the tracing a shopify request codelab for more details on request routing.
There are a lot more files and directories within the project, but these give you an overview of some of the core aspects to a Rails application.
Next we are going to start adding our controller to Shopify.
- Create a file named
magic_controller.rb
inapp/controllers/admin/
. - Within that file paste the following code:
class Admin::MagicController < AdminAreaController
layout 'admin/admin'
def index
end
end
Explanation:
- We are adding our controller within the admin directory since we want it accessible from the admin.
- We namespace the controller name with
Admin::
and the class name matches the file name in CamelCase. - The controller subclasses
AdminAreaController
so that we get admin behaviors baked in such as authentication, access control, error handling etc. - The
layout
call specifies which layout the actions should be rendered within.
- Open the
config/routes.rb
file. This is where we specify which controllers requests are routed to. - Near the top of this file we are loading
config/routes/admin.rb
. The route file has been broken up and the admin routes are there. Open that file. - When adding a new route you should try and group it with anything related. In this case we will add it to the top for simplicity sake. Modify the admin.rb routes file to add the resource for our magic controller:
Rails.application.routes.draw do
routing_method :shop_from_host do
namespace :admin, defaults: { protocol: 'https://' } do
[404, 403, 422, 500].each do |code|
get code.to_s => "errors#error_#{ code }"
resources :magic # add this line
# ...
end
# ...
end
- Start your Rails server by opening the Shopify project in terminal and run the command
dev server
. - Open up your browser and navigate to https://shop1.myshopify.io/admin/magic and log into the admin using the default account (user: dev@shopify.com password: password) or authenticate via https://shop1.myshopify.io/admin/staff. This is what you see: .
Explanation:
- When we loaded that page we can see that it is routing to the correct controller, but it doesn't have a view template file to render.
- In the routes we are adding our route to the
magic
resource within theadmin
namespace so that it shows up there.
- Add the view template to be rendered
app/views/admin/magic/index.html.erb
and add some html to it:
<p>Magic Page</p>
Explanation:
- Rails operates by convention so it knows to look for a controllers views under a directory with the same name in the
app/views
directory, e.g.app/views/admin/magic/
. - By default, rails will render the view template with the same name as the controller action that is evaluated,
index.html.erb
here.
We didn't touch on testing, but every feature within Shopify should have tests added. Controller tests should be added to verify the behavior of the controller. Once you make a real change you will want to walk through creating your first pr to learn how to create a pull request and get your code reviewed.
This should set you up with some of the basics for navigating the codebase and start understanding how to work on Shopify. I'd encourage you to explore more of the codebase and notice more conventions and patterns that are used.