Reusable components for your rails frontend

Living Styleguide with Mountain View

Living Styleguide for Rails with Mountain View

Working in a growing team requires frameworks and libraries that make the communication between different parties of the development team easier. To enable developers and designers alike to work simultaneously on a project, a living styleguide can be of great help.

CodingLisa Schmitz –
18 August 2017

Such a styleguide is a documentation of the view and view elements used in an application. It is living in a sense, that all the changes made to the application's style are immediately represented in the styleguide pages. Even better, a good styleguide can become the designers' workplace, where it is possible to create and style view components independently of the project logic. An interface to the components allow the programmer to add custom content and reuse the components in a flexible way. We in zauberware were looking for such a styleguide and our choice fell on Mountain View. It seemed to fulfill the requirements of working well together with Rails and supporting component oriented design. In this article I will dive into the structure of Mountain View's file organization, how to include them into the existing rails project and what else there has to be taken care of.

File structure

The Mountain View components can be found in their own directory in the app folder, called components.

│─ app # app root
│ │─ components # all mountain view components

This is the place where the components' html and style live. The view components that can be found here are available everywhere in the application views.

Generating a component

As a simple example component I will use the profile image thumb created for the reflecta network website. In order to create the component and the necessary files, it is enough to enter $ rails generate mountain_view:component profile_thumb in the console. This command will generate the following files:

│─ app
│ │─ components
│ │ │─ _profile_thumb.html.erb # html view for the profile thumb
│ │ │─ _profile_thumb.js # if javascript is needed for the component to work, then here is its place
│ │ │─ _profile_thumb.sass # style for the html element, style that is defined here applies only to this component
│ │ │─ _profile_thumb.yml # contains the properties that will be inserted into the styleguide view, the file is only relevant for the styleguide
│ │ │─ _profile_thumb_component.rb # defines the permitted properties of the component, has to be created manually

One additional file should be created, called profile_thumb_component.rb. In this file, properties that are needed for the component e.g the link to the profile thumb image can be specified.

Template (_profile_thumb.html.erb)

The _profile_thumb.html.erb contains the html to display the component. In the example case it would be

Most of this snippet is common html while the <%= ... %> tag signals, that some ruby is used here. We need this, because every user should get an individual profile picture accessed through a unique url. However, we only show the content of the property variables. As this area is for the designer, ruby code should only be used to access the properties and nothing else. This is not the place for backend logic. The logic that is needed for the view should be defined outside of the component whenever possible. The parts of the html view that should be represented as a property are all dynamic elements like the user name.

Styling (profile_thumb.sass)

The profile_thumb.sass file contains the style that is relevant only for the profile thumb component. If nowhere else included, the css here only applies to the html in the component. I can create a fancy style for the html <body> in this file, but even if the component is later part of a site that features the <body> - no style from this file will leave the component's html. This keeps the framework modular and reusable. For the profile thumb image we use the following code in the profile_thumb.sass:

As we can see, the profile_thumb.sass only contains relevant css for the profile thumb component. Well, except from importing the entire index file, one could argue. But if the entire views are set up as components, the only thing that should be included in the index is some universal style like variable definitions. Those are needed here to access e.g. $baseSize.

Javascript (_profile_thumb.js)

Related javascript finds its place here in order to add animation or other style specific code. The profile image does not need animation so this file stays empty for this component.

Sample data and config (_profile_thumb.yml)

This is where the designer can define sample properties to fill the component skeleton. This file is only for the presentation of the component in the styleguide, nothing in here is used in the actual application views. But working on the design for the profile image thumb is much better with a nice image as a placeholder instead of just a blank area. Therefore, the styleguide needs some input for the properties of the component, in this case the image url. This can be any url to a sufficient image file, in our component's case, we use '/assets/team/the-designer.jpg'. To define this in the yml file, those lines here are enough:

-
:img_url: '/assets/team/jannis-borgers.jpg'

Make sure not to forget the hyphen, the indentation or any of the two colons. The hyphen here indicates that this is the first instance of this component in the styleguide. Maybe it would also be good for the designer to see how the profile img style works together with the default img. Then this can be added as a second example as easy as this:

Now the only part left is to declare which parameters we want in the ruby file.

Declaration in rails (_profile_thumb_component.rb)

This file has space for some addtional modifications of the properties, before they are processed e.g. capitalization. But that is mostly uninteresting for the designer's part. The only important lines for this file are

This declares the profile thumb component which takes the properties :img_url. And thats it. Now Mountain View knows enough to display the component. We can admire the new component in the styleguide under the url: /mountain_view/styleguide/profile_thumb - at least thats what we hope for. Instead there might be an information saying: "Hint:To see your component make sure you've created stubs: ... " This might be a good moment to restart the server. This is needed to register the component properly. But after that you are good to go and changes in the files should be visible after refreshing.

Preview of styleguide

How to use the component in rails

What is left now is the integration of the component in the rails views which is more interesting for the programmer. This is as easy as rendering a partial with the following command:

And that are all the basics! More information about yielding content, extra pages and more can be found on the Mountain View github page. But before we come to the end, just one more thing:

<%= properties[:img_url] %> over <%= :img_url %>

One thing that you might notice when you compare this articles code to the documentation from Mountain Views github repository is, that the properties given to the view are referenced in two different ways. In this article I said that the <img> tag should look like the following <img src='<%= properties[:img_url] %>'/>, while according to the Mountain View documentation it should look more like this: <img src='<%= img_url %>'/>. The reason that I came to prefer the longer version is the following: it might be that we already created the variable img_url in our routes. Maybe something like img_url/:id gives us the profile images associated with the user with the given id. If this is the case then <img src='<%= img_url %>'/>, instead of trying to access the property, will try to call the path that is specified as a route. Which will most likely lead to an error. Since I think that the mountainview styleguide area should be mostly for the designer and therefore the naming of those properties can be the designers choice, we should try to avoid confusion with rails code from the backend. Calling properties[:img_url] prevents any such confusion and should - in my opinion - therefore be prefered.