Project organization

Project Organization

A couple notes on how Instrumental assumes your project to be organized:

app/views/shared/components

This folder is where all of the components' ERB partials. If it's in the "components" folder, it's considered a "component" and that means it's intended to be used (and re-used) globally across various areas of the project. As such, we want to lean more heavily on local variables, and avoid hard-coding too much or placing content that's specific to one instance of this component.

Take the dropdown component, for example. It's made up of 2 partials located inside the components folder: _dropdown.html.erb and _dropdown_link.html.erb. We wouldn't want to hard code a link that points to a specific page here. We'd want to render the dropdown partial anytime we need a dropdown, and in its' yield block, render each dropdown_link.

app/javascript/controllers/components

As usual, all StimulusJS controllers reside inside the app/javascript/controllers folder.

Instrumental installs its component-specific stimulus controllers inside the components namespace. So when calling the toggle controller, for example, we use: components--toggle . Similar to the views/shared/components folder, the thinking here is:

ERB Partials

Instrumental is built with many ERB partials (files that begin with _).

In most of them, at the top of the partial file, you will find the list of all local variables that might be used in instances of this partial. Most of these are optional. Some have default values if the variable is not set.

Many local variables are used for customizing TailwindCSS classes on elements within the partial. Some general patterns here:

• Specific styles are split out to separate local variables. For example, you might want to customize the text-size, but want to leave the rest of the styles (color, weight, padding, etc.) to their default values. Using many, style-specific, local variables makes this fine-grained level of customization possible.
• Local variable names lean towards more descriptive names, to distinguish exactly which element or attribute they control.
• Typically there is also a more general "…classes" local_variable, placed after all of the style-specific variables. You can throw any/all additional custom classes here.
• Most elements in ERB partials accept a local_variable named data. Use this just like you would in any other tag to apply data attributes to the element.

Routes

Many components will add new routes to your config/routes.rb file. You might notice a somewhat unusual approach here:

Some components make use of Rails routes helpers. For example, when you use Instrumental Scaffolds, it will add a resources route for the newly added resource, which adds RESTful routes for the resource.

However, many other components simply add single line routes, with custom paths and names. These are neatly grouped with commented headlines to help you read and organize. Brian's reasoning for this is to allow for more fine-grain control over the path structures and naming conventions used in your project. That makes navigating your app easier for users and maintaining your project easier for you and your team.

Rails conventions

In addition to views, partials, and Stimulus controllers, Instrumental Components adds and inserts many other files into your codebase. These aim to follow Ruby on Rails conventions as closely as possible.

Depending on the component, you'll find any of the following added to your project:

• Routes
• Controllers
• Models
• Migrations
• Mailers
• Initializers
• Helpers
• ...