bootstrap/docs/getting-started.html

---
layout: default
title: Getting started
slug: getting-started
lead: "An overview of Jasny Bootstrap, how to download and use, basic templates and examples, and more."
base_url: "../"
---

  <!-- Getting started
  ================================================== -->
  <div class="bs-docs-section">
    <div class="pb-2 mt-4 mb-2 border-bottom">
      <h1 id="jasny-bootstrap">Jasny Bootstrap</h1>
    </div>
    <p class="lead">Jasny Bootstrap is an extension to <a href="http://getbootstrap.com">vanilla Bootstrap</a>, adding a number of features and components.</p>
    <p>The aim of Jasny Bootstrap is to provide all the required features for building highly interactive web applications for desktop and mobile.</p>

    <div class="bs-callout bs-callout-warning">
      <h4>Delivered as extension only</h4>
      <p>As of version 3.1.0 Jasny Bootstrap is no longer bundled with vanilla Bootstrap. You should load vanilla Bootstrap's CSS before this extension.</p>
    </div>
  </div>

  <!-- Getting started
  ================================================== -->
  <div class="bs-docs-section">
    <div class="pb-2 mt-4 mb-2 border-bottom">
      <h1 id="download">Download</h1>
    </div>
    <p class="lead">Jasny Bootstrap has a few easy ways to quickly get started, each one appealing to a different skill level and use case. Read through to see what suits your particular needs.</p>

    <h3 id="download-compiled">Compiled CSS and JS</h3>
    <p>The fastest way to get Jasny Bootstrap is to download the compiled and minified versions of our CSS and JavaScript. No documentation or original source files are included.</p>
    <p><a class="btn btn-lg btn-primary" href="{{ site.download.dist }}" onclick="_gaq.push(['_trackEvent', 'Getting started', 'Download', 'Download compiled']);">Download Jasny Bootstrap</a></p>

    <h3 id="download-additional">Additional downloads</h3>
    <div class="bs-docs-dl-options">
      <h4>
        <a href="{{ site.download.source }}" onclick="_gaq.push(['_trackEvent', 'Getting started', 'Download', 'Download source']);">Download source code</a>
      </h4>
      <p>Get the latest Jasny Bootstrap LESS and JavaScript source code by downloading it directly from GitHub.</p>
      <h4>
        <a href="{{ site.repo }}" onclick="_gaq.push(['_trackEvent', 'Getting started', 'Download', 'GitHub project']);">Clone or fork via GitHub</a>
      </h4>
      <p>Visit us on GitHub to clone or fork the Jasny Bootstrap project.</p>
    </div>

    <h3 id="download-cdn">Jasny Bootstrap @ cdnjs</h3>
    <p><a href="http://cdnjs.com" target="_blank">CDNJS</a> is a community driven CDN hosted by CloudFlare, supporting over a hundred projects. To use this CDN, swap your local instances for the CDN links listed below.</p>
{% highlight html %}
<!-- Latest compiled and minified CSS -->
<link rel="stylesheet" href="{{ site.cdn.css }}">

<!-- Latest compiled and minified JavaScript -->
<script src="{{ site.cdn.js }}"></script>
{% endhighlight %}

    <div class="bs-callout bs-callout-warning" id="callout-less-compilation">
      <h4>Compiling Jasny Bootstrap's LESS files</h4>
      <p>If you work with Jasny Bootstrap's uncompiled source code, you need to compile the LESS files to produce usable CSS files. For compiling LESS files into CSS, we only officially support <a href="http://twitter.github.io/recess/">Recess</a>, which is Twitter's CSS hinter based on <a href="http://lesscss.org">less.js</a>.</p>
    </div>
  </div>


  <!-- File structure
  ================================================== -->
  <div class="bs-docs-section bs-jasny">
    <div class="pb-2 mt-4 mb-2 border-bottom">
      <h1 id="whats-included">What's included</h1>
    </div>
    <p class="lead">Within the download you'll find the following directories and files, logically grouping common resources and providing both compiled and minified variations.</p>
    <p>Once downloaded, unzip the compressed folder to see the structure of (the compiled) Jasny Bootstrap. You'll see something like this:</p>

