gistfile1.txt

* Sinatra
* Bootstrap SASS
* Compass
* A basic HTML structure.

<p>I recently made two new website which had to be done fairly quickly but still look good, be simple technically, be responsive and not be static. There are many ways to do this but I settled on using Sinatra, Bootstrap, SASS and Compass, and this is how I stitched that together. This isn't groundbreaking but might be useful for someone who wants to do something similar without piecing together parts and conventions.</p>

<p>You can see a skeleton of the project <a href="https://github.com/bergcloud/demo-sinatra-site">on GitHub</a>. Once you've got a copy locally, <code>cd</code> into <code>demo-sinatra-site/</code> and then for development you'll want to run these in separate windows:</p>

<pre><code>$ compass watch .
$ rackup</code></pre>

<p>The first makes Compass watch the SASS files (in <code>public/sass/</code>) for changes, at which point it compiles new CSS files (into <code>public/css/</code>). The second runs the Sinatra webserver, so visiting <a href=" http://0.0.0.0:9292">http://0.0.0.0:9292/</a> should get you "Hello World".</p>

<p>Let's look at each part.</p>

<h2>Sinatra</h2>

<p>If I was making a quick static site, I'd probably use <a href="http://jekyllrb.com/">Jekyll</a> but usually there's at least one thing that needs some server-side processing. So, this being a Ruby place, <a href="http://www.sinatrarb.com/">Sinatra</a>.</p>

<p>Some notes:</p>


<ul>
  <li><p>There are two layouts in <code>views/_layouts/</code> as examples of using different general page structures.</p></li>

  <li><p>Each layout uses the same header and footer, both in <code>views/_partials/</code></p></li>

  <li><p><code>app.rb</code> contains the config, helper functions and routes for this example site. Expand as you need.</p>
    <ul>
      <li><p>There's a commented-out section that will let you add username/password authentication for a particular environment.</p></li>
      <li><p>Add a Google Analytics ID and the <code>views/_partials/footer.erb</code> template will render the required JavaScript.</p></li>
      <li><p>There are two routes set up for <code>/</code> and <code>/special/</code>. The second is an example of a page that has some unique server-side stuff happening.</p></li>
      <li>
        <p>There's a catch-all route for URLs that do nothing but render a view. Add new paths and page details to the hash, and matching views, to get them working. eg, if you want <code>/projects/demo/</code> to work as a URL, add this to the <code>pages</code> hash:</p>
        <pre><code>'projects/demo' =&gt; {
  :page_name =&gt; 'projects_demo',
  :title =&gt; 'Demo project',
  :layout =&gt; 'with_sidebar',
},</code></pre>
        <p>And create a new view at <code>views/projects_demo.erb</code> containing the main content for that page.</p>
        <p>The <code>:layout</code> is optional. If not set, the <code>views/_layouts/_with_sidebar.erb</code> layout will be used.</p>
      </li>
    </ul>
  </li>
  <li>Any changes made to views or <code>app.rb</code> should automatically take effect when you reload a page, thanks to <a href="http://www.sinatrarb.com/contrib/reloader.html">Sinatra::Reloader</a>.</li>
</ul>


<h2>Bootstrap</h2>

<p>I feel a bit defensive using Bootstrap's CSS <a href="http://notes.gross.is/post/43508972396/please-stop-using-twitter-bootstrap">because it's so common</a>. I decided to use it because: the responsive grid structure seems to work well; the default styles for forms, tables etc are nicer than the usual browser defaults; we'd be restyling it from the default look; and we've used it for sites before so there were people here already familiar with it.</p>

<p>We don't want to include all of Bootstrap's CSS and JS files, but only the bits we need. One way of doing this is to use the <a href="http://getbootstrap.com/customize/">customise</a> tool to download your own version, although that becomes a pain if you want to keep tweaking things.</p>

