Getting started
Overview of the project, its contents, and how to get started IOUI.
1. Project setup
In the following example we will set up a typical ASP.NET MVC 4 application for using IOUI. The process should look highly similar to WebForms, and an example might be provided in the future.
Start by creating an empty ASP.NET MVC 4 application project using the Razor view engine and create a new layout page called _Layout.cshtml file in your Views > Shared folder.
In the next section we will prepare our application for using the IOUI CDN.
2. Configuring the CDN
All shared IOUI resources are hosted on a CDN provided by EPiServer. In the future, after the initial public release, we will provide offline packages as well, but for now everything is available directly off the CDN since the files frequently will change in the coming weeks.
Start by adding a reference to the IOUI.CDN library hosted in TFS on $/SvenskidrottOnline/IOUI/IOUI.CDN/lib. This library provides a configuration section and helpers for including all static resources in your application provided by IOUI.
After you have added a reference to your web project, add a section with the name ioui.cdn to the configSections element in your Web.config.
<configuration>
<configSections>
<section name="ioui.cdn" type="IOUI.CDN.Configuration"/>
</configSections>
...
</configuration>
Then add the actual section to your configuration:
<ioui.cdn>
<settings uri="http://cdn.ioui.idrottonline.se" version="1" jQueryVersion="1.8.3" debug="false"/> enableTopbar="true"/>
<bundles>
<clear/>
<add name="FuelUX"/>
<add name="Kendo"/>
<add name="Validate"/>
</bundles>
</ioui.cdn>
The section consists of the main settings element which has the following attributes
Next, on line 3, we have the bundle element were you specify which optional bundles you wish to load. Simply use the key of the bundle to add it to the loaded resources. The following bundles are currently available:
- Kendo
- FuelUX
- Validate
Please refer to the optional bundles section for a futher explanation of these. Future bundles may also include Telerik RadControls, primarily used in WebForms and Sharepoint applications, as well as validation styling for WebForms.
Heads up! While you are configuring your application, you should also add a csutom header to prevent Internet Explorer users from using the compability mode, since you want to ensure they are using Internet Explorer's latest rendering engine.
Add the custom header X-UA-Compatible in your customHeaders section as illustrated below:
<system.webServer>
...
<httpProtocol>
<customHeaders>
...
<add name="X-UA-Compatible" value="IE=Edge,chrome=1" />
</customHeaders>
</httpProtocol>
</system.webServer>
3. Configuring your layout page
With a brief intro into the contents out of the way, we can focus on putting IOUI to use. Open the newly created layout page in your web application that you created in section 1.
The initial layout will look like something this.
<!DOCTYPE html>
<html>
<head>
<meta name="viewport" content="width=device-width" />
<title>@ViewBag.Title</title>
</head>
<body>
<div>
@RenderBody()
</div>
</body>
</html>
Start by adding a few conditional comments to the HTML-element, which will allow for IOUI to adapt to different versions of Internet Explorer.
Next change the viewport meta tag to ensure IOUI adapts to mobile devices as well as preventing the user to scale and zoom in your application.
Also add the character encoding meta tag to ensure it is set UTF-8, to prevent any weird character issues.
<!DOCTYPE html>
<!--[if lt IE 7 ]><html class="ie ie6" lang="en"> <![endif]-->
<!--[if IE 7 ]><html class="ie ie7" lang="en"> <![endif]-->
<!--[if IE 8 ]><html class="ie ie8" lang="en"> <![endif]-->
<!--[if (gte IE 9)|!(IE)]><!-->
<html lang="en">
<!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
<title>@ViewBag.Title</title>
</head>
<body>
<div>
@RenderBody()
</div>
</body>
</html>
Now it is time to include IOUI itself. If you successfully have added a reference to IOUI.CDN project as described in the previous section, you can use the helpers in the IOUI.CDN namespace to add all scripts and styles that you need to include and they will also be loaded in the correct order.
On line 5 we include a reference to the scripts that are required to load in the head. Add it by locating the HeadScripts() method on the Bundles property.
As a browser process a web page sequentially, any scripts should always be included in the bottom of the page for performance reasons. But due to timing issues some scripts are required to load as soon as possible and they are included here.
Next, on line 6 simply locate the Styles() method on the Bundles property as illustrated and all styles you need (both the core part of IOUI as well as any optional packages) will be included.
Right after IOUI is added, you can then add any styles of your own, that you need for your specific application, as shown on line 7.
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
<title>@ViewBag.Title</title>
@IOUI.CDN.Bundles.HeadScripts()
@IOUI.CDN.Bundles.Styles()
@* load you styles here *@
@RenderSection("styles", required: false)
@RenderSection("head", required: false)
@* favicons and touch icons go here *@
</head>
All though not required for IOUI it might be helpful to have regions which will allow you to add more styles or other head content in other pages, so here we have added regions that you can use for this purpose on line 8 and 9.
Finally you can add any favicons or touch icons if you wish for your application.
Adding the layout elements
The main layout of IOUI consists of four typical web application regions – a header, a sidebar, a content area and a footer. These four elements define your application's layout and must be present on every page in your application.
First we need look at the body though. We need to wrap everything with a <div class="page-container"></div>, which is required for modals to work properly so add the class page-container to a div that will surround the entire body area.
<body>
<div class="page-container">
@RenderBody()
</div>
</body>
The header element contains only a heading one where you insert the name of your application. Also, you set the link to point at the start page of your application.
<div class="ioui-header">
<h1>
<a href="/">App | IdrottOnline</a></h1>
</div>
Next up is the sidebar. The only element required for the sidebar is a div with the class name ioui-sidebar. As you've probably guessed, the sidebar area is where you place your application menu.
The application menu consists of two levels, where you add the page structure of your application. In the following example we will go through the a part of this application’s menu as an example, and what elements you must use when structuring your menu.
<div class="ioui-sidebar">
<a href="#" class="visible-phone">
<i class="icon icon-reorder"></i>Menu
</a>
<ul>
<li>
<a title="Home" href="#">
<i class="icon icon-th"></i>
<span>Home</span>
</a>
</li>
<li class="active">
<a title="Getting started" href="/docs/getting-started">
<i class="icon icon-th"></i>
<span>Getting started</span>
</a>
</li>
<li class="submenu">
<a title="Sample layouts" href="#">
<i class="icon icon-th"></i>
<span>Sample layouts</span>
<span class="label">1</span>
</a>
<ul>
<li>
<a title="Start" href="/sample-layouts">Start</a>
</li>
</ul>
</li>
</ul>
</div>
On line 2 you will find a link with the class="visible-phone". This is a special menu item which will only be visible for phones, as the menu will render in a collapsible list at the top instead of always being present to the left.
By tapping this item, the user will be able to expand and collapse this menu accordingly.
On line 5 the actual menu start and is nothing more than a simple unordered list. The top level items are required to have an icon defined, as illustrated as they need to visible in compact mode. Find an appropriate icon and include it according to the docs.
Finally you can also have items which only act as placeholders for a submenu, without any actual link. This item also require you to provide a label with a count of the numer of subitems, to indicate for the user that this is a group. The submenu follows the same pattern as the top menu level, but do not add any icons or labels on this level.
And now we will add the main content area. As IOUI is responsive we need to wrap everything in the Bootstrap container-fluid class. Next, you simply add the logic for rendering your views or pages.
<div id="content" class="ioui-content">
<div class="container-fluid">
@RenderBody()
</div>
</div>
We will then add a basic footer, where you can provide some basic information about your application.
<div id="footer" class="ioui-footer">
<p>© IdrottOnline @DateTime.Now.Year.</p>
</div>
Last we reference the scripts just above the closing of the <body> tag. Here you can also add your own scripts as well provide a section like we did in the head.
<body>
...
@IOUI.CDN.Bundles.Scripts()
@* load you scripts here *@
@RenderSection("scripts", required: false)
</body>
And you are set! Your final layout page should look like this:
<!DOCTYPE html>
<!--[if lt IE 7 ]><html class="ie ie6" lang="en"> <![endif]-->
<!--[if IE 7 ]><html class="ie ie7" lang="en"> <![endif]-->
<!--[if IE 8 ]><html class="ie ie8" lang="en"> <![endif]-->
<!--[if (gte IE 9)|!(IE)]><!-->
<html lang="en">
<!--<![endif]-->
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0, maximum-scale=1.0, user-scalable=no">
<title>@ViewBag.Title</title>
@IOUI.CDN.Bundles.HeadScripts()
@IOUI.CDN.Bundles.Styles()
@* load you styles here *@
@RenderSection("styles", required: false)
@RenderSection("head", required: false)
@* favicons and touch icons go here *@
</head>
<body>
<div class="page-container">
<div class="ioui-header">
<h1>
<a href="/">App | IdrottOnline</a></h1>
</div>
<div class="ioui-sidebar">
<a href="#" class="visible-phone">
<i class="icon icon-reorder"></i>Menu
</a>
<ul>
<li>
<a title="Home" href="/">
<i class="icon-th icon"></i>
<span>Home</span>
</a>
</li>
<li class="active">
<a title="Getting started" href="/docs/getting-started">
<i class="icon-th icon"></i><span>Getting started</span>
</a>
</li>
<li class="submenu">
<a title="Sample layouts" href="/">
<i class="icon-th icon"></i>
<span>Sample layouts</span>
<span class="label">1</span>
</a>
<ul>
<li>
<a title="Start" href="/sample-layouts">Start</a>
</li>
</ul>
</li>
</ul>
</div>
<div id="content" class="ioui-content">
<div class="container-fluid">
@RenderBody()
</div>
</div>
<div id="footer" class="ioui-footer">
<p>© IdrottOnline @DateTime.Now.Year.</p>
</div>
</div>
@IOUI.CDN.Bundles.Scripts()
@* load you scripts here *@
@RenderSection("scripts", required: false)
</body>
</html>
Now head over to the Scaffolding sections to learn more on how to structure your individual pages.
Globalization and translations
In an ASP.NET Web page, you can set to two culture values, the Culture and UICulture properties. The Culture value determines the results of culture-dependent functions, such as the date, number, and currency formatting, and so on. The UICulture value determines which resources are loaded for the page.
IOUI uses the UICulture to determine which resources to load on
You can configure your all your pages in you application to use a defualt culture in web.config by adding a globalization section.
<globalization uiCulture="sv-SE" culture="sv-SE" />
Learn more about the different options on MSDN.
What next?
Head to the docs for information, examples, and code snippets, or take the next leap and customize Bootstrap for any upcoming project.