I. Become a developer

As a registered developer, you can test and debug your own, not yet published, services through the app itself.

1. Download the app

Download the apps in their respective stores. Search for "Mitt Vilhelmina".

2. Find your unique device ID

iOS

Go to your iPhone's settings, scroll down to 'Mitt Vilhelmina'. There you'll find your device ID.

Android

Open the 'Mitt Vilhelmina' app. Press the settings icon in upper right corner. Your device ID is visible in the lower right corner.

3. Sign up as a developer

II. Test environment

There are many ways in which you can test services you are developing.

• On a developer enabled device (recommended)
• Webkit-based desktop browser
• Mobile browser
• Mobile simulator

Testing locally

You can test parts of your services in any Webkit browser (like Safari or Chrome). There is an iOS simulator inside Apple's IDE Xcode that can come in handy when testing locally. But keep in mind that UIWebView in the app functions a little bit different from the simulator. For instance iOS5 Safari uses a faster JavaScript engine than UIWebView, meaning that animations and JavaScript could appear slower in the actual app. UIWebView also ignores the HTML5 cache manifest, so that can not be used.

That said: The only way to make sure that something really works as intended is to test it on the device itself.

Quick guides to testing locally

Testing in the web browser

1. Install Apache and PHP. If you do not already have it installed or are not sure how to do this there are software packages that includes a "turn-key" environment for Apache, MySQL and PHP. For Windows there is WAMP and for Mac there is MAMP
2. Once this is working you can open services and test them in the browser. Make sure that you are using a webkit browser (preferably Chrome) and not Firefox or Internet Explorer

Testing service in native app

1. Upload the service that is being developed on a public web server with PHP installed.
2. Register as a developer to flag your device as "developer enabled"
3. Inside the app: On the home screen, tap the button "+Se alla tjänster", scroll all the way to the bottom and press "Lägg till Ad Hoc-tjänst". If your device is not developer enabled this button will not be showing. If that is the case, make sure that you registered your device as a developer.
4. Enter the name of the service as well as the URL to the location where you put the service.

Testing locally, but in the native app (removing the need to deploy changes to a server all the time)

1. Install a proxy solution on your machine that lets you access localhost from your phone. There are different ways of doing this. CharlesProxy works on both Windows and Mac.
2. Inside the app: On the home screen, tap the button "+Se alla tjänster", scroll all the way to the bottom and press "Lägg till Ad Hoc-tjänst". If your device is not developer enabled this button will not be showing. If that is the case, make sure that you registered your device as a developer.

III. Development

The services in Mitt Vilhelmina are created with HTML5, CSS and JavaScript, which is also the building blocks of the frontend framework.

HTML5

The framework is set up so that you can use all kinds of predefined classes in your HTML code to get the layout of your choice with the constraints of a smartphone. The framework handles the output for all the different platforms. Read more in the Framework reference.

CSS

If you are using the elements included in the frontend framework you will not need to write any custom CSS. If you need additional elements or need to customize the look and feel of your service, you can load your own CSS file or use internal styles. Read more about CSS.

JavaScript

The frontend framework uses JavaScript that is transformed to native functions in the smartphone app. For best performance you should use the methods in this documentation, but you can always use plain JavaScript or include any additional libraries you need to build your service. Read more about JavaScript in Mitt Vilhelmina.

Read more

You can find more details in the Technical overview, or see the full documentation in the Framework reference.

Contribute

If you find bugs or have suggestions for features that you think should be included in the framework, feel free to send an e-mail to helloumbra@hellofuture.se. Thank you!

IV. Publishing

Publishing services is handled by Vilhelmina kommun. Contact Vilhelmina kommun on e-mail app@vilhelmina.se when you are ready to publish your service.

The following information should be included in the e-mail:

• The name of your service
• A description of the service
• A URL to the service

What is a service?

The ultimate objective of a service is to be easy to use, smart and helpful in the everyday lives of citizens.

Of course a service can be many different things. They can be stand alone, or part of a larger service network. They can be micro-services in that they perform a small but specific function. Opening hours is a good example of a micro-service that is simple, yet can be very useful in the context of the everyday life of the user.

How to identify good service opportunities

Looking at mobile usage there are three main things that a user will be looking to do:

• I need something often
• I need something right now
• I am bored and need something to do

In the case of Mitt Vilhelmina, services should mainly make use of the first two behaviours. If you identify something that needed quickly and often, the potential for a useful service is definitely there.

