Conventions¶ ↑

This guide goes over conventions for directory layout and file layout for Roda applications. You are free to ignore these conventions, they mostly exist to help users who are unsure how to structure their Roda applications.

Directory Layout¶ ↑

Which directory layout to use should reflect the size of your application.

Small Applications¶ ↑

For a small application, the following directory layout is recommended:

Rakefile
app_name.rb
assets/
config.ru
db.rb
migrate/
models.rb
models/
public/
spec/
views/

app_name.rb should contain the Roda application, and should reflect the name of your application. So, if your application is named FooBar, you should use foo_bar.rb.

config.ru should contain the code the webserver uses to determine which application to run.

views/ should contain your template files. This assumes you are using the render plugin and server-side rendering. If you are creating a single page application and just serving JSON, then you won’t need a views directory. For small applications, all view files should be in the views directory.

public/ should contain any static files that should be served directly by the webserver. Again, for pure JSON applications, you won’t need a public directory.

assets/ should contain the source files for your CSS and javascript assets. If you are not using the assets plugin, you won’t need an assets directory.

db.rb should contain the minimum code to setup a database connection, without loading any of the applications models. This can be required in cases where you don’t want the models loaded, such as when running migrations. This file should be required by models.rb.

models.rb should contain all code related to your ORM. This file should be required by app_name.rb. This keeps your model code separate from your web code, making it easier to use outside of your web code. It allows you to get an IRB shell for accessing your models via irb -r ./models, without loading the Roda application.

models/ should contain your ORM models, with a separate file per model class.

migrate/ should create your database migration files, if you are using an ORM that uses migrations.

spec/ (or test/ should contain your specifications/tests. For a small application, it’s recommended to have a single file for your model tests, and a single file for your web/integration tests.

Rakefile should contain the rake tasks for the application. The convention is that the default rake task will run all specs/tests related to the application. If you are using the assets plugin, you should have an assets:precompile task for precompiling assets.

Large Applications¶ ↑

Large applications generally need more structure:

Rakefile
app_name.rb
assets/
helpers/
migrate/
models.rb
models/
public/
routes/
 prefix1.rb
 prefix2.rb
spec/
 models/
 web/
views/
 prefix1/
 prefix2/

For larger apps, the Rakefile, assets/, migrate, models.rb, models/, public/, remain the same.

app_name.rb should use the hash_branch_view_subdir plugin (which builds on the hash_branches and view_options plugin), or the multi_run plugin. The routes used by the hash_branches or multi_run should be stored in routing files in the routes/ directory, with one file per prefix.

For specs/tests, you should have spec/models/ and spec/web/, with one file per model in spec/models/ and one file per prefix in spec/web/. Substitute spec with test if that is what you are using as the name of the directory.

You should have a separate view subdirectory per prefix. With the hash_branch_view_subdir, the application will automatically set a separate view subdirectory per routing tree branch.

helpers/ should be used to store helper methods for your application, that you call in your routing files and views. In a small application, these methods should just be specified in app_name.rb

Really Large Applications¶ ↑

For very large applications, it’s expected that there will be deviations from these conventions. However, it is recommended to use the hash_branch_view_subdir or multi_run plugins to organize your application, and have subdirectories in the routes/ directory, and nested subdirectories in the views/ directory.

Roda Application File Layout¶ ↑

Small Applications¶ ↑

For a small application, the convention in Roda is to layout your Roda application file (app_name.rb) like this:

require 'roda'
require_relative 'models'

class AppName < Roda
  SOME_CONSTANT = 1

  use SomeMiddleware

  plugin :render, escape: true
  plugin :assets

  route do |r|
    # ...
  end

  def view_method
    'foo'
  end
end

You should first require roda and ./models, followed by any other libraries needed by the application.

You should subclass Roda and make the application’s name the name of the Roda subclass. Inside the subclass, you first define the constants used by the application. Then you add any middleware used by the application, followed by loading any plugins used by the application. Then you add the route block for the application. After the route block, define the instance methods used in your route block or views.

Large Applications¶ ↑

For larger applications, there are some slight changes to the Roda application file layout:

require 'roda'
require_relative 'models'

class AppName < Roda
  SOME_CONSTANT = 1

  use SomeMiddleware

  plugin :render, escape: true, layout: './layout'
  plugin :assets
  plugin :hash_branch_view_subdir
  Dir['routes/*.rb'].each{|f| require_relative f}

  route do |r|
    r.hash_branches('')

    r.root do
      # ...
    end
  end

  Dir['helpers/*.rb'].each{|f| require_relative f}
end

After loading the hash_branch_view_subdir plugin, you require all of your routing files. Inside your route block, instead of defining your routes, you just call r.hash_branches, which will dispatch to all of your routing files. After your route block, you require all of your helper files containing the instance methods for your route block or views, instead of defining the methods directly.