App Template #1 - Argon

Argon is our first App Template - a beautiful Bootstrap Dashboard theme integrated with Webpacker and Rails. Get up and running in 5 minutes.

Introducing Argon

Argon is open-source and free for personal and commercial use under the MIT license. Check it out on Github!

Argon is a beautiful Dashboard that will save you weeks of time building your next app.

It includes over 100 components -- charts, tables, cards, navbars, and more. Easily mix, match, and customize components to turn your vision into a reality.

Argon is a Bootstrap theme designed and built by Creative Tim. Our Argon App Template is the marriage of their open-source theme and the Rails Asset Pipeline.

This tutorial will walk you through how to use it:

  • Get it up and running on localhost in minutes
  • Stylesheets
  • Javascript
  • Images
  • Icons
  • Views
  • Customizations and using real data

We believe that small teams (and even individuals) can build amazing products when they're not bogged down by reinventing the wheel.

We're here to help you. With our open source App Templates and step-by-step tutorials, you can skip the mundane boilerplate and fly right into the exciting stuff that'll make your app great.

Up and Running in 5 Minutes

Download Argon and get it running on localhost.

In your terminal, clone the repository to your local filesystem.

-- CODE language-sh --git clone git@github.com:Dino-Saas/Argon.git argon-demo

Now you'll need to take a couple steps to download the latest versions of required Ruby gems and Javascript packages.

First, run bundle install to download the right gems with the right versions (as specified in the Gemfile).

-- CODE language-sh --bundle install

Next, update Yarn packages as specified in package.json.

-- CODE language-sh --yarn install

Now start up your server.

-- CODE language-rb --rails server

Point your browser to http://localhost:3000 and check out your stunning new Rails dashboard!

Diving into the Codebase

Assembling a Rails app is even more complex than assembling IKEA furniture. And just like an IKEA dresser, you shouldn’t have to go at it without instructions.

We’ll walk you through how some of the more important pieces are assembled.

Background Topics

This guide does not attempt to be a deep technical resource on the inner workings of Ruby on Rails. There are plenty of resources online for that, but we’ll try and point you in the right direction when we can.

If you’re unfamiliar with them, it’d be a good idea to read up on the basics of a few topics:

  1. Bootstrap
  2. Sass
  3. Rails Asset Pipeline

Stylesheets

Argon’s stylesheets use Sass. It all starts in the application layout file - application.html.erb. There, we link to our application.scss manifest file: 

-- CODE language-rb --<%= stylesheet_link_tag 'application', media: 'all', 'data-turbolinks-track': 'reload' %> 

application.scss tells Sprockets which stylesheets to include and in what order via @import directives.

We'll walk through how to use these stylesheets to customize your app’s look and feel shortly.

Javascript

Our Javascript journey starts back in application.html.erb. Here, we include our application javascript pack with Webpacker:

-- CODE language-rb --<%= javascript_pack_tag 'application', 'data-turbolinks-track': 'reload' %>

This references our application.js manifest file. Similar to application.scss, application.js contains a sequence of require directives telling Sprockets which files to include and in which order.

argon.js is one of those included files. It has all the custom javascript included with the theme. It’s well commented and broken up by component.

Images

Images can be found in app/assets/images.

We render them using image_tag. This helper method generates the <img> tag that we know and love.

With image_tag, we specify only a relative path from one of the default asset locations that Sprockets knows to look for. For example, you’ll see the following in pages/_sidenav.html.erb:

-- CODE language-rb --<%= image_tag "brand/blue.png", class: "navbar-brand-img", alt: "..." %>

See Section 2.2.1 in the official Rails docs on The Asset Pipeline if you’d like to learn more about how Sprockets loads images and other assets.

When you deploy to production, you'll want to move your images to a Content Delivery Network (CDN) like Cloudfront or Cloudinary. This will force you to use some different helper methods, but will be well worth it to decrease page load times. We’ll go over this more in-depth in a later post.