<p>(Top tip if you do use that tool though: when you download your files you'll get a <code>config.json</code> file. Paste the contents into a <a href="https://gist.github.com/">Gist</a>. Take the ID number from the Gist's URL and add it to the URL of the Bootstrap cusomtizer. eg, from <code>https://gist.github.com/anonymous/9325216</code> you get <code>http://getbootstrap.com/customize/?id=9325216</code>. The customizer then loads your settings. Nice.)</p>

<h3>Bootstrap's CSS</h3>

<p>We're using <a href="https://github.com/twbs/bootstrap-sass">Bootstrap-SASS</a>. I haven't taken full advantage of <a href="http://sass-lang.com/">SASS's</a> powers, but it lets us:</p>

<ul>
<li>Easily add or remove Bootstrap components.</li>
<li>Override some of the default Bootstrap colours, sizes, etc.</li>
<li>Re-use common bits of CSS and set variables.</li>
</ul>

<p>Edit CSS in the SASS files (in <code>public/sass/</code> with <code>.scss</code> extensions). These are then compiled by Compass into one or more CSS files in <code>public/css/</code>. Any SASS file whose name starts with an underscore is <em>not</em> compiled to a CSS file, so this is used to name included files.</p>

<p>Here's our SASS file structure:</p>

<dl>
<dt><code>styles.scss</code></dt>
<dd>This will be compiled to <code>styles.css</code> and used on the site. Styles in here should be very specific to our site. You could, instead, have several files like this, for different sections of the site, containing section-specific CSS. This file imports…</dd>

<dt><code>_base.scss</code></dt>
<dd>This sets any common, generic styles and variables and imports…</dd>

<dt><code>_bootstrap_custom.scss</code></dt>
<dd>This is a copy of <a href="https://github.com/twbs/bootstrap-sass/blob/master/vendor/assets/stylesheets/bootstrap/bootstrap.scss"><code>bootstrap.scss</code></a> with the <code>@import</code> paths tweaked and any parts of Bootstrap we don't need commented out. SASS then only includes the parts we need in the generated CSS file(s), keeping it smaller. This file also imports…</dd>

<dt><code>_bootstrap_variables.scss</code></dt>
<dd>The <a href="https://github.com/twbs/bootstrap-sass/blob/master/vendor/assets/stylesheets/bootstrap/_variables.scss"><code>_variables.scss</code></a> file contains all the default Bootstrap values. In our local version we set any values that we want to change.</dd>
<dd>For example, the original <code>_variables.scss</code> has <code>$body-bg: #fff !default;</code>. If we want a different background color, we'd put <code>$body-bg: #eee;</code> in our local <code>_bootstrap_variables.scss</code>.</dd>
</dl>

<p>The upshot of all that is that we can choose which components of Bootstrap to use (minimising our CSS file size), set default values that Bootstrap uses to build its CSS, and set our own styles afterwards. This lets us override any Bootstrap styles we want in <code>_base.scss</code> or <code>styles.scss</code>.</p>

<p>Alternatively, if you want to add a Bootstrap style to a different element, SASS makes that easy. eg, to make WordPress's comment <code>textarea</code> look like a Bootstrap form element you need to add the <code>form-control</code> class to it. If you don't want to touch the HTML you can add the <code>form-control</code> class's styles to it:</p>

<pre><code>.comment-form textarea {
  @extend .form-control;
}</code></pre>

<p>This applies all of <code>.form-control</code>'s styles to that <code>textarea</code>.</p>

<h3>Bootstrap's JavaScript</h3>

<p>If you need any of Bootstrap's JavaScript you'll either need to use the <a href="http://getbootstrap.com/customize/">customizer</a> to download what you need, or just use the complete JavaScript file. Either way, it goes in <code>public/js/</code>. Don't forget to enable the bits of Bootstrap CSS (in <code>_bootstrap_custom.scss</code>) each JS component requires.</p>


<h2>Compass</h2>

<p>I find <a href="http://compass-style.org/">Compass's documentation</a> baffling; I can never find anything I need. But we're only using Compass for its ability to watch some SASS files and compile them to CSS when something changes.</p>

<p><code>config.rb</code> contains the configuration for Compass, telling it where to find and put things, and what format to generate CSS in. You might not need to touch this, but <a href="http://compass-style.org/help/tutorials/configuration-reference/">here's the Compass configuration reference</a>.</p>


<h2>HTML</h2>

<p><code>views/</code> contains the HTML templates. You'll probably want to change stuff here, but it's enough to display something for demonstration purposes.</p>






  <div class="container">
    <div class="row">
      <div class="col-md-9">
        <p>The main content is here.</p>
      </div>
      <div class="col-md-3 sidebar">
        <p>Sidebar content is here.</p>
      </div>
    </div>
  </div>