Adding a search feature is so commonplace that it's almost essential for any modern Rails application (or any app, really). So of course, it's a component in Instrumental Components!
Since search can be configured in many different ways, there are a few extra steps to getting the Search component installed, compared to other components. Don't worry, it's easy and all the steps are right here:
Note: The search component requires that you're using a PostgreSQL database. Adapting it to work with other databases is possible (you'll have access to all of the files) but out of the box, it's set up to search for records in a PostgreSQL database.
Start by running the installation command for the search component:
rails g instrumental:searchThat will begin by asking for a few bits of information about how you want your search feature to work:
First, it'll ask you to specify the class name of the model you want to search. This is the model that will be searched for records. For example, if you're searching your posts table, which is a Post model, then you'd enter Post.
When your search returns results, each result will be a link that points to a page for that result. Typically that will be the show view for your model.
For example, if we're searching for posts, we likely have a route helper for post_path(post) (yours might be different).
You will only need to specify the search helper path without the parantheses. In our example, we'd enter post_path. The generator will add the `(post) part.
If after installing the search component, you find you need to fix the link path for each search result, you can do so in the file: app/views/search.turbo_stream.erb.
Next, it'll ask you to specify the columns on your table that you want to search. For example, if Posts have a title and excerpt, you can select these columns. The generator will give you a list of existing columns on your table to choose from (you can add several searchable columns).
Oftentimes, your primary model has a relationship with other models, which have content that should be searchable when searching the primary model.
Sticking with our Post example, a post often has content, served using Rails' ActionText. In this case, your post.rb model would have something like this in it: has_rich_text :content. Since 'content' is not a column on the posts table, but rather a column in the ActionText table, you'll need to follow the prompts to specify that this is a Rich Text association and it's name is 'content'. That will take care of making posts' content searchable.
You can add other associated models as well. For example, lets say you have a Tags model, and each post has many tags. You can follow the prompts to add your Tag model as an associated model and its column name to be searchable. Now you can search for posts and if the query is in a post's tag name, then it will be found.
If after installing the search component, you find you need to further customize your search scopes, you can do so in the file: app/controllers/search_controller.rb.
The last bit of information that you'll need to provide is the title for each search result. Typically this would be the title (or name) of the model. Select the column that contains the title of the model that's being searched.
Optionally, you can display small text below the title for each search result. This might be a description or the created_at date or something else. If you want to display this text, then select the column to display as the "description" for each search result.
After installation, you can further refine and customize your search results, including displaying icons or avatars or other information, using the many customization variables built into: app/views/search/_search_result.html.erb, which is called from app/views/search/search.turbo_stream.erb.
After completing the installation process above, your search feature won't yet be available in your app's views. To complete the installation, you'll need to add it to the layout(s) that power any pages where you want the search to be available.
<body> tagOpen your layout file (typically app/views/layouts/application.html.erb) and make sure your <body> tag has the following requireed attributes for the search component to work:
<body data-controller="mobile-nav components--search"
data-action="keydown->components--search#keyboardLaunch">If you're using any Instrumental layout, then <body> tag will have some other stuff in it, and look more like this:
<body class="instrumental-layout h-full group/sidebar"
data-controller="mobile-nav components--search"
data-mobile-nav-open-value="false"
data-action="keydown->components--search#keyboardLaunch">Finally, in order to launch your search modal popup, that search modal partial needs to be included in your layout.
Add this line somewhere in your layout:
<%= render "search/search" %>Restart your server.
At this point, you should be able to launch the search modal using the keyboard shortcut, /.
You might also want to add a link or icon that a user can click to launch the search modal, rather than relying solely on the keyboard shortcut.
Add the following snippet of code somewhere in your layout. If using a Instrumental layout, then a good place for it would be in the app/views/layouts/application/_top.html.erb file (see the video above for details).
<div class="hidden lg:block cursor-pointer text-gray-400 dark:text-gray-600
hover:text-gray-600 dark:hover:text-gray-400"
data-action="click->components--search#launch">
<%= icon("search") %>
</div>The front-end UI for the search feature is handled primarily in the StimulusJS controller, app/javascript/controllers/components/search_controller.js.
Out of the box, it provides the following functionality:
/ (or by clicking a link)
/ to launch the search modal is ignored if the user is currently focusing any input field on a page.esc
I created Instrumental Components to make designing and building professional apps with Ruby on Rails easy, fast, and fun. I use it on all of my projects and I hope it helps you build something great.
