How it works

Instrumental Components works a little differently than a typical "Starter Kit" or "Boilerplate" Ruby on Rails app. It's designed with the following goals in mind:

• Allow you to install individual components on an as-needed basis
• Components are highly customizable, while being re-useable across your codebase and other projects
• Install component files directly into your codebase, so that you can easily customize and adapt them to the needs of your project.

The recommended approach is to install the gem and then install the components you need. But if a ready-made Boilerplate app is more your style, then you can use the Starter Kit, which gives you a full Rails app with all Instrumental Components pre-installed.

Installing components

To install any component, use a variation of the following command, where component_name is the name of the component you want to install:

rails g instrumental:component_name

You will find the exact command for each component documented here in the docs.

When you run any component generator, your terminal will output the entire installation process, which generally follows these steps:

1. First, it will show an overview, which lists the component plus other dependent components that will be installed. You will be asked to confirm and proceed with installation.
2. Then it will install each of the components, one by one (only the ones you don't already have installed).
3. Finally, it will display a detailed recap, which lists all of the files that have been added or updated, along with any new routes, migrations, or gems that were added into your codebase.

Some components include some questions for you to answer or confirm as part of the installation process.

In addition to the recap you see in the terminal, the same recap (and more) for each component's installation is saved to a log file in .instrumental/component_installation_logs. Learn more about logs here.

Components work together

The beauty of designing and building Rails applications with components is that your components work together, often depending on and interacting with one another.

A simple example of this is the Forms component: When you display a form, that typically includes the form's fields, plus a submit button. So in order to display a form, you'd need both the Forms component and the Buttons component.

The Authentication component is another example of this. Authentication is a complex component, which includes many other components, including the Forms component, Buttons component, Avatars component, and more.

Using (and customizing) components

Most components consist of anywhere from one to many files. These include views, controllers, models, Stimulus JS controllers, and more.

Views, and more typically, ERB partials, are where the majority of the "action" happens when you're building with components. You'll find most of the component ERB partials in the app/views/shared/components folder.

Open up any component's ERB partial(s), and right at the top, you'll see a list of all of the local variables (:local_assigns) that are available to be passed into this partial. This list serves 2 purposes:

• Treat it like your reference guide for this component.
• The extensive list of local variables is designed to give you as much customization abilities as possible.

The aim is to avoid needing to customize or change any code in the component's files itself, since they're intended to be re-used across your project.

But if you do want to customize a component's underlying code, you can! But if you do, you'll need to be take some extra care if/when updating to newer versions of Instrumental Components... Which brings us to...

Preventing overwrites

First, you should rest assured that when you run any component generator, by default:

• If this component, or any of its dependent components, are already present in your codebase, it will not re-install or overwrite them. It will let you know that you already it.
  • If you include the --update flag in your command, then it will overwrite the main component, even if you already have it.
  • If you include the --update_all flag in your command, then it will overwrite the main component, plus all of its' dependent components, even if you already have them.

You can also add any file in your codebase to your "Prevent Overwrites" list, located in your config/instrumental.yml file. This will ensure that if/when you even re-run that component's generator, it will not overwrite your custom version of that file (even if you've included the --update or --update_all flag).

Note: That means that these files will be skipped during a component's installation process. So if you need to get released by Instrumental Components, but you've also made some customizations and you're preventing overwrites for a particular file, then you can take a look at the Starter Kit repo to see the latest "clean" version of all files for all components.

Code insertions

Some components include some "code insertions", where bits of code need to be injected into existing files, while keeping their existing code intact.

For example, some components add methods to application_controller.rb, application_helper.rb, among other files.

As always, your component installation recaps as well as the installation log files will list exactly which files received code insertions, so that you can review them and make any adjustments as needed.