This is the source code to support our Firefox OS workshops.
Requirements:
- Firefox Nightly, the bleeding-edge version of Firefox.
- Firefox OS Simulator, which is actually an extension for Firefox. Open this link from Firefox to install it.
You can just download the code, fork it or clone it with Git:
git clone [email protected]:belen-albeza/ffxos-workshop.gitTo run the apps in the simulator:
- Open Firefox Nightly.
- Go to
Tools / Web Developer / Firefox OS Simulator. - Click on the
Add Directorybutton. - Browse and select one of the examples'
manifest.webappfiles. - Enjoy!
To run the apps locally in Firefox Nightly (very useful for development), you will need to launch a local server in your app's directory.
If you have Python in your system (comes pre-installed in Mac OS X and most Linux distros), you can easily run it by cd to the desired app directory and executing:
python -m SimpleHTTPServer- Open the URL of your app in Firefox Nightly. If you use the previous Python line, then just go to
0.0.0.0:8000. - Enable the Responsive View so it mimics how it's seen in the device. Go to
Tools / Web Developer / Responsive View
Located at hello-world.
This a simple Hello World application, that shows how to set up a minimal manifest (the manifest.webapp file) so your web app is actually a Firefox OS app.
You need to create a manifest.webapp file for your app. You can find documentation in the MDN.
Note that it is mandatory that your app has icons! You will need 60x60, 120x120 and 128x128 images.
You can see if your manifest file is valid in the Firefox OS Simulator.
Located at hello-world-gaiabb.
This shows how to include and use Gaia Building Blocks in your app.
First you need to download the Building Blocks and then copy the CSS stylesheets and their folders of the specific blocks that you want to use. In this example we are using the headers block, so we copied the style/headers.css file and the style/headers folder to our application.
There are additional blocks you can use in style_unstable too. And there's also a util.css file with some CSS rules that will make your life easier (for instance, it sets a reasonable base font-size for the application). We have included this stylesheet in this demo.
The standard font that comes with Firefox OS is Feura Sans, which you can download (to be able to test your apps in a desktop browser).
After you have included the CSS stylesheets in your HTML document, you need to add the attribute role="application" to your body tag. If you don't do this, the Building Blocks won't work.
To put a Building Block in your app, you need to use a specific HTML code. You can grab this code from the index.html file in each Building Block folder, or from the Building Firefox OS page. For instance, this is the code that you need to use for a simple heading:
<section role="region">
<header>
<h1>Hello Gaia BB!</h1>
</header>
</section>One common pattern in applications is to have the header always visible on top, and then make only the rest of the window scrollable. You can have this behavior easily if you include the util.css stylesheet in your app. Then you need to add the class fixed to the header, and put your content inside an <article> with the classes scrollable header. For example:
<body role="application">
<section role="region">
<header class="fixed">
<h1>Rainbows</h1>
</header>
<article class="scrollable header">
<p>Sparkling unicorns!</p>
</article>
</section>
</body>Located at webapi-contacts.
You need to specify the permissions that you need the user to grant. Also, the Contacts WebAPI is only available at privileged or certified apps; that is, apps from the Marketplace or system apps.
To mark our app as privileged (to be distributed via a Marketplace), you need to update the manifest with the type setting. Permissions are stored int he permissions keys. You can find a list of all permissions and their different options in the MDN.
For this demo, we need to ask for reading access, so we can display the contacts list.
"type": "privileged",
"permissions": {
"contacts": {
"description": "Required to display your contacts",
"access": "readonly"
}
}When the app tries to access the contacts, a dialog to grant permission to do so will be shown to the user:
The Contacts WebAPI is accessed via a ContactManager stored in navigator.mozContacts. This object is not still ready on the desktop version of Firefox, so you will need to use the simulator to try this API.
The method to read the contacts is called getAll, and we can pass an Object containing the sorting and filter options. We need to supply two callbacks: onsuccess (will be called for each contact read) and onerror (it will be called if the user doesn't grant permission).
function readContacts() {
var contacts = navigator.mozContacts.getAll({});
contacts.onsuccess = function (event) {
// ...
};
contacts.onerror = function (event) {
// ...
}
}The Contacts WebAPI is asynchronous. This is very useful, because this list can be really long, and we don't want to block the UI while we are loading it. The way it works is by passing a cursor to the callback (it's the event.target). This cursor will have a contact property if a contact has been read. Once we have fetched this contact, we need to call cursor.continue() to read the next one (another call to onsuccess will be made).
About the contact object, you can take a look at the documentation to see what it contains. Some useful properties are name and tel. This last one is actually an array, since contacts can have multiple phone numbers!
contacts.onsuccess = function (event) {
var cursor = event.target;
if (cursor.contact) { // we have read a contact
console.log(contact.name);
cursor.continue(); // load the next one
}
else { // we have finished reading contacts
// ...
}
}
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent