Getting Started

In order to provide the most flexibility, FluentBootstrap does not code with a dependency on Bootstrap. This allows you to select the most appropriate mechanism of including Bootstrap for your situation. For example, you can use the default Bootstrap NuGet package, or use the LESS source. You can even go to the Bootstrap web site and download the CSS for manual inclusion. However you get Bootstrap, the corresponding CSS and JavaScript must be included on your page(s).

Note that you will want to match the version of Bootstrap to the version of FluentBootstrap (or vice versa). Since FluentBootstrap may be a version behind the official Bootstrap release, you may need to get a previous version of Bootstrap. To do this on NuGet with the standard Bootstrap package, you would type the following into the Package Management Console: Install-Package Bootstrap -Version X.X.X.

FluentBootstrap is designed to work in any environment. It consists of a code library, and in most cases, an architecture-specific library. The following instructions detail how to set up FluentBootstrap for various platforms.

ASP.NET MVC

The easiest way to get FluentBootstrap working on ASP.NET MVC is to get the FluentBootstrap.Mvc NuGet package. This will pull down both the core library and the special support for ASP.NET MVC including the Bootstrap model binding helpers.

All of the extensions for FluentBootstrap are under the root FluentBootstrap namespace. In order to access this namespace from your view code, you'll probably want to add it to your web.config like this:

<system.web.webPages.razor>
    <host .../>
    <pages ...>
        <namespaces>
            ...
            <add namespace="FluentBootstrap" />
        </namespaces>
    </pages>
</system.web.webPages.razor>

T4MVC

FluentBootstrap also has a supporting library for T4MVC, FluentBootstrap.Mvc.T4MVC. This allows you to use a T4MVC ActionResult anywhere a link is accepted.

ASP.NET WebPages

If you prefer to use ASP.NET WebPages, you can get the FluentBootstrap.WebPages NuGet package. This will pull down both the core library and the special support for ASP.NET WebPages. You will need to include @using FluentBootstrap at the top of every page. You will also need to pass in the page instance when using the helper like @Html.Bootstrap(this).Heading1("My Header"). This is because the ASP.NET WebPages HtmlHelper class does not provide all the information needed to use FluentBootstrap (such as access to the request context).

Wyam

There is also a library available for the Wyam static site generator at FluentBootstrap.Wyam (it's prerelease because Wyam uses the .NET Compiler Platform which is also prerelease). This will pull down both the core library and the special support for Wyam Razor templates. To include in your Wyam site, put this in the setup section of your Wyam configuration file: Packages.Install("FluentBootstrap.Wyam", allowPrereleaseVersions: true);. You will also need to include @using FluentBootstrap at the top of every Razor page. Then just call the .Bootstrap() extension like this: @Html.Bootstrap().Heading1("My Header").

Use It Directly

If you are outside of ASP.NET or you just want to generate Bootstrap HTML strings, then you can get by with just the FluentBootstrap NuGet package. This provides a SimpleBootstrapHelper class that you could instantiate to get access to all of the FluentBootstrap extensions.

Most of the functionality in FluentBootstrap is provided via extension methods on a special BootstrapHelper class obtained through the standard HtmlHelper. This helps segregate the many extension methods and keeps them from polluting the standard HtmlHelper extensions list. In general, you get access to the BootstrapHelper class as @Html.Bootstrap().

FluentBootstrap is designed as a fluent interface, which means that most components are configured via a chain of method calls. In general, you create a component after getting the BootstrapHelper and then configure it until it's output. A typical FluentBootstrap component might look like this:

@Html.Bootstrap().Dropdown("My Dropdown").SetSize(ButtonSize.Xs).SetState(ButtonState.Warning)

Components are also often provided with overloaded initial methods so that you don't need to use the fluent interface for the most common scenarios. For example:

@Html.Bootstrap().Alert(AlertState.Warning, "Warning", "Yikes, this is a warning.")

Alternatively, in ASP.NET MVC you can write code like @Bootstrap.Heading1("My Header") (notice that there's no Html. call) by creating a property in your base page class (if you don't have a custom base page class, see here for instructions on how to create one):

public MvcBootstrapHelper<TModel> Bootstrap
{
    get { return Html.Bootstrap(); }
}

You can also reduce the verbosity by creating and holding a reference to the BootstrapHelper object. Since it doesn't maintain any state, it can be repeatedly reused for FluentBootstrap components:

var b = Html.Bootstrap();
...
@b.Alert(AlertState.Warning, "My Alert")
...
@b.Heading2("Some Heading")
...

FluentBootstrap has a number of different ways to get the rendered HTML of your component (for example, to write it to the page output stream).

IHtmlString and ToHtmlString()

When you use the @ symbol in Razor, you're really passing an object to the Razor rendering engine and telling it to write that object to the output stream. One of the main ways it does this is to look for the object to implement IHtmlString. All of the FluentBootstrap component implement this interface and will render their HTML to the output stream when used with the @ symbol. Keep in mind that this rendering will occur at the end of the fluent method chain once all methods have been evaluated.

IDisposable And Begin/End

FluentBootstrap components can also be used as IDisposable objects (primarily for use in using statements for automatic tag closing). To do this, you need to call .Begin() on the component (for a discussion about why you have to make an extra call to get the IDisposable, see here). As soon as you call .Begin(), the component is immediately rendered to the output stream and a special wrapper is returned that provides extensions specific to the component being rendered.

using (var list = Html.Bootstrap().List(ListType.Ordered).Begin())
{
    @list.ListItem("One")
    @list.ListItem("Two")
}

If you forget to call .Begin(), you will get a compile-time error if you have pre-compilation turned on, or a run-time error if not, informing you that the component could not be converted to an IDisposable. This is intentional and is intended to ensure you remember to call .Begin() when using a component in a using statement.

As an alternative to a using statement, you can also manually begin and end the component.

var list = Html.Bootstrap().List(ListType.Ordered).Begin();
@list.ListItem("One")
@list.ListItem("Two")
list.End();

Notice how list.End(); is not preceded by a @. That's because both .Begin() and .End() write directly to the output stream and do not return an IHtmlString interface. If you forget and add the @, you will get a compile-time error if you have pre-compilation turned on, or a run-time error if not.

Alternative Begin Syntax

Alternatively, you can also use a special lambda syntax to begin your components if you don't like the explicit .Begin() call. To do this, call .Begin() immediately after the call to .Bootstrap() and construct your component as a function:

using(var list = Html.Bootstrap().Begin(x => x.List(ListType.Ordered)))
{
    ...
}

Outputting to a String

It's also possible to defer rendering and/or output the component to a string.

var dropdown = Html.Bootstrap().Dropdown("My Dropdown");
dropdown.SetSize(ButtonSize.Xs);
dropdown.SetState(ButtonState.Warning);
var renderedDropdown = dropdown.ToString();

This approach can be helpful if you're trying to output content for JavaScript or otherwise need to post-process the rendered component.

Many Bootstrap components have logical children. For example, a grid row has grid columns and a list has list items. FluentBootstrap has a number of facilities to help with children. For starters, when you use .Begin() to use a component inside a using statement, an object will be returned that restricts the list of additional FluentBootstrap components to those children that are most common for the containing component (keep in mind that you're not limited to what the returned class provides - you can always use the default BootstrapHelper inside another component).

Another scenario you might encounter is when you need to build an entire component hierarchy without outputting to the output stream. This can be accomplished using the .AddChild() extension method. For example:

string list = Html.Bootstrap().List(ListType.Ordered)
.AddChild(x => x.ListItem("One"))
.AddChild(x => x.ListItem("Two"))
.ToString();

Each call to .AddChild() returns context back to the original component when done. If on the other hand you just want to add a single child and maintain the fluent chain you can use the .WithChild() extension method.

@Html.Bootstrap().List(ListType.Ordered).WithChild().ListItem("Single List Item")

There is nothing wrong with mixing FluentBootstrap code and regular HTML markup or Bootstrap CSS. The two are designed to work well together, and it is recommended that you use whatever syntax provides the most understanding and benefit in your view code. For example, while FluentBootstrap has a .Paragraph() extension, you'll probably want to use the standard <p> HTML tag instead because it's much shorter.

The one thing to keep in mind when mixing code and markup is that you may need to change context from code back to markup if you're inside a FluentBootstrap code block and you don't need to open a new HTML tag. Thankfully, Razor provides both the <text> tag and the @: syntax to help achieve this. Here is a great blog article on the use of these two syntactical features.

@using(var row = Html.Bootstrap().GridRow().Begin())
{
    using(row.GridColumn(12).Begin())
    {
        // We are in a code context here and need to escape back to markup
        <text>My content.</text>
    }
}

CSS Classes

In fact, if you need to write HTML markup but still want the benefit of statically-typed Bootstrap CSS class names, you can use the static Css class. It contains const strings for every CSS class defined in the Bootstrap stylesheet. This allows you to swap out class name magic strings for string constants.

<p class="@Css.TextInfo">This is some informational text.</p>

There is a lot more to FluentBootstrap than what's described here. You can take a look at the other sections of this site (such as CSS) for many examples. You can also view additional examples by looking at the tests in the FluentBootstrap repository.

The best way to get help is to post a question on StackOverflow with the FluentBootstrap tag. If you find a bug, open an issue on GitHub. You can also tweet or follow @daveaglick with questions or for announcements.


FluentBootstrap is crafted by Dave Glick. Code on GitHub.