<!-- NOTE: This info is intentionally duplicated in the README.
Copy any changes made here over to the README too. -->
{% highlight bash %}
jasny-bootstrap/
├── css/
│   ├── jasny-bootstrap.css
│   ├── jasny-bootstrap.min.css
└── js/
    ├── jasny-bootstrap.js
    └── jasny-bootstrap.min.js

{% endhighlight %}

    <p>This is the most basic form of Jasny Bootstrap. We provide compiled CSS and JS (<code>jasny-bootstrap.*</code>), as well as compiled and minified CSS and JS (<code>jasny-bootstrap.min.*</code>).</p>

    <p>The <code>jasny-bootstrap.*</code> files should be loaded in conjunction with the original vanilla Bootstrap files.</p>

    <div class="bs-callout bs-callout-danger" id="jquery-required">
      <h4>jQuery required</h4>
      <p>Please note that <strong>all JavaScript plugins require jQuery</strong> to be included, as shown in the <a href="#template">starter template</a>.
    </div>
  </div>


  <!-- Template
  ================================================== -->
  <div class="bs-docs-section">
    <div class="pb-2 mt-4 mb-2 border-bottom">
      <h1 id="template">Basic template</h1>
    </div>
    <p class="lead">Start with this basic HTML template, or modify <a href="../getting-started#examples">these examples</a>. We hope you'll customize our templates and examples, adapting them to suit your needs.</p>

    <p>Copy the HTML below to begin working with a minimal Bootstrap document.</p>
{% highlight html %}
<!DOCTYPE html>
<html>
  <head>
    <title>Bootstrap 101 Template</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0">
    <!-- Bootstrap -->
    <link href="css/bootstrap.min.css" rel="stylesheet" media="screen">
    <link href="css/jasny-bootstrap.min.css" rel="stylesheet" media="screen">

    <!-- HTML5 Shim and Respond.js IE8 support of HTML5 elements and media queries -->
    <!-- WARNING: Respond.js doesn't work if you view the page via file:// -->
    <!--[if lt IE 9]>
      <script src="https://oss.maxcdn.com/libs/html5shiv/3.7.0/html5shiv.js"></script>
      <script src="https://oss.maxcdn.com/libs/respond.js/1.3.0/respond.min.js"></script>
    <![endif]-->
  </head>
  <body>
    <h1>Hello, world!</h1>

    <!-- jQuery (necessary for Bootstrap's JavaScript plugins) -->
    <script src="https://code.jquery.com/jquery.js"></script>
    <!-- Include all compiled plugins (below), or include individual files as needed -->
    <script src="js/bootstrap.min.js"></script>
    <script src="js/jasny-bootstrap.min.js"></script>
  </body>
</html>
{% endhighlight %}
  </div>


  <!-- Plugins
  ================================================== -->
  <div class="bs-docs-section">
    <div class="pb-2 mt-4 mb-2 border-bottom">
      <h1 id="js-overview">Plugins</h1>
    </div>

    <h3 id="js-individual-compiled">Individual or compiled</h3>
    <p>Plugins can be included individually (using Jasny Bootstrap's individual <code>*.js</code> files), or all at once (using <code>jasny-bootstrap.js</code> or the minified <code>jasny-bootstrap.min.js</code>).</p>
    <p>The Jasny Bootstrap plugins work with or without loading vanilla Bootstrap's <code>bootstrap.js</code>.</p>

    <div class="bs-callout bs-callout-danger">
      <h4>Do not attempt to include both.</h4>
      <p>Both <code>jasny-bootstrap.js</code> and <code>jasny-bootstrap.min.js</code> contain all plugins in a single file.</p>
    </div>

    <h3 id="js-data-attrs">Data attributes</h3>
    <p>You can use all Jasny Bootstrap plugins purely through the markup API without writing a single line of JavaScript. This is Bootstrap's first-class API and should be your first consideration when using a plugin.</p>

    <p>That said, in some situations it may be desirable to turn this functionality off. Therefore, we also provide the ability to disable the data attribute API by unbinding all events on the document namespaced with <code>data-api</code>. This looks like this:
{% highlight js %}
$(document).off('.data-api')
{% endhighlight %}

    <p>Alternatively, to target a specific plugin, just include the plugin's name as a namespace along with the data-api namespace like this:</p>
{% highlight js %}
$(document).off('.alert.data-api')
{% endhighlight %}

    <h3 id="js-programmatic-api">Programmatic API</h3>
    <p>We also believe you should be able to use all Bootstrap plugins purely through the JavaScript API. All public APIs are single, chainable methods, and return the collection acted upon.</p>
{% highlight js %}
$(".fileinput").fileinput().addClass("fat")
{% endhighlight %}

    <p>All methods should accept an optional options object, a string which targets a particular method, or nothing (which initiates a plugin with default behavior):</p>
{% highlight js %}
$("#myMenu").offcanvas()                      // initialized with defaults
$("#myMenu").offcanvas({ autohide: false })   // initialized with no autohide
$("#myMenu").offcanvas('show')                // initializes and invokes show immediately</p>
{% endhighlight %}

    <p>Each plugin also exposes its raw constructor on a <code>Constructor</code> property: <code>$.fn.popover.Offcanvas</code>. If you'd like to get a particular plugin instance, retrieve it directly from an element: <code>$('.navmenu').data('offcanvas')</code>.</p>

    <h3 id="js-noconflict">No conflict</h3>
    <p>Sometimes it is necessary to use Bootstrap plugins with other UI frameworks. In these circumstances, namespace collisions can occasionally occur. If this happens, you may call <code>.noConflict</code> on the plugin you wish to revert the value of.</p>
{% highlight js %}
var bootstrapButton = $.fn.button.noConflict() // return $.fn.button to previously assigned value
$.fn.bootstrapBtn = bootstrapButton            // give $().bootstrapBtn the Bootstrap functionality
{% endhighlight %}

    <h3 id="js-events">Events</h3>
    <p>Bootstrap provides custom events for most plugin's unique actions. Generally, these come in an infinitive and past participle form - where the infinitive (ex. <code>show</code>) is triggered at the start of an event, and its past participle form (ex. <code>shown</code>) is trigger on the completion of an action.</p>
    <p>As of 3.1.2, all Bootstrap events are namespaced.</p>
    <p>All infinitive events provide <code>preventDefault</code> functionality. This provides the ability to stop the execution of an action before it starts.</p>
{% highlight js %}
$('#myMenu').on('show.bs.offcanvas', function (e) {
  if (!data) return e.preventDefault() // stops menu from being shown
})
{% endhighlight %}
  </div>


  <!-- Containers
  ================================================== -->
  <div class="bs-docs-section">
    <div class="pb-2 mt-4 mb-2 border-bottom">
      <h1 id="containers">Containers</h1>
    </div>

    <p>Added <code>.container-smooth</code> a container to use the same <code>max-width</code> for all viewport sizes. This means that the container size won't jump at media query breakpoints.</p>
  </div>


  <!-- Template
  ================================================== -->
  <div class="bs-docs-section">
    <div class="pb-2 mt-4 mb-2 border-bottom">
      <h1 id="examples">Examples</h1>
    </div>
    <p class="lead">Create diverse and advanced user interfaces using Jasny's Bootstrap components.</p>

    <div class="row bs-examples">
      <div class="col-xs-6 col-md-4">
        <a class="thumbnail" href="../examples/starter-template/">
          <img class="img-thumbnail" src="../examples/screenshots/starter-template.jpg" alt="">
        </a>
        <h4>Starter template</h4>
        <p>Nothing but the basics: compiled CSS and JavaScript along with a container.</p>
      </div>
      <div class="col-xs-6 col-md-4">
        <a class="thumbnail" href="../examples/navmenu/">
          <img class="img-thumbnail" src="../examples/screenshots/navmenu.jpg" alt="">
        </a>
        <h4>Navmenu</h4>
        <p>A basic template showing the navmenu element and demonstrates usage of the offcanvas plugin.</p>
      </div>
      <div class="clearfix visible-xs visible-sm"></div>
      <div class="col-xs-6 col-md-4">
        <a class="thumbnail" href="../examples/navmenu-push/">
          <img class="img-thumbnail" src="../examples/screenshots/navmenu-push.jpg" alt="">
        </a>
        <h4>Off Canvas Push Menu</h4>
        <p>A template demonstrating a push effect for the off canvas navmenu.</p>
      </div>
      <div class="clearfix visible-md visible-lg"></div>
      <div class="col-xs-6 col-md-4">
        <a class="thumbnail" href="../examples/navmenu-reveal/">
          <img class="img-thumbnail" src="../examples/screenshots/navmenu-reveal.jpg" alt="">
        </a>
        <h4>Off Canvas Reveal Menu</h4>
        <p>A template demonstrating a reveal effect by placing the navmenu under the content.</p>
      </div>
      <div class="col-xs-6 col-md-4">
        <a class="thumbnail" href="../examples/navbar-offcanvas/">
          <img class="img-thumbnail" src="../examples/screenshots/navbar-offcanvas.jpg" alt="">
        </a>
        <h4>Off canvas navbar</h4>
        <p>A template using offcanvas for mobile view of the navbar.</p>
      </div>
    </div>
  </div>

  <!-- Migration from 3.x to 4.0
  ================================================== -->
  <div class="bs-docs-section">
    <div class="pb-2 mt-4 mb-2 border-bottom">
      <h1 id="migration-v4">Migrating from 3.x to 4.0</h1>
    </div>
    <p class="lead">There are not many changes in this migration, as it mostly deals with moving to Bootstrap 4 support.</p>

    <h2 id="migration-classes-v4">Major class changes</h2>
    <p>Bootsrtap 4 release introduced some new classes, so we also switched to using them. There're no other new classes in this version of Jasny Bootstrap.</p>
    <ul>
      <li>Introduced <code>.nav-item</code>, <code>.nav-link</code>, <code>.flex-column</code> classes, that are used in nav-menu.</li>
      <li><code>.navbar-fixed-top</code> is changed to <code>.fixed-top</code>.</li>
    </ul>

    <h2 id="migration-dropped-v4">What's removed</h2>
    <ul>
      <li>Starting from this version Jasny Bootstrap is no longer published on Bower.</li>
      <li>Inputmask plugin has been removed.</li>
      <li>Removed variables customization page in documentation.</li>
      <li>By default file icon is removed from file input, though it can be easily added. See <a href="../components#fileinput-examples">Fielinput examples</a>.</li>
      <li>As Glyphicons were excluded from Bootstrap 4 bundle, icons now should be explicitly loaded to be used. For button labels we switched to <a href="https://fontawesome.com/">Font Awasome icons</a>. For them to work, you should include the link to them on the page, like the following: <code>&lt;link rel="stylesheet" href="https://stackpath.bootstrapcdn.com/font-awesome/4.7.0/css/font-awesome.min.css"&gt;</code></li>
    </ul>
  </div>

  <!-- Migration from 2.x to 3.0
  ================================================== -->
  <div class="bs-docs-section">
    <div class="pb-2 mt-4 mb-2 border-bottom">
      <h1 id="migration-v3">Migrating from 2.x to 3.0</h1>
    </div>
    <p class="lead">Folks looking to upgrade to v3 should use this section as a general upgrade guide. We've outlined some of the major changes and provided tables that highlight key changes.</p>

    <h2 id="migration-classes-v3">Major class changes</h2>
    <p>This table shows the style changes between v2.x and v3.0.</p>
    <div class="table-responsive">
      <table class="table table-bordered table-striped">
        <thead>
          <tr>
            <th>Bootstrap 2.x</th>
            <th>Bootstrap 3.0</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td><code>.container-semifluid</code></td>
            <td><code>.container-smooth</code></td>
          </tr>
          <tr>
            <td><code>.fileupload</code> <code>.fileupload-*</code></td>
            <td><code>.fileinput</code> <code>.fileinput-*</code></td>
          </tr>
        </tbody>
      </table>
    </div><!-- /.table-responsive -->

    <h2 id="migration-new-v3">What's new</h2>
    <p>We've added new elements and changed some existing ones. Here are the new or updated styles.</p>
    <div class="table-responsive">
      <table class="table table-bordered table-striped">
        <thead>
          <tr>
            <th>Element</th>
            <th>Description</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Navmenu</td>
            <td><code>.navmenu .navmenu-default</code> <code>.navmenu .navmenu-inverse</code> <code>.navmenu-fixed-left</code> <code>.navmenu-fixed-right</code> <code>.navmenu-brand</code> <code>.navmenu-nav</code></td>
          </tr>
          <tr>
            <td>Fixed alerts</td>
            <td><code>.alert-fixed-top</code> <code>.alert-fixed-bottom</code></td>
          </tr>
          <tr>
            <td>Off canvas</td>
            <td><code>.offcanvas</code> <code>.offcanvas-*</code></td>
          </tr>
        </tbody>
      </table>
    </div><!-- /.table-responsive -->


    <h2 id="migration-dropped-v3">What's removed</h2>
    <p>The following elements have been dropped or changed in v3.0.</p>
    <div class="table-responsive">
      <table class="table table-bordered table-striped">
        <thead>
          <tr>
            <th>Element</th>
            <th>Removed from 2.x</th>
            <th>3.0 Equivalent</th>
          </tr>
        </thead>
        <tbody>
          <tr>
            <td>Header actions</td>
            <td><code>.header-actions</code></td>
            <td class="text-muted">N/A</td>
          </tr>
          <tr>
            <td>Table actions</td>
            <td><code>.table-actions</code></td>
            <td class="text-muted">N/A</td>
          </tr>
          <tr>
            <td>Desktop rows</td>
            <td><code>.row-desktop</code></td>
            <td><code>.row &gt; .col-md-*</code></td>
          </tr>
          <tr>
            <td>Action links</td>
            <td><code>.act-*</code></td>
            <td class="text-muted">N/A</td>
          </tr>
          <tr>
            <td>Page alerts</td>
            <td><code>.pagealert</code></td>
            <td><code>.alert-fixed-top</code></td>
          </tr>
          <tr>
            <td>Iconic icons</td>
            <td><code>.iconic-*</code></td>
            <td class="text-muted">N/A</td>
          </tr>
          <tr>
            <td>Editor textarea</td>
            <td><code>.editor</code></td>
            <td class="text-muted">N/A</td>
          </tr>
        </tbody>
      </table>
    </div><!-- /.table-responsive -->


    <h2 id="migration-notes-v3">Additional notes</h2>
    <p>Other changes in v3.0 are not immediately apparent. Base classes, key styles, and behaviors have been adjusted for flexibility and our <em>mobile first</em> approach. Here's a partial list:</p>
    <ul>
      <li>The fileupload plugin has been renamed to fileinput. File upload was poorly chosen, since the plugin allows the creation of a styled file input element. It has nothing to do with how the file is uploaded.</li>
      <li class="bs-jasny-only">Tab alignments are still supported in this fork (while dropped in vanilla Bootstrap).</li>
      <li>Typeahead has been dropped, in favor of using <a href="http://brianreavis.github.io/selectize.js/">Selectize.js</a>.</li>
      <li>Iconic icons are still available from <a href="http://www.somerandomdude.com/work/open-iconic/">P.J. Onori</a>.</li>
    </ul>
    <p>For more information on upgrading to v3.0, and code snippets from the community, see <a href="http://bootply.com/">Bootply</a>.</p>
  </div>