Graphical guidelines

The main purpose of this documentation is to guide you to design a service that fits within Mitt Vilhelmina. It is not a manual and should not be seen as such. Depending on the context and situation there is always be room to design the service your own way. It is, however, recommended that you follow the basic UI elements unless there are strong reasons not to do so.

Using fonts, margins and colors that are not default will remove cohesion between different services that may harm the overall experience of the platform.

Layout

Rule #1: Keep it simple. Complex layouts on small screens is generally not a good idea. More than one column is not recommended. More information about the specific user interface elements can be found in the Framework reference.

There are a lot of standard elements in the framework that you can use. What you won't find in the framework is images, icons and other graphical elements that can create a personality and make your service shine. It's possible and encouraged that you add graphics of your own but be aware of platform inconstancies. Make sure to test colors, legibility and functionality across the many supported platforms and screen sizes.

Fonts

The native app and the services uses Helvetica Neue throughout. Always use Helvetica Neue unless exceptions are required. The font is embedded in the framework already and loading additional fonts can be to the detriment of performance.

Other fonts can be used if needed, but in that case it should mostly be for headers and other protruding graphical elements.

Colors

Accessibility

From an accessibility perspective, think about using colors that has sufficient contrast. Remember to use other means than color for providing interface clues.

Architecture

HTML5

Each html file can contain one or more pages. Each page is included in a section tag.

Service outline

The example below shows a basic outline of a service. There you can see the one script-tag that makes up the whole frontend framework. Custom CSS and JavaScript is loaded as usual. Each HTML5-file may contain one or more pages. Each page inside the service is a section. Place your first section after the opening body-tag.

<!DOCTYPE html> 
<html>
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, 
			initial-scale=1.0, user-scalable=no" />
		<meta name="format-detection" content="telephone=no" />
		<!-- title (not used) -->
		<title>The name of the service</title>
		<!-- frontend framework -->
		<script src="http://ff-vilhelmina.helloumbra.com/current/"></script>
		<!-- optional stylesheet for this service -->
		<link rel="stylesheet" href="assets/css/myservice.css" />
	</head>
	<body>
		<!-- each body must contain att least one section 
			that is shown as a page -->
		<section>
			<!-- each section should have a header -->
			<header>
				<!-- each header should have a <h1> that represents 
					the page title -->
				<h1>Page one</h1>
			</header>
			<!-- page elements¹ -->
		</section>
		<!-- optional additional sections (pages) -->
		<section>
			<!-- […] -->
		</section>
		<section>
			<!-- […] -->
		</section>
		<!-- all javascript should be included 
			after the last section element -->
		<!-- optional javascript for this service -->
		<script src="assets/js/myservice.js"></script>
	</body>
</html>

¹ Page elements included in the framework:

Pages

Each section can have a data-ff-role-attribute that configure the page in the following ways:

<section id="page-1" data-ff-role="home default swipe-in">
	<!-- […] -->
</section>
<section id="page-2" data-ff-role="swipe-in">
	<!-- […] -->
</section>

Pages loaded with xhr

If a page is loaded with data-ff-role="xhr"> only two elements of that page will be loaded. All script-elements with data-ff-role="include" set, as well as all section elements.

To see an example of a resource loaded with xhr, look at this. Due to the fact that xhr-resources only load script and section-tags, the CSS definitions should be included in the previous page. Each DOM-attribute id should only be used once in your service.

<!DOCTYPE html> 
<html>
	<!-- if this is loaded with xhr, then … -->
	
	<!-- … the header is ignored -->
	<head><!-- head definitions --></head>
	<body>
		<!-- … every section is loaded -->
		<section><!-- section content --></section>
		<section><!-- section content --></section>

		<!-- … this script is loaded since it's using data-ff-role=include -->
		<script src="include-me.js" data-ff-role="include"></script>

		<!-- … this script isn't loaded because data-ff-role=include is missing -->
		<script src="ignore-me.js"></script>
	</body>
</html>

Read the Page reference to learn more about the page system in the frontend framework.

CSS

If you are using only elements found in the frontend framework you don't need to add custom css at all. If you however want a different look and feel for your service you need to write custom css.

You can include your css directly after the frameworks css. If you only have some lines of css code you can use an internal stylesheet using the style element to reduce HTTP requests.

You should not use classnames that start with ff- since these are reserved for the frontend framework