Icons

Argon is configured to use 2 different sources of icons:

Nucleo Icons

See the Creative Tim docs on icons to see what's available and how to use them. You can also check out icons.html.erb in Argon for plenty of examples like this one:

<i class="ni ni-active-40"></i>

Font Awesome (and the font-awesome-rails gem)

font-awesome-rails lets us include icons using the fa_icon helper method. Check out pages/logged_out/_topnav.html.erb for some examples like this:

-- CODE language-rb --<%= fa_icon 'facebook' %>

FontAwesome has thousands of free and premium icons to choose from on their website.

Views

For simplicity, we’ve organized all our views under a generic pages directory. They all have empty (currently not defined) actions in PagesController. I would not recommend continuing this simplistic pattern when you extend the app for your own purposes.

All views start with the application layout file - application.html.erb. Rails renders the appropriate view file where we call yield in the layout. Read more on layouts here in the Rails docs.

Each view file is further broken up into partials. A partial is a way of dividing up a bigger file into smaller chunks. It avoids having massive files with thousands of lines. More importantly, it allows us to reuse code across different views while only writing it once.

Adding some flair

Customizing the UI

Just because you start from a theme, doesn’t mean you can’t get creative with it!

Bootstrap makes it super easy to style pretty much everything using their included classes. For example, bg-primary sets background-color to blue, while btn-secondary makes your <button> white.

But not everyone wants their site looking like an out-of-the box Bootstrap template. I’m going to walk through how to customize Argon to match our own brand and colors at DinoSaaS.

Bootstrap comes with a _variables.scss file that specifies everything from $primary and $secondary colors to $border-radius and $box-shadow.

These values are used all across the app - we can change values in one place and immediately have global consistency.

We could go directly into the bootstrap source at bootstrap/_variables.scss and modify them there, but I wouldn’t recommend it. Doing this will make it more difficult down the road to update Bootstrap to a future version.

Instead, you’ll want to make changes in custom/_variables.scss. In general, if a property on a class is set twice, the one that is set last overrides the first. However, bootstrap/_variables.scss uses the !default flag - this assigns a value to a variable only if it's not already defined.

So even though custom/_variables.scss is included first in our application.scss manifest, variables that are set there will override the bootstrap defaults.

Changing the color scheme

First, we’re going to make some color changes. We’ll set $primary to “Steel Blue”, the lighter blue color used in most of our copy.

Next, we’re going to change our $default color to “Midnight Blue”, the darker blue used in our home page.

Here’s what some of our pages look like with these new changes:

We changed the background color of the top section to "Steel Blue" and the background color of the "Sales value" chart to "Midnight Blue".
The 2 background colors on the Login page match the new values of $primary and $default as well.

Here are those changes in custom/_variables.scss:

$default: #1f2c3d !default;
$primary: #096ad0 !default;

Updating the logo

The Argon logos are stored in /images/brand - there’s white.png and blue.png.

We’ll replace these files with the DinoSaaS white and blue logos, respectively:


Dashboard with blue logo.
Login page with white logo.

You can see all the changes related to customizing the UI in Pull Request #2.

Still need a logo? This tutorial walks you through how to design your own in 15 minutes using free tools.

Custom Javascript

If you want to extend or remove Javascript code included with the template, edit argon.js.

If you want to add new functionality, I’d suggest starting with new files. In this commit, we’ll add a little greeting that’s sure to inject some user delight into your dashboard experience.

We'll start by adding a new button to the top of the Dashboard. In dashboard.html.erb, we add this button:

<div class="header bg-primary pb-6">
	<div class="container-fluid">
  	<button id="hello" class="btn btn-secondary">Say Hello</button>
    <div class="header-body">
    ...
    </div>
  </div>
</div>

It should look like this:

Dashboard with "Say Hello" button

Next, we’ll hook it up to some Javascript. Create a new demo-app.js file in app/javascript. Here, we’ll add the following code:

-- CODE language-js --$( document ).on('turbolinks:load', function() { $("#hello").click(function() { alert("Hello!"); }); });

Now we'll include the new file in application.js:

-- CODE language-js --require("demo-app.js")

Reload the page. Clicking the “Say Hello” button should show you an alert popup like this:

Clicking the "Say Hello" button brings up this alert.

Why are we listening for the turbolinks:load event?

Great question! By waiting for turbolinks:load to fire, we ensure that the button is rendered before we attach its click handler. See this section in the Rails docs on Turbolinks if you want to learn more.

Using real data

By now, you’re probably thinking, Yea these charts look great, but what am I supposed to do with this fake data?!

Snarkiness aside, you’ve got a point. Next, we’re going to populate the “Page Visits” table with real data from our Rails backend.

We’ll start by creating a PageVisit model. We don't care about tests right now so we don't generate tests or fixtures.

-- CODE language-sh -- rails generate model PageVisit page_name:string visitors:integer unique_users:integer uniques_week_over_week:decimal --no-test-framework --skip-fixture

I've replaced "Bounce Rate" with "Uniques WoW", where "WoW" stands for "week-over-week" - the week-over-week change in unique visitors.

Run rake db:migrate to migrate the database.

-- CODE language-sh --rake db:migrate

Populate the database with some seed data. We’ll use db/seeds.rb. Run rake db:seed to add the new rows to page_visits.

-- CODE language-sh --rake db:seed

Query page_visits in PagesController. We’ll add this in the pages#dashboard action:

-- CODE language-rb --def dashboard @page_visits = PageVisit.all end

We’ll iterate through @page_visits when rendering the “Page Visits” table on pages/dashboard.html.erb. There, we render the table via the _page_visits.html.erb partial:

-- CODE language-rb --<%= render 'pages/dashboard/tables/page_visits' %>

We'll need to send @page_visits as a local variable when rendering the partial. Otherwise, it will be undefined there.

-- CODE language-rb --<%= render partial: 'pages/dashboard/tables/page_visits', locals: { page_visits: @page_visits } %>

Now we can iterate through page_visits in _page_visits.html.erb to populate the table:

<tbody>
	<% page_visits.each do |pv| %>
	<tr>
	  <th scope="row">
	    <%= pv.page_name %>
	  </th>
	  <td>
	    <%= pv.visitors %>
	  </td>
	  <td>
	    <%= pv.unique_users %>
	  </td>
	  <td>
	    <%= if pv.uniques_week_over_week < 0
	          fa_icon 'arrow-down', class: "text-warning mr-3"
	        else
	          fa_icon 'arrow-up', class: "text-success mr-3"
	        end
	    %>
	    <%= number_to_percentage (pv.uniques_week_over_week * 100).abs, precision: 2 %>
	  </td>
	</tr>
	<% end %>
</tbody>

And voila! “Page Visits” now shows our real data from the page_visits table:

"Page Visits" table populated with "real" data.

You can see all the changes related to integrating real data in Pull Request #1.

Is Argon helpful? Star the repo on Github so others it's legit :)

See it in action

BugTracker is a fully-functional SaaS app built on Argon. Check out the step-by-step tutorial to see how it's built.

BugTracker, built on Argon

Coming Soon!

We’re excited to continue to make it easier than ever to build a Ruby on Rails SaaS app. We’ll be publishing lots of great content over the next weeks and months. Here are just a few examples:

  1. More templates
  2. Tables, charts, pages, and other components
  3. Guide to setting up user registration and authentication
  4. Guide to setting up a billing flow with Stripe

We have tons of ideas but ultimately we want you to tell us what you want to see next. Let us know! Email us at hey@dinosaas.com.

Build beautiful products, faster than ever

Be the first to know when we release new App Templates, Building Blocks, and MVPs.

Thank you! Click the link in your inbox to confirm your subscription.
Oops! Something went wrong. Email us at hey@dinosaas.com if this keeps happening.