Each selector should contain at least one id or classname to avoid changing the general look and feel provided by the framework.

Use Data URI schema to reduce HTTP requests.

Remember that you write for WebKit only and therefore can use a lot of advanced css3 technologies. But there are limitations both in iOS and Android. If you want to use a special feature check first on http://caniuse.com/ if it works on Android 4.1+ and iOS 7+.

JavaScript

jQuery is included in the framework, and for touch events like swipe or tap there's also the jQuery plugin Hammer. There are two global variables used to call methods. The dollar sign, $, is used to call jQuery and FF is used to call the frontend framework. Only use variables and methods included in this documentation, as everything else is subject to change in future versions of the framework.

The following libraries are included in the framework:

• jQuery (v2.1.4)
• Hammer.js (v1.0.5)

Using your own JavaScript code

You can always include your own javascript file besides the framework.

<!-- put after the last section element, before the ending body tag -->
<!-- js frontend framework -->
<script src="http://ff-vilhelmina.helloumbra.com/current/"></script>
<!-- optional javascript for this service -->
<script src="assets/js/application.js"></script>

To initialize your own javascript code use FF.Service.ready(), which executes after the page and its content is loaded.

FF.Service.ready(function() {

	/* initialize service */

});

For full documentation see Framework reference.

Asynchronous methods and jQuery Deferred objects.

Some of the Layout independent methods are asynchronous, because they have to wait, for example for a http request to return or a user to take a picture with the camera.

These methods do not return the result of the request but a Promise provided by jQuery. This Promise object will provide several chainable methods. The function in done() is executed if the request was successful, the function in fail() is executed if an error occured. These functions holds arguments from the asynchronous call in the app, so the parameters can be different from different calls. This is the general structure:

requestSomethingAsynchronously(id)
	/* the promise object provides the methods .done() and .fail() */
	.done(function(responseStatus) { /* parameters depend on the asynchronous method */
		/* this is executed if th call was successful */
		FF.Modal.alert(responseStatus);
	})
	.fail(function(errorCode, errorMessage) { /* parameters depend on the asynchronous method */
		/* this is executed if there was an error */
		FF.Modal.alert('Error #' + errorCode);
	})
;

These are the asynchronous methods:

• FF.Media.requestImage
• FF.HttpRequest.requestPost
• FF.Position.requestPosition

Pages

Each HTML5-file may contain one or more pages. A page is created using a section-tag. Place your first section after the opening body-tag and fill it with the content of your service. If you need to use multiple pages you can simply add more section-tags. In the example below you can see an example of how this works.

<!DOCTYPE html> 
<html>
	<head>
		<meta charset="UTF-8" />
		<meta name="viewport" content="width=device-width, 
			initial-scale=1.0, user-scalable=no" />
		<meta name="format-detection" content="telephone=no" />
		<!-- title (not used) -->
		<title>The name of the service</title>
		<!-- frontend framework -->
		<script src="http://ff-vilhelmina.helloumbra.com/current/"></script>
		<!-- optional stylesheet for this service -->
		<link rel="stylesheet" href="assets/css/myservice.css" />
	</head>
	<body>
		<!-- each body must contain att least one section 
			that is shown as a page -->
		<section>
			<!-- each section should have a header -->
			<header>
				<!-- each header should have a <h1> that represents 
					the page title -->
				<h1>Page one</h1>
			</header>
			<!-- page elements¹ -->
		</section>
		<!-- optional additional sections (pages) -->
		<section>
			<!-- […] -->
		</section>
		<section>
			<!-- […] -->
		</section>
		<!-- all javascript should be included 
			after the last section element -->
		<!-- optional javascript for this service -->
		<script src="assets/js/myservice.js"></script>
	</body>
</html>

Page data-ff-roles:

HTML section-tags can have a data-ff-role-attribute that configures the page. All available data-ff-role-attributes are listed below:

Loding pages with xhr (ajax)

If a page is loaded with a link that has data-ff-role="xhr" (see example) only two elements of that page will be loaded. All script-elements with data-ff-role="include" set, as well as all section elements.

Below is an example of a resource loaded with xhr. Due to the fact that xhr-resources only load script and section-tags, the CSS definitions should be included in the previous page.

<!DOCTYPE html> 
<html>
	<!-- if this is loaded with xhr, then … -->
	
	<!-- … the header is ignored -->
	<head><!-- head definitions --></head>
	<body>
		<!-- … every section is loaded -->
		<section><!-- section content --></section>
		<section><!-- section content --></section>

		<!-- … this script is loaded since it's using data-ff-role=include -->
		<script src="include-me.js" data-ff-role="include"></script>

		<!-- … this script isn't loaded because data-ff-role=include is missing -->
		<script src="ignore-me.js"></script>
	</body>
</html>

Page elements included in the framework:

There are several useful page elements included in the front end framework. These can be used to quickly build out a service. It's either the actual html element, or you can set a class name to add specific behaviour and/or layout.

Page api

Static methods:

FF.Page.getActive

Returns the active page which is visible right now.

FF.Page.getByNode

Returns a page by a given jQuery node

Snippet pages-getByNode.js is missing.

FF.Page.addSection

Adds a section as a page. It may be a section that already lies in the DOM or a section, html snippet that should be added to the DOM as well

Snippet pages-addsection.js is missing.

Object methods:

page.getNode

Returns the section-node, which contains the HTML-presentation of the page

page.equals

Tests if a page equals another page

page.exists

Tests if this page exists

page.findNodes

Find nodes in the page. A shortcut for page.getNode().find)()

page.getId

Returns the id of the page, taken from the id-attribute of the section-node

page.getTitle

Returns the title of the page, taken from the h1 element in the section header

page.hasDataRole

Checks, if the page has a certain data role

page.triggerDomChange

Triggers an event that signals the framework that it should re-init the page, e.g. to add click handlers on links

FF.Service.ready(function() {
	$.get(DATA_URL).done(function(content) {
		$('#main > header').after(content);
		FF.Page.getByNode('#main').triggerDomChange();
	});
});

page.on

Runs a callback if a page event is triggered

Snippet pages-getByNode.js is missing.

Navigation

Use for:

• Navigation between a large number of pages or items
• Multi-level navigation

Implementation:

A navigation menu like the one pictured is a list contained inside a nav-element.

<nav class="ff-menu">
	<ul>
		<li><a href="#page-1">Link 1</a></li>
		<li><a href="#page-2">Link 2</a></li>
		<li><a href="#page-3">Link 3</a></li>
		<!-- […] -->
	</ul>
</nav>

Internal links begin with the hash sign (#), and should link to other pages (section elements) inside the same file. If you load new page with xhr the link requires data-ff-role="xhr". If that attribute is missing the link is treated as external, and is opened in the web browser on the device.

<nav class="ff-menu">
	<ul>
		<li>
			<a href="#page-1">
				Internal link
			</a>
		</li>
		<li>
			<a href="page2.php" data-ff-role="xhr">
				Link on the same domain to a file that's loaded with xhr (ajax)
			</a>
		</li>
		<li>
			<a href="http://other-domain.example.org" data-ff-role="xhr">
				This won't work. Xhr-links has to be on the same domain.
			</a>
		</li>
		<li>
			<a href="page3.php">
				External link on the same domain, will open inside the service.
			</a>
		</li>
		<li>
			<a href="http://page4.example.org" rel="external">
				External link, will open in external web browser.
			</a>
		</li>
	</ul>
</nav>

Technically the navigation is not hierarchical. Instead pages are linked to from a table navigation:

<section data-ff-role="home default swipe-in">
	<!-- header and page element -->
	<nav class="ff-menu">
		<ul>
			<li><a href="#page-1">Menu item 1</a></li><!-- to #page-1 -->
			<li><a href="#page-2">Menu item 2</a></li>
			<li><a href="#page-3">Menu item 3</a></li>
		</ul>
	</nav>
</section>

<section data-ff-role="swipe-in" id="page-1">
	<!-- header and page element -->
	<nav class="ff-menu">
		<ul>
			<li><a href="#page-1-1">Menu item 1.1</a></li>
			<li><a href="#page-1-2">Menu item 1.2</a></li><!-- to #page-1.2 -->
		</ul>
	</nav>
</section>

<section data-ff-role="swipe-in" id="page-1-2">
	<!-- header and page element -->
	<nav class="ff-menu">
		<ul>
			<li><a href="#page-1-2-1">Menu item 1.2.1</a></li>
			<li><a href="#page-1-2-2">Menu item 1.2.2</a></li>
		</ul>
	</nav>
</section>

<!-- additional pages -->

Adding information in navigation lists

Important information like today's date can be added in the navigation lists:

<section data-ff-role="home default swipe-in">
	<nav class="ff-menu">
		<ul>
			<li class="ff-date-above">
				<a href="#test-foo"><date>2012-01-09</date>Date above</a>
			</li>
			<li class="ff-date-before">
				<a href="#test-oof">
					<date>
						<span class="ff-day">Mån</span>
						<span class="ff-date">30 aug</span>
					</date>
					Date before
				</a>
			</li>
		</ul>
	</nav>
</section>

Typography

As a default setting, content spans all the way out to the edges of the screen. If you want your content to make use of the globally used settings for margins you should wrap the content in <article class="ff-content">. Text, lists and normal content should use margins in most cases.

<article class="ff-content">
	<h2>Big headline</h2>
	<h3>Smaller headline</h3>
	
	<p>A normal paragraph with text. Flygande bäckasiner 
	söka hwila på mjuka tuvor. Go fröjd: squaw på bekväm lyxchintz.</p>
				
	<h4>Headline</h4>
	<ul>
		<li>List item</li>
		<li>List item</li>
		<li>List item</li>
	</ul>
</article>

Read more on Graphical guidelines

Tables

Complex tables generally do not work well on small screens. If you can avoid them you should. Often times it is better to simply list content vertically. But if you really need to use tables there are a few alternatives to choose from.

<table>
	<!-- optional header -->
	<caption>Standard table</caption>
	<!-- /optional header -->
	<thead>
		<tr>
			<th>Column 1</th>
			<th>Column 2</th>
			<th>Column 3</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<th>Row 1</th>
			<td>47.23</td>
			<td>18.07</td>
		</tr>
		<tr>
			<th>Row 2</th>
			<td>118.20</td>
			<td>25.37</td>
		</tr>
		<tr>
			<th>Row 3</th>
			<td>199.21</td>
			<td>—</td>
		</tr>
	</tbody>
</table>

There are many classes you can use to style tables:

Alternate rows

Table with alternating rows.

<table class="ff-alternate">
	<caption>Alternate table</caption>
	<thead>
		<tr>
			<th class="ff-minimum-cell">Column 1</th>
			<th>Column 2</th>
			<th>Column 3</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<th>Row 1</th>
			<td class="ff-right">47.23</td>
			<td class="ff-right">18.07</td>
		</tr>
		<tr>
			<th>Row 1</th>
			<td class="ff-right">-127.23</td>
			<td class="ff-right">1800.07</td>
		</tr>
	</tbody>
</table>

Horizontal lines

Tables with horizontal lines uses the class .ff-hlined, additionally you can use .ff-vlined to show vertical lines, see example in the Centered table.

<table class="ff-hlined">
	<caption>Horizontally lined table</caption>
	<thead>
		<tr>
			<th>Column 1</th>
			<th>Column 2</th>
			<th>Column 3</th>
		</tr>
	</thead>
	<tbody>
		<tr>
			<th>Row 1</th>
			<td>47.23</td>
			<td>18.07</td>
		</tr>
		<tr>
			<th>Row 3</th>
			<td>199.21</td>
			<td>—</td>
		</tr>
	</tbody>
</table>

Centered table

.ff-pre and .ff-post is helpful if you want to center text after a certain line. This is useful for centering opening hours where the hours are to be centered. The text in ff-pre and ff-post can be no longer than 40% of the full width of the table.

<table class="ff-vlined">
	<tbody>
		<tr>
			<th>Monday to friday</th>
			<td class="ff-center">
				<span class="ff-pre">9</span> – <span class="ff-post">22, Fr: 23</span>
			</td>
		</tr>
		<tr>
			<th>Saturday</th>
			<td class="ff-center">
				<span class="ff-pre">10</span> – <span class="ff-post">17</span>
			</td>
		</tr>
		<tr>
			<th>Sunday</th>
			<td class="ff-center">
				<span class="ff-pre">New: 11</span> – <span class="ff-post">16</span>
			</td>
		</tr>
	</tbody>
</table>

Wide table

Table with horizontal scroll for wide tables.

<table class="ff-horizontal-scroll">
	<caption>Table with horizontal scroll</caption>
	<tbody>
		<tr>
			<th>Lorem ipsum dolor sit amet</th>
			<td>consectetur adipisicing elit</td>
			<td>sed do eiusmod tempor incididunt</td>
			<td>ut labore et dolore magna aliqua.</td>
			<td>Ut enim ad minim veniam, quis nostrud</td>
		</tr>
	</tbody>
</table>

Form elements

Forms uses the standard form tag with the class .ff-content, together with an ul-tag (unordered list) with the class .ff-form. Every li element can have specific classes that decides the appearence and behaviour. These are the classes you can use:

Buttons

Buttons are mainly used inside forms, but can be used in other contexts. Read more about buttons.

Text fields

A regular form looks like this. The submit button is outside of the ul-element. Text fields use HTML5 input types and attributes to control the behaviour. Be sure to set the right class on the li tag to get the right layout.

<form action="#" class="ff-content">
	<ul class="ff-form">
		<li class="ff-inlinelabel">
			<label for="elt-10">Label</label>
			<input id="elt-10" type="tel" 
					value="070-12345678" required="required" />
		</li>
		<li class="ff-inlinelabel">
			<label for="elt-11">Label</label>
			<input id="elt-11" type="text" pattern="[sS]venss?on"
					placeholder="Placeholder text" />
		</li>
		<li class="ff-inlinelabel">
			<label for="elt-12">Label</label>
			<input id="elt-12" type="email" required="required" />
		</li>
		<li class="ff-input">
			<label for="elt-2">Label above input:</label>
			<input id="elt-2" type="text" />
		</li>
		<li class="ff-textarea">
			<label for="elt-3">Textarea:</label>
			<textarea id="elt-3"></textarea>
		</li>
	</ul>
	<button type="submit">Submit</button>
</form>

Radio buttons

Use radios if the user have a few options. Wrap you radio buttons with <li class="ff-radio">, see example below.

<form action="#" class="ff-content" 
	data-ff-error-message="Error: You need to fill in all the required details!">
	<ul class="ff-form">
		<li class="ff-radio">

			<label for="elt-1">Either this:</label>
			<input  id="elt-1" type="radio" name="example" 
				checked="checked" value="" />

			<label for="elt-2">… or this:</label>
			<input  id="elt-2" type="radio" 
				name="example" value="" />

		</li>
	</ul>
	<button type="submit">Send</button>
</form>

Checkboxes

Wrap you checkboxes with <li class="ff-checkbox">, see example below. See also: Switches.

<ul class="ff-form">
 	<li class="ff-checkbox">

		<label for="elt-4">#1 (normal):</label>
		<input  id="elt-4" type="checkbox" name="number1" />

		<label for="elt-5">#2 (checked):</label>
		<input  id="elt-5" type="checkbox" checked="checked" 
			name="number2" />

	</li>
</ul>

Switches

Switches are similar to Checkboxes, and can be switched on or off.

<ul class="ff-form">

	<li class="ff-toggleonoff">
		<label for="elt-1">On/off button (checkbox):</label>
		<input  id="elt-1" type="checkbox" name="setting1" />
	</li>

	<li class="ff-toggleonoff">
		<label for="elt-2">On/off button (checkbox on):</label>
		<input  id="elt-2" type="checkbox" checked="checked" 
			name="setting2" />
	</li>

</ul>

<form action="serverscript" class="ff-content" 
	enctype="multipart/form-data" 
	data-ff-error-message="An error occured">
	<ul class="ff-form">
		<li class="ff-imageupload">
			<label for="elt-12">Image upload (one)</label>
			<div data-ff-type="ff-image-element" id="singleimage" 
				data-ff-size="1024">
				<input type="file" name="image" value="23" />
			</div>
		</li>
		<li class="ff-imageupload">
			<label for="elt-12">Image upload (max 3)</label>
			<div data-ff-type="ff-image-element(multiple)" 
				data-ff-max-number="3" id="multipleimages">
				<input type="file" name="images[]" />
			</div>
		</li>
	</ul>
	<button type="submit">Send</button>
</form>

<form action="#" class="ff-content" 
	data-ff-error-message="Error in form">
	<!-- form elements -->
</form>

Buttons

Buttons are mainly used inside forms, but can be used in other contexts. They can, for example, be useful if the user needs to perform an action like send something, or request some sort of information.

Full or half-sized buttons

Buttons that utilize the full width of the screen and half of the width of the screen are preferred. The color of the button is determined by the category the service belongs to.

Secondary button

If you want to add a button with less visual weight, with a dimmed out look, it is possible to do so by adding the class ff-dimmed to the button. This is a way of distinguishing two buttons from each other as primary and secondary actions.

A button can either use the element button or use the a-element with a class of ff-button added to it.

<button>Regular button</button>
<a href="#" class="ff-button">Link as regular button</a>

<button type="submit">Submit button</button>
<button type="submit" class="ff-dimmed">Dimmed button</button>

<!-- half width buttons -->

<a href="#" class="ff-half-button">Send</a>
<a href="#" class="ff-half-button ff-dimmed">Cancel</a>

<button class="ff-half-button">Half width button</button>

Share

Share content to social networks like Twitter, Facebook, mail etc.

Example

<!DOCTYPE html>
<html lang="sv">
	<body>
		<section id="ff-social" data-ff-role="swipe-in">
			<header>
		        <h1>FF.Social</h1>
		    </header>
			<div class="ff-content">
				<button class="ff-share" 
					data-ff-share-url="http://example.org" 
					data-ff-share-text="Share this interesting url">
					Share
				</button>
			</div>
		</section>
	</body>	
</html>

Images

Images are used in the same way as usual in html, but keep in mind that the service will be used across a large variety of screen sizes (although only portrait mode is used). Therefore it is often practical to use images that cover the whole width of the screen. How large the image should be is a balancing act between performance and image quality. Generally though, the image should be from 320 to 720 pixels wide.

To make the image cover the width of the screen use classname .ff-full-width.

<!-- image that uses the whole screen width -->
<img src="assets/image.jpg" class="ff-full-width" />

Modal dialogs

Modal dialogues can be used to display many different system messages. The dialogues are like popups, which means that they cover the screen for a duration of time. They remain visible until closed automatically, or until the user responds to a prompt.

API

Available modal boxes:

Creating modals:

var modal = new FF.Modal.ButtonPopup(options); // or ErrorPopup or …

Comparison of modals:

Methods:

You can open several modals, but only show one at a time. If you open several modal boxes, only the first one will be visible - while the rest wait in queue. When the first modal box is closed, the next modal is shown.

FF.Service.ready(function() {
	
	// opens right away
	new FF.Modal.ProgressPopup({
		content: 'Sidan laddas …',
		// it's not meaningful to use a timeout in a
		// ProgressPopup. This is only to keep this example short
		timeout: '2000'
	}).open();

	// opens after the first modal is closed 
	// (in this example, after 2 seconds)
	new FF.Modal.SuccessPopup({
		content: 'Ansökan skickades',
		buttons: { 'true': 'OK'}
	}).open();

});

FF.Service.ready(function() {
	
	new FF.Modal.alert('Service is loaded!');

});

FF.Service.ready(function() {

	// create an object literal with the button choices
	var buttons = {
		htc:     'HTC',
		iphone:  'iPhone',
		samsung: 'Samsung'
	};

	// create and call ButtonPopup 
	new FF.Modal.ButtonPopup({
		    title: 'Multiple choice',
		    content: 'Which smartphone do you like best?',
		    buttons: buttons
	}).open().done(function(value) {
		FF.Modal.alert('You chose ' + buttons[value]);
	});

});

FF.Service.ready(function() {

	new FF.Modal.ErrorPopup({
		content: 'Du måste godkänna användarvillkoren',
		buttons: {'true': 'OK'}
	}).open();

});

// simple example 
var progress= new FF.Modal.ProgressPopup({
	title: 'progress'
}).open().done(function() {
	// do something when ready
});
window.setTimeout(function() { progress.close(); }, 3000);

FF.Service.ready(function() {

	var anAsynchronousRequest = function() {
		var dfd = $.Deferred();
		window.setTimeout(dfd.resolve, 2000);
		return dfd.promise();
	};

	// define and open modal
	var progress = new FF.Modal.ProgressPopup({
		content: 'Please wait'
	}).open();

	anAsynchronousRequest().done(function() {
		// close modal
		progress.close();
	});

});

FF.Service.ready(function() {
	
	new FF.Modal.SuccessPopup({
		content: 'Your account is ready.',
		timeout: 3000
	}).open();

});

new FF.Modal.SuccessPopup({
	content: 'Thanks for registering, your account is now ready to use.',
	buttons: {'true': 'OK'}
}).open();

Widgets

Other useful widgets.

Tabs

Use tabs if you are building a service with only two or three views ("pages"), the tabs makes it easy to switch between the views.

Use to:

• Switch between 2-3 (more than 3 does not work) sections on the same page.

Implementation:

<section>
	<header>
		<h1>Tabs</h1>
	</header>
	<ul class="ff-tab-navigation" data-ff-target="my-tabs">
		<li data-ff-role="default">Tab 1</li>
		<li>Tab 2</li>
		<li>Tab 3</li>
	</ul>
	<div data-ff-role="tab-group" id="my-tabs" class="ff-content">
		<section>
			<h1>Tab 1</h1>
			<p>Lorem ipsum dolor sit amet, consectetur adipisicing elit, sed do.</p>
		</section>
		<section>
			<h1>Tab 2</h1>
			<p>Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris.</p>
		</section>
		<section>
			<h1>Tab 3</h1>
			<p>Duis aute irure dolor in reprehenderit in voluptate velit esse.</p>
		</section>
	</div>
</section>

Accordions

Accordions give a good overview over a lot of information when you don't want the user to switch to another page.

Use to:

• Show/hide sections on a page

Implementation:

<section>
	<header>
		<h1>Show/hide sections</h1>
	</header>
	<dl class="ff-accordion">
		<dt>Section one</dt>
		<dd>Lorem ipsum dolor sit amet, consectetur adipisicing elit.</dd>
		<dt>Section two</dt>
		<dd>Quis nostrud exercitation ullamco laboris nisi ut aliquip.</dd>
		<dt>Section three</dt>
		<dd>Eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat.</dd>
	</dl>
</section>

Swipe containers

Galleries is an easy way to show more than one image where you let the user swipe to navigate between the images.

Use to:

• Show a gallery of images

Implementation:

<section>
	<header>
		<h1>Gallery</h1>
	</header>
	<ul class="ff-swipe">
		<li><img src="img/gallery1.jpg" alt="gallery1" /></li>
		<li><img src="img/gallery2.jpg" alt="gallery2" /></li>
		<li><img src="img/gallery3.jpg" alt="gallery3" /></li>
	</ul>
</section>

Layout independent methods

General methods of the framework you can call directly from your javascript to simplify things for your service.

	$('#open-in-browser').submit(function(e) {
		e.preventDefault();
		FF.App.openInBrowser($('#url').val());
	});

FF.Console.info('This is an information');

FF.Console.log('This is a log message');

FF.Console.warn('This is a warning');

FF.Console.error('This is an error');

{
	"firstName": "Robin",
	"lastName": "Robinsson",
	"phone": "070 000 00 00",
	"email": "someone@example.org"
}

FF.GoogleAnalytics.trackEvent('Search', 'Search:' +  needle);

FF.GoogleAnalytics.trackPageView(location.href);

url = 'http://example.org/form/request';
formData = [
	{
		name:  'firstname',
		value: 'Robin'
	},
	{
		name:  'lastname',
		value: 'Robinsson'
	},
	{
		name:  'myimage',
		value: imageId
	}
];
headers = {
	"X-Custom-Foo": "A custom header",
	"X-Custom-Bar": "Another custom header"
};
FF.HttpRequest.requestPost(url, formData, headers)
	.done(function(status, response, responseHeaders) {
		FF.Modal.alert(status);
	})
	.fail(function(code, message) {
		FF.Modal.alert('Error ' + code);
	})
;

var config = {
	imageQuality: 80,
	imageSize: 2048
};

FF.Media.requestImage(config)
	.done(function(id, thumbUrl, previewUrl) {
		$('<img>')
			.attr('src', thumbUrl)
			.addClass('thumb')
			.appendTo('#image-container')
		;
	})
	.fail(function(code, message) {
		$('<p>')
			.text('image could not be loaded')
			.addClass('error')
			.appendTo('#image-container')
		;
	})
;

FF.Position.requestPosition(true)
	.done(function(lat, lng, reverseData) {
		new FF.Modal.alert('Ah, so you are in ' + reverseData.country + '?');
	})
	.fail(function(code, message) {
		new FF.Modal.ErrorPopup({
			content: 'Error: ' + message,
			buttons: {'true': 'OK'}
		}).open();
	});

if (FF.Version.compare(FF.Version.getFrameworkVersion(), '2', 
	FF.Version.HIGHER_OR_EQUAL)) {
	// code for Framework version 2.0 or higher
}

if (FF.Version.compare(FF.Version.getAppVersion(), '2.0.1', 
	FF.Version.LOWER)) {
	// code for App version lower than 2.0.1
}