Tizen for Dummies

Tizen™

Tizen Developer Conference Edition

by Jon Lansdell, Cheng Luo, and Michelle Somerville

Tizen™ For Dummies®, Tizen Developer Conference Edition Published by John Wiley & Sons, Ltd The Atrium Southern Gate Chichester West Sussex PO19 8SQ England For details on how to create a custom For Dummies book for your business or organisation, contact [email protected]. For information about licensing the For Dummies brand for products or services, contact [email protected]. Visit our Home Page on www.customdummies.com Copyright © 2013 by John Wiley & Sons Ltd, Chichester, West Sussex, England All Rights Reserved. No part of this publication may be reproduced, stored in a retrieval system or transmitted in any form or by any means, electronic, mechanical, photocopying, recording, scanning or otherwise, except under the terms of the Copyright, Designs and Patents Act 1988 or under the terms of a licence issued by the Copyright Licensing Agency Ltd, 90 Tottenham Court Road, London, W1T 4LP, UK, without the permission in writing of the Publisher. Requests to the Publisher for permission should be addressed to the Permissions Department, John Wiley & Sons, Ltd, The Atrium, Southern Gate, Chichester, West Sussex, PO19 8SQ, England, or emailed to permreq@ wiley.com, or faxed to (44) 1243 770620. Trademarks: Wiley, the Wiley logo, For Dummies, the Dummies Man logo, A Reference for the Rest of Us!, The Dummies Way, Dummies Daily, The Fun and Easy Way, Dummies.com and related trade dress are trademarks or registered trademarks of John Wiley & Sons, Inc. and/or its affiliates in the United States and other countries, and may not be used without written permission. Tizen™ is a trademark of the Linux Foundation. All other trademarks are the property of their respective owners. John Wiley & Sons, Inc., is not associated with any product or vendor mentioned in this book. LIMIT OF LIABILITY/DISCLAIMER OF WARRANTY: THE PUBLISHER, THE AUTHOR, AND ANYONE ELSE INVOLVED IN PREPARING THIS WORK MAKE NO REPRESENTATIONS OR WARRANTIES WITH RESPECT TO THE ACCURACY OR COMPLETENESS OF THE CONTENTS OF THIS WORK AND SPECIFICALLY DISCLAIM ALL WARRANTIES, INCLUDING WITHOUT LIMITATION WARRANTIES OF FITNESS FOR A PARTICULAR PURPOSE. NO WARRANTY MAY BE CREATED OR EXTENDED BY SALES OR PROMOTIONAL MATERIALS. THE ADVICE AND STRATEGIES CONTAINED HEREIN MAY NOT BE SUITABLE FOR EVERY SITUATION. THIS WORK IS SOLD WITH THE UNDERSTANDING THAT THE PUBLISHER IS NOT ENGAGED IN RENDERING LEGAL, ACCOUNTING, OR OTHER PROFESSIONAL SERVICES. IF PROFESSIONAL ASSISTANCE IS REQUIRED, THE SERVICES OF A COMPETENT PROFESSIONAL PERSON SHOULD BE SOUGHT. NEITHER THE PUBLISHER NOR THE AUTHOR SHALL BE LIABLE FOR DAMAGES ARISING HEREFROM. THE FACT THAT AN ORGANIZATION OR WEBSITE IS REFERRED TO IN THIS WORK AS A CITATION AND/OR A POTENTIAL SOURCE OF FURTHER INFORMATION DOES NOT MEAN THAT THE AUTHOR OR THE PUBLISHER ENDORSES THE INFORMATION THE ORGANIZATION OR WEBSITE MAY PROVIDE OR RECOMMENDATIONS IT MAY MAKE. FURTHER, READERS SHOULD BE AWARE THAT INTERNET WEBSITES LISTED IN THIS WORK MAY HAVE CHANGED OR DISAPPEARED BETWEEN WHEN THIS WORK WAS WRITTEN AND WHEN IT IS READ. Wiley also publishes its books in a variety of electronic formats. Some content that appears in print may not be available in electronic books. ISBN: 978-1-118-73606-7 Printed and bound in the United States 10 9 8 7 6 5 4 3 2 1

Contents at a Glance Introduction....................................................... 1 Part I: Introducing Tizen..................................... 5

Chapter 1: Getting an Inside Look at Tizen............................................. 7 Chapter 2: Exploring the Tizen Architecture........................................ 17

Part II: Getting Practical.................................. 29

Chapter 3: Getting Started...................................................................... 31 Chapter 4: Piecing Together the Application Jigsaw........................... 47 Chapter 5: Testing and Debugging......................................................... 73 Chapter 6: Porting Your Web App to Tizen.......................................... 91

Part III: Tizen in Detail................................... 107

Chapter 7: Building Your UI.................................................................. 109 Chapter 8: Taking Advantage of Location-Based Services................ 121 Chapter 9: Working with Multimedia................................................... 129 Chapter 10: Using Hardware in Tizen.................................................. 145 Chapter 11: Messaging........................................................................... 159 Chapter 12: Working with Contacts..................................................... 171 Chapter 13: Getting Organized with Calendars.................................. 181

Part IV: The Part of Tens................................. 189

Chapter 14: Ten Really Useful Resources........................................... 191 Chapter 15: Ten Reasons You Should Develop for Tizen.................. 195

Acknowledgments.......................................... 199

Table of Contents Introduction........................................................ 1 About This Book......................................................................... 1 Conventions Used in This Book ............................................... 1 Who Should Read This Book..................................................... 2 How This Book Is Organized..................................................... 2 Part I: Introducing Tizen.................................................. 3 Part II: Getting Practical................................................... 3 Part III: Tizen in Detail...................................................... 3 Part IV: The Part of Tens.................................................. 3 Icons Used in This Book............................................................. 4 Where to Go from Here.............................................................. 4

Part I: Introducing Tizen...................................... 5 Chapter 1: Getting an Inside Look at Tizen. . . . . . . . . . . . 7 Discovering Tizen....................................................................... 7 Focusing on HTML5.......................................................... 8 Tizen’s place in the mobile world.................................. 8 Figuring Out What Makes Tizen Different.............................. 10 Tizen is based on standards......................................... 10 Tizen is open................................................................... 11 Tizen is innovative.......................................................... 12 Tizen has industry support........................................... 12 Comparing Tizen to Other Platforms..................................... 12 Getting Familiar with the Tizen Association......................... 13 Getting Involved........................................................................ 13 Submitting patches......................................................... 14 Mailing list and IRC......................................................... 14 Forums............................................................................. 15 Bug tracker...................................................................... 15

Chapter 2: Exploring the Tizen Architecture . . . . . . . . . 17 Introducing Web Apps............................................................. 18 The web runtime............................................................. 19 Installer............................................................................ 20 Runtime core................................................................... 20 Plugin core....................................................................... 21 Using Tizen Web APIs............................................................... 21

vi

Tizen For Dummies, Developer Conference Edition Exploring the Tizen Device APIs............................................. 22 Tizen................................................................................. 23 Alarm................................................................................ 24 Application...................................................................... 24 Bookmark......................................................................... 24 Bluetooth......................................................................... 24 Calendar........................................................................... 24 CallHistory....................................................................... 24 Contacts........................................................................... 25 Content............................................................................. 25 DataControl..................................................................... 25 DataSynchronization...................................................... 25 Download......................................................................... 25 Filesystem........................................................................ 25 MessagePort.................................................................... 26 Messaging........................................................................ 26 NetworkBearerSelection................................................ 26 NFC................................................................................... 26 Notification...................................................................... 26 Package............................................................................ 27 Power............................................................................... 27 Push.................................................................................. 27 SecureElement................................................................ 27 SystemInfo....................................................................... 27 SystemSetting.................................................................. 27 Time.................................................................................. 28

Part II: Getting Practical.................................. 29 Chapter 3: Getting Started. . . . . . . . . . . . . . . . . . . . . . . . . 31 Installing the IDE....................................................................... 32 Creating Your First Tizen Web App........................................ 34 Using a sample app......................................................... 35 Using your own template............................................... 35 Importing an existing project........................................ 37 Tizen web application.......................................... 37 Other web applications....................................... 38 Writing the Code....................................................................... 39 HTML Web Page Editor.................................................. 39 HTML Preview................................................................. 41 CSS Preview..................................................................... 41 Minifying CSS and JavaScript.................................................. 42 CSS.................................................................................... 42 JavaScript........................................................................ 43

Table of Contents

vii

Building Your Project............................................................... 43 Running Your Project............................................................... 43 Help Is on the Way.................................................................... 44 Help documentation....................................................... 44 Sample applications....................................................... 45

Chapter 4: Piecing Together the Application Jigsaw . . . . 47 Examining the Pieces................................................................ 48 The Application Package......................................................... 48 Localized content........................................................... 49 The configuration file..................................................... 50 Breaking down the config file............................. 50 config.xml the easy way: the Configuration Editor......................................... 52 Start file............................................................................ 59 JavaScript........................................................................ 59 Style sheet....................................................................... 60 Application icon.............................................................. 60 Author signature............................................................. 60 Distributor signature...................................................... 61 Third-party source code or libraries........................... 61 Adding source code or libraries to a project......62 Adding source code or libraries in index.html......62 Putting the Pieces Together.................................................... 63 Example 1: A 5-minute application............................... 63 Creating the application project........................ 64 Editing the icon file.............................................. 64 Editing the configuration document.................. 64 Editing the start file.............................................. 65 Running the application...................................... 65 Example 2: Something a bit more complicated.......... 66 Using the Tizen APIs............................................ 68 Looking at index.html.......................................... 68 Figuring out what is in main.js............................ 70 Defining style attributes in style.css.................. 71

Chapter 5: Testing and Debugging. . . . . . . . . . . . . . . . . . 73 Testing Your App...................................................................... 74 Running in the Simulator............................................... 74 Testing with the Emulator............................................. 75 Using the Emulator Manager to create an image............................................ 76 Launching an Emulator instance........................ 78 Using the Connection Explorer........................... 79

viii

Tizen For Dummies, Developer Conference Edition Running your application in the Emulator........ 80 Using the Event Injector...................................... 80 Testing your app on a device........................................ 82 Connecting the device......................................... 83 Running your app on the device........................ 83 Tracking Down the Bugs.......................................................... 83 Debugging in the Simulator........................................... 84 Debugging in the Emulator............................................ 85 Debugging on the device............................................... 86 Debugging JavaScript..................................................... 86 Using the Smart Development Bridge.......................... 88 Using SDB commands.......................................... 88 Discovering the connected devices................... 89

Chapter 6: Porting Your Web App to Tizen. . . . . . . . . . . 91 Everything You Wanted to Know about Web Apps (But Were Afraid to Ask)...................................................... 92 Web apps on different platforms.................................. 93 Tools and frameworks................................................... 94 Standards......................................................................... 94 Distribution..................................................................... 95 Porting Problems Solved......................................................... 95 Handling different package formats............................. 96 Making your layout flexible........................................... 98 Fixing inconsistent behavior....................................... 101 Porting device specific libraries................................. 103 Making your app more portable................................. 104

Part III: Tizen in Detail................................... 107 Chapter 7: Building Your UI. . . . . . . . . . . . . . . . . . . . . . . 109 Delving into the Nuts, Bolts, and jQuery Mobile................ 110 Embedded custom data attributes............................. 110 Page structure............................................................... 110 Events............................................................................. 111 Exploring the Tizen UI Widgets............................................. 112 The UI Builder: Just Drag and Drop...................................... 113 Choosing your widgets................................................ 114 Implementing events in the UI builder....................... 116 Adding Some Flourish to Your UI......................................... 117

Table of Contents

Chapter 8: Taking Advantage of Location-Based Services . . . . . . . . . . . . . . . . . . . . . . 121 Finding Your Way.................................................................... 122 Displaying a Map..................................................................... 122 Finding an Address................................................................. 125 Google Geocoder API................................................... 125 X Marks the Spot..................................................................... 126

Chapter 9: Working with Multimedia . . . . . . . . . . . . . . 129 Introducing the Multimedia APIs.......................................... 130 Discovering Content............................................................... 130 Content........................................................................... 131 Getting permission....................................................... 132 Example: Creating a playlist........................................ 132 Capturing Images and Video................................................. 134 Using the Application Manager................................... 134 Application Control object................................ 134 Launching an application.................................. 135 Example: Taking a photo............................................. 136 Playing Audio and Video........................................................ 138 Example: Playing local audio files.............................. 138 Example: Playing local video files............................... 140 Multimedia Streaming............................................................ 141 webkitGetUserMedia.................................................... 141 Example: Streaming video from your device’s camera............................................... 142

Chapter 10: Using Hardware in Tizen . . . . . . . . . . . . . . 145 Introducing NFC...................................................................... 146 Using NFC in your Tizen Apps.................................... 147 Setting up NFC............................................................... 149 Setting up the listeners................................................ 149 Reading a tag....................................................... 150 Writing a tag........................................................ 152 Using NFC in peer-to-peer mode................................. 153 Detecting Device Orientation................................................ 154 Detecting Device Motion........................................................ 157 Using the Vibration API.......................................................... 158

ix

x

Tizen For Dummies, Developer Conference Edition

Chapter 11: Messaging. . . . . . . . . . . . . . . . . . . . . . . . . . . 159 Introducing the Messaging API............................................. 160 Message service............................................................ 160 Message structure........................................................ 160 Message............................................................... 161 MessageBody...................................................... 161 MessageAttachment........................................... 161 Message storage................................................. 162 Getting Permission................................................................. 162 Getting Practical: Searching for Messages.......................... 162 Creating the page.......................................................... 163 Filling the message list................................................. 165 Initialisation........................................................ 165 Searching for messages..................................... 165 Drawing the list................................................... 166 Searching the message list.......................................... 168 Processing user input........................................ 168 Searching for messages..................................... 169

Chapter 12: Working with Contacts. . . . . . . . . . . . . . . . 171 Meeting the Key Personnel.................................................... 171 Address books.............................................................. 172 Contacts......................................................................... 173 Getting Permission................................................................. 174 Managing Your Contacts........................................................ 174 Adding a contact........................................................... 174 Retrieving a contact..................................................... 176 Deleting contacts.......................................................... 177 Exporting a contact...................................................... 178

Chapter 13: Getting Organized with Calendars. . . . . . 181 Introducing the Calendar API................................................ 181 CalendarManager.......................................................... 182 Calendar......................................................................... 182 CalendarItem................................................................. 182 Getting Permission................................................................. 183 Creating a Task........................................................................ 184 Retrieving Tasks...................................................................... 185 Setting an Alarm...................................................................... 187

Table of Contents

Part IV: The Part of Tens................................. 189 Chapter 14: Ten Really Useful Resources. . . . . . . . . . . 191 JavaScript: The Definitive Guide .......................................... 191 Douglas Crockford’s JavaScript Lectures............................ 192 JavaScript: The Good Parts................................................... 192 JavaScript Patterns................................................................. 192 Browser Developer Tools...................................................... 192 JavaScript Libraries................................................................ 193 Keeping up with HTML5......................................................... 193 Smashing Magazine................................................................ 194 The Linux Foundation on YouTube...................................... 194 And . . . You.............................................................................. 194

Chapter 15: Ten Reasons You Should Develop for Tizen . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 195 Tizen Is Easy to Learn............................................................ 195 Tizen Doesn’t Reinvent the Wheel........................................ 196 Tizen Supports the Latest Standards................................... 196 Tizen Supports These Standards Very Well............................. 196 Tizen Fills in the Gaps............................................................ 196 Tizen Is Consistent................................................................. 197 You Can Easily Get Help......................................................... 197 You Can Give Back.................................................................. 197 Tizen Isn’t Just for Mobile..................................................... 197 Tizen Isn’t Just for Web Developers..................................... 197

Acknowledgments........................................... 199

xi

xii

Tizen For Dummies, Developer Conference Edition

Introduction

W

elcome to Tizen For Dummies. This book will be your best friend to help you understand the technologies and story behind the Tizen platform. If you already know about web technologies, such as HTML and JavaScript, you can use the information in these pages to give you a head start in developing Tizen apps.

About This Book The information in this book is based on the Tizen 2.1 release. Tizen is a fast-moving, evolving project, and you may be running a later version. Changes happen, bugs are fixed, behaviors change, but the key concepts don’t. These key concepts are the heart of this book. The Tizen SDK Help will always provide the most up-to-date reference information. Check out https://developer. tizen.org and the resources listed throughout this book to ensure that you stay up to date.

Conventions Used in This Book When this book was printed, some code or web addresses may have needed to break across two lines of text. If that happened, rest assured that we haven’t put in any extra characters (such as hyphens) to indicate the break. So, when using this code or one of these web addresses, just type exactly what you see in this book, pretending as though the line break doesn’t exist. When you’re choosing a series of menu commands, we use ➪ to indicate the different commands you’re choosing. So when you see choose File➪New➪Tizen Web Project, you should simply click the File menu, click New from the menu that appears, and then click Tizen Web Project.

2

Tizen For Dummies, 2nd Edition In addition, we often refer you to the Tizen website or the SDK Help file. You can open the Help file from within the Tizen IDE by choosing Help➪Help Contents. You can also find help online at the Tizen website at https://developer.tizen. org/documention.

Who Should Read This Book When writing this book, we made a few assumptions about you, the reader. You’re either: ✓ A software engineer with experience developing for the desktop, but no experience developing mobile apps. You’re keen to start developing mobile apps and want to know what Tizen offers. ✓ A technical manager, evaluating the opportunities Tizen offers for your next project on mobile. ✓ A developer with a good grasp of web technologies, such as HTML, JavaScript, and CSS, who is curious about Tizen. (Don’t worry if you’re not a web guru; we don’t expect you to be.) ✓ A parent with small children, looking for something to read during the precious hours while the kids sleep. If any of the preceding applies to you, or you just stumbled upon this book and found your curiosity piqued, the information presented here will give you a good idea of what the Tizen platform is and how you can start developing for it.

How This Book Is Organized To help you find the information you need, this book is divided into four parts.

Introduction

3

Part I: Introducing Tizen If you want to know what makes Tizen different and discover Tizen’s place in the mobile landscape, you can find the answers in this part. We examine how Tizen compares to other platforms and explain the importance of the Tizen community. We also give you a tour of the components of the Tizen platform, explain how web applications fit in and provide you with a quick summary of the Tizen Device APIs.

Part II: Getting Practical Part II encourages you to fire up the Tizen IDE and start developing apps. Think of the first three chapters of this part as a Tizen orientation trilogy, where you discover everything you need to know to build your first Tizen app. In addition, if you’ve built a web app for another platform and want to move it to Tizen, we explain many of the issues you’ll encounter when porting.

Part III: Tizen in Detail Part III explains the Tizen Device APIs in more detail. We don’t include all the APIs or try to replace the information you can find in the Tizen SDK Help. Instead, we focus on what you need to know to build a fully featured Tizen web app.

Part IV: The Part of Tens No For Dummies book would be complete without a part of tens. In this part, you discover ten really useful resources and ten reasons why you should develop for Tizen.

4

Tizen For Dummies, 2nd Edition

Icons Used in This Book Throughout this book, you can see small pictures in the margins. These icons have special meanings:



The Tip icon points out important information that can save you time or make a task easier. This icon marks information you won’t want to forget.

Be careful when you see this icon!



This icon highlights information that is nice to know but not crucial to the discussion. Feel free to skip this information if you’re not interested in it.

Where to Go from Here The content in this book is designed to be easy to navigate. Dip in and dip out of each chapter as the mood takes you. We don’t expect you to read the book cover to cover, but if you do make it to the end before your friends do, please don’t spoil the ending. Think of this book as your first stop on your Tizen development journey. We explain the concepts, identify gotchas, provide hints, tips, and handy sample code, and draw on our own experience to help kick-start your Tizen development efforts. If you’re an experienced web developer, you may want to focus on the chapters that explain Tizen device APIs and show you how to apply your existing knowledge of HTML and JavaScript to create Tizen web apps. If you’re new to web development, it may feel at times as if you’re navigating uncharted waters. Think of this book as your map. You discover how Tizen web applications are created using a mixture of technologies, including W3C APIs, third-party Javascript libraries, and Tizen-specific APIs, all mixed together to create powerful apps.

Part I

Introducing Tizen

T

In this part . . .

his part is your Tizen orientation session, where we issue you with your virtual map, compass and backpack as you start to explore this new platform. You learn about Tizen’s place in the mobile landscape and what makes this mobile platform different from the rest. You explore the structure of a typical open source platform, see where Tizen fits in and find out how you can get involved in the Tizen community. In Chapter 2 you learn how Tizen is organized and discover how Tizen web applications look and behave like native ones. We also explore Tizen’s support for web standards and introduce the Tizen device APIs which allow you to create powerful and feature-rich apps.

Chapter 1

Getting an Inside Look at Tizen In This Chapter ▶ Discovering what makes Tizen unique ▶ Becoming part of the Tizen community

Y

ou may have heard of Tizen, but not know what it is. No worries! In this chapter, you discover Tizen’s place in the mobile world and some of the many reasons why this open source software platform is one of a kind. You also find out how Tizen compares to other mobile platforms and how to become involved in the Tizen community.

Discovering Tizen Tizen is an open source, standards-based, cross-architecture device software platform designed to find a place in everything from smartphones to smart TVs and beyond. The Linux Foundation announced the Tizen project in September 2011 and the Tizen Association was formed in 2012 to drive industry engagement and support for the project. Currently, the main contributors to Tizen are Samsung and Intel, but with increasing industry support, you can expect more organizations to become active contributors. Currently, the Tizen Association board has 12 members from different industry sectors, including many mobile operators.

8

Part I: Introducing Tizen Tizen has solid open source foundations, and it makes use of established open source components, such as WebKit, GStreamer, Xorg, and Connman. If you want to know how Tizen compares to other open source mobile platforms, see the section ‘Tizen’s place in the mobile world,’ later in this chapter.



You can find out more about Tizen and the Tizen Association at www.tizen.org and www.tizenassociation.org.

Focusing on HTML5 Tizen’s primary focus for application development is HTML5, which is rapidly emerging as the preferred development environment for mobile applications. Tizen support for HTML5 is extensive and powerful. It includes support for most of the major W3C APIs included under the banner of HTML5, as well as many supplementary web APIs. The first prerelease version of Tizen emerged blinking into the spotlight of the developer community in January 2012. The final 1.0 version, code named Larkspur and including Linux and Windows versions of the SDK and the Tizen Web UI framework, was released in May, just before the first Tizen Developer’s Conference in San Francisco. At this event, the attendees were given a reference device, known as the software development platform (SDP), or lunchbox, as it is nicknamed due to its less than svelte appearance. The version of Tizen we used to create this book is 2.1, which was released in May 2013, and introduced many new web APIs. The Tizen 2.0 SDK was the first to include C++ APIs which you can use to create native apps. However, web apps are still the main way of developing for Tizen and that’s the focus of this book.

Tizen’s place in the mobile world Our years of mobile development has taught us one simple fact – creating a mobile platform is hard. The average smart device includes a dazzling range of technologies that put desktop computers to shame. We expect our smart devices to entertain us, help us find our way home, run our schedules and just occasionally make phone calls. No one person can be

Chapter 1: Getting an Inside Look at Tizen

9

expected to be an expert in everything from application development to the low-level technologies that enable your phone to talk to the cellphone towers. Figure 1-1 shows the different perspective that users, application developers and platform developers have on the way a typical open source platform is organised. Put yourself in the shoes of each of these people as we show you how Tizen fits in to the mobile open source landscape.

Figure 1-1: Different perspectives on the layers of a mobile open source platform

The way platforms are organized is often described in terms of an onion. You gradually peel away the layers until you reach the core. At the top layer, we have applications and services. It’s what’s contained here that helps end users make their decision about which device to buy. They choose their devices according to what apps and services are available for them to use. Next we come to the platform level. This layer is where you’ll find the APIs and SDKs that allow developers to create applications. It’s where you’ll find Tizen and the APIs discussed in this book. Tizen has many similarities to other platforms, but you discover the differences too.

10

Part I: Introducing Tizen Delving deeper we come to the middleware. Many middleware components will come from conventional desktop open source projects. Different platforms will pick and choose which open source components to include. The great thing about open source software is the range of components available. The lowest layer is the kernel. For open source mobile platforms, this layer will generally be a Linux kernel. The kernel interacts with middleware components to talk to the hardware. It’s the middleware layer that the platform developers, who contribute to the components of the platform, will be most interested in.

Figuring Out What Makes Tizen Different When Tizen was announced, some of the most common questions asked by developers, analysts and users included whether a new platform was needed at all and what makes Tizen stand out from the crowd. In this book, we attempt to answer some of these questions, but for now, here are four ways in which Tizen is different from the rest.

Tizen is based on standards HTML5 is a set of standards that enjoys support from across the industry, and it’s a standard that Tizen supports very well. HTML5 supports multiple browsers, operating systems, and devices. In its latest incarnation, HTML5 provides greater access to device hardware, advanced audio and video capabilities, and more flexibility for design and layout. Using HTML5, developers can create cross-platform applications, writing the code once and running it on multiple platforms. The extent to which a platform supports the HTML5 specification is vital for developers who want to make the most of the latest features.

Chapter 1: Getting an Inside Look at Tizen

11

Tizen supports most of the official HTML5 standards, along with some supplementary and legacy standards. Designed to get the most out of HTML, JavaScript, and CSS, Tizen’s web engine is tuned to within an inch of its life to squeeze best performance out of these technologies. Not only does the Tizen web engine (based on WekKit2 since Tizen 2.0) perform well, its web browser also scores highly in web standards compliance tests, finishing first according to the scores from http://html5test.com, which test how well a browser supports HTML5 specifications.

Tizen is open As an open source software platform, Tizen provides many opportunities for both individuals and Original Equipment Manufacturers (OEMs) – the people that make the phones. Anyone can grab the source code and customize it to meet their own needs. Any OEM can ship Tizen devices with a customized user interface, app store, or set of services. Open source projects also encourage collaboration. Software engineering is changing, and it’s a challenge for an individual or even an organization to build something without using open source code. Collaborating with the open source community is a more efficient and cost-effective way of development, and it generally avoids re-inventing the wheel.

Defining open At any gathering of open source developers, the one subject guaranteed to cause an argument – aside from which pizza restaurant to order from – is ‘What is the definition of open source?’ In this book, we describe Tizen as open source because the source

code to the platform is freely available, anyone can download it, and you can use it for any purpose in any project. We accept that this may not meet everyone’s definition of open source software, but this is our definition, and we’re sticking to it.

12

Part I: Introducing Tizen

Tizen is innovative Innovation can come from many sources. It may be an idea from an individual or an organisation’s R&D projects, but most innovation comes from collaboration. The Tizen Project brings these different resources and knowledge together. Everyone can contribute ideas and innovations to the platform, and everyone can benefit. Innovation doesn’t stop at collaboration; it also brings differentiation to a product and leads to more choice for end users.

Tizen has industry support One lesson learned from previous open source platforms is that being open source doesn’t necessarily guarantee success or innovation. A project must have strong industry support. The Tizen Association board includes many operators and device manufacturers, and a strong ecosystem built around Tizen offers opportunities far beyond smartphones. You can look forward to your applications running not only on mobile phones, but also on in-vehicle infotainment systems, notebooks, tablets, and Smart TVs. At the time of writing, the board members of the Tizen Association are Intel, Samsung, Fujitsu, Huawei, KT, NEC Casio Mobile Communications, NTT docomo, Orange, Panasonic Mobile Communications, SK Telecom, Sprint and Vodafone.

Comparing Tizen to Other Platforms Tizen’s openness contrasts with closed, proprietary platforms, such as iOS, Blackberry 10 and Windows Phone, for which the source code is not available. The choice for users of these platforms is also limited, with only Windows Phone licensed to other manufacturers and the rest available only on the vendor’s devices.

Chapter 1: Getting an Inside Look at Tizen

13

Of the open source alternatives, WebOS and Firefox OS are both platforms with potential, but they don’t have the same level of industry support as Tizen. Android is the best known open source platform, but the governance of the platform is arguably not as open, and its standards support isn’t as comprehensive as Tizen.

Getting Familiar with the Tizen Association The Tizen Association and the Tizen Project, under the Linux Foundation, are complementary to each other. The industry and market-facing aspects of Tizen are driven by the Tizen Association, while the engineering of the Tizen software platform takes place within the Tizen open source project hosted by the Linux Foundation. The Linux Foundation runs the Tizen Project, with a focus on platform development and delivery. You can find out more at www.tizenassociation.org. The board of directors decides the commercial direction of the Tizen Association. The board decides on the platform requirements, business strategy, application store requirements, and industry partnerships. It aims to evolve the ecosystem of the Tizen platform. Several technical steering groups (TSGs) govern the Tizen Project. Intel and Samsung, as the two primary platform contributors, chair the TSGs, and other interested parties can participate.

Getting Involved You can participate and contribute to the Tizen Project at different levels. As described on the Tizen website (www.tizen. org), you can be a platform contributor, an application developer, a user, or a Tizen product vendor. At the platform level, the membership for the TSG (for example, groups responsible for areas such as Release Engineering, Quality Assurance, and Program Management) is invitation

14

Part I: Introducing Tizen only and will mainly be open to the Tizen vendors. However, the Community Office, Localization, and some Middleware groups will be open to participation on a merit basis.

Submitting patches If you think you can improve the existing code of the Tizen platform, you can submit your changes to the Gerrit system for code review. The maintainer, release engineers, and the QA team will review your patches and decide whether they will be accepted based on the quality of your code. Once the changes are approved, you can submit them to the Gerrit system and Gerrit will merge the changes into the Tizen code base. You can find a guide to submitting changes at: https://source.tizen.org/documentation/ developer-guide/submitting-patches The Tizen wiki is available for collaborating on documentation related to the Tizen project: https://wiki.tizen.org/wiki/Main_Page If you have any information or tutorials you want to share with the community, you’re free to add them to the wiki. However, before contributing, you should check the User Guide and style guides.

Mailing list and IRC Several mailing lists and an IRC channel enable community members to share information and ask questions about the Tizen platform. Details of these mailing lists and how to join them are provided on the Tizen community website: www.tizen.org/community/mailing-lists The IRC channel is #tizen at: irc.freenode.net, and the channel’s logs are available to view: www.tizen.org/irclogs

Chapter 1: Getting an Inside Look at Tizen

15

Forums Another source of help and information are the forums available on the Tizen developer site: https://developer.tizen.org/forums The forums are available to any developer with an account to ask questions, contribute to discussions, and share information.

Bug tracker Tizen uses JIRA to track bugs and gather requests for new features: https://bugs.tizen.org/jira Anyone with a tizen.org account can add a new bug, comment on an existing bug, or even submit a patch to fix a bug.

16

Part I: Introducing Tizen

Chapter 2

Exploring the Tizen Architecture In This Chapter ▶ Looking at Tizen’s organisation ▶ Exploring the role of the web runtime ▶ Getting an inside look at the web APIs ▶ Listing the Tizen device APIs

T

izen isn’t just for smartphones and tablets; it’s designed to drive a wide range of device categories from smart TVs to netbooks and beyond. For example, the IVI project is setting standards to allow Tizen to be used as part of in-vehicle infotainment systems in cars, planes, and buses. In the future, you may find Tizen on Blu-ray players and digital TVs or powering a new generation of netbooks. Because Tizen is open source and standards based, developers in the open source community can find uses for Tizen in devices far beyond what’s available today. Maybe you’ll find Tizen in your fridge or alarm clock or in a home automation system. The possibilities are endless. It’s the incarnation of Tizen defined for smartphones and tablets that we concentrate on in this book. Web developers don’t have to know the inner workings of Tizen in order to create apps, but the more you know about the platform, the more informed your development choices can be.

18

Part I: Introducing Tizen

Introducing Web Apps The term web app is actually quite broad. Our definition is apps based on web technologies that can access system resources and that you can install on a device – although they don’t have to be. Is a website a web app? Yes, it is. Websites are built with standard web technologies and can use W3C APIs to access some device features. They don’t have to be installed because everything happens in the browser. Tizen web apps are created using a combination of W3C/ HTML5 specifications, supplementary web specifications, and Tizen web app device APIs. The important thing to know for this section is that Tizen web apps are just like traditional apps: ✓ They can access system resources. ✓ They can launch other apps. ✓ They provide services. ✓ They generally behave like traditional native apps do.

Going native The 2.1 release of the Tizen SDK includes a set of C++ APIs which you can use to create native apps. Depending on your requirements, you can choose whether to create a web app or take the native approach. Developing a native app is a good choice if your app is performance intensive or you need access to

device functionality not supported by the web APIs. However, web apps are more portable, support all the HTML5 standards and still have most of the features of native apps. This book concentrates on web apps, but you can find full details of the C++ APIs, as well as examples and tutorials, in the SDK help.

Chapter 2: Exploring the Tizen Architecture

19

The web runtime Each web app runs in its own process. In the task manager of a Tizen device, you can see a Tizen web app just like a native app. You can utilise process scheduling and management, and platform security features also apply. The web runtime provides a framework for installable web applications. The role of the web runtime is to install and launch apps and provide integration with the native platform, exposing Tizen APIs so that web apps can access device features. The web application can be integrated with the task manager and package manager, and it can also receive some of the system events, such as out of memory, screen orientation, and system locale change. The web runtime is also responsible for access control checking. Whenever a web app calls a JavaScript API, the web runtime checks that the app is allowed to access that particular feature, returning an error if access is denied. This process provides a high level of runtime security. Figure 2-1 shows the components of the web runtime. As you can see from Figure 2-1, the web application talks to the web runtime, which then communicates with the layer below to access the features of the device. The web runtime consists of an installer, runtime core, plugin core, and security components. The following sections look at these areas in more detail.

Figure 2-1: The Tizen web runtime.

20

Part I: Introducing Tizen

Installer When an application is installed, the Tizen package manager is called to install the web application. The package manager invokes the web runtime’s app installer program, which checks that the app is properly signed and then starts the installation. Once installed, the app is registered with the web runtime database using the information supplied in the app’s configuration file, including the app ID, name of the app, and icon. The app’s icon then appears in the menu screen. When the user uninstalls an app, the app is unregistered from the web runtime database, and all app resources are removed from the client.

Runtime core The runtime core is responsible for managing the lifecycle of an application, including startup, suspend and resume, and terminate. When an app launches, the Tizen launchpad executes the web app process. This creates a new process for the web app and initialises some of the callbacks that will be invoked for certain system events. When an app is initially launched, the runtime will retrieve the web app’s start file, usually called index.html, initialise the web view and load this .html file. If the app provides a service – for example, getting an image from a web service – then this feature will be registered as a service, using the Image MIME type. When another app requests the image service, the app will receive the request and handle it. The Tizen web runtime rendering engine is based on WebKit2. This is the same WebKit used in the Tizen browser. As a result, web apps can take advantage of the same HTML5 APIs and the same 2D and 3D optimisations and CSS3 optimisations that the built-in browser uses.

Chapter 2: Exploring the Tizen Architecture

21

Plugin core The plugin core is what enables the web app to talk to the device/platform via JavaScript APIs. It communicates with the JSCore module in the platform layer (refer to Figure 2-1) and implements on-demand loading of plugins at runtime. The advantage of on-demand loading of plugins is that the web app starts faster because plugins are loaded only when the JavaScript needs them.

Using Tizen Web APIs You create Tizen web apps using a combination of W3C/ HTML5 specifications, supplementary web specifications, and Tizen-specific device APIs. Tizen provides support for many HTML5 features, such as audio and video, offline web storage, web workers, and 3D transform and transition effects. You can use these standard technologies in a web application. Tizen also includes support for some APIs not specified in W3C but that are part of supplementary common web standards. Included in this list are typed arrays and the viewport metatag definition. Figure 2-2 shows the relationship between W3C APIs, supplementary APIs, and Tizen-specific device APIs. Of course, when you build web apps, you’re also likely to use various JavaScript utility libraries, such as jQuery and jQueryMobile. With so many libraries available for you to use, you don’t need to re-invent the wheel.

Checking the specs You can find the current status of Tizen’s support for particular W3C APIs in the online help in the Tizen W3C API Specifications section. HTML5 is a moving target, and Tizen’s API support is evolving. By the time you read this book, the HTML5 support will be even better.

In fact, because Tizen provides such good HTML5 support, you can create many web apps without using any Tizen-specific APIs at all. You can still access some device features, such as geolocation, and some sensor features all from within a portable completely standard web app.

22

Part I: Introducing Tizen

Figure 2-2: The APIs available to a Tizen web application.

Exploring the Tizen Device APIs So why does Tizen need its own JavaScript device APIs? Well, it turns out that while the W3C specifications do provide a lot of features, some gaps exist. Tizen device APIs were created to fill these gaps. For example, you can find Tizen APIs for manipulating contacts and calendars in Chapters 12 and 13. These Tizen APIs are all contained within the Tizen namespace. You also discover how to give your apps a consistent look and feel in Chapter 7, which introduces the Tizen Web UI Framework. The idea behind these APIs isn’t to compete with the W3C APIs. In fact, Samsung and Intel participate on various standards committees that define W3C APIs. The aim is that the Tizen device APIs will one day be absorbed into W3C so that they’ll become standards. Tizen is still an evolving platform and Tizen device APIs are designed to supplement, not replace, the functionality of the W3C APIs. However, the device features provided by the W3C APIs are also becoming more comprehensive. You might find

Chapter 2: Exploring the Tizen Architecture

23

that new W3C standards are introduced that provide the same functionality as some of the Tizen device APIs discussed in this book. In this case, you should update your application to use these APIs and help to make your apps more portable and future proof. You can find a complete specification of the device APIs in the SDK help, but the following sections provide a quick overview and point you to the more detailed information and code samples in later chapters. The SDK also includes code samples covering most of the device APIs; see Chapter 3 for more information on using the samples included with the SDK.

Tizen The Tizen JavaScript object is used to access device APIs such as Contact, Calendar and NFC. For example, to access the default address book, you use the following code: var addressBook = tizen.contact. getDefaultAddressBook(); The contact object is a property of the tizen object and contains a ContactManager object, which provides access to the Contacts API, including the getDefaultAddressBook() function. The same pattern is used with the other device APIs. Throughout this book and in the Tizen SDK, the web Interface Definition Language (IDL) is used to describe APIs in a language independent way. This allows the APIs to be described using terms familiar to those of you with a background in strongly typed object oriented languages, such as C++, even though the APIs are accessed through JavaScript. Apart from being the base object used to access the other device APIs, the tizen object also provides access to a set of generic functions, including error handling and filters. Chapter 9 demonstrates how to use filters.

24

Part I: Introducing Tizen

Alarm The Alarm API allows you to set an alarm to run an application at a specified time and launch it if it’s not already running.

Application The Application API allows you to retrieve a list of running applications and launch other apps by using an application control. So, you might launch the camera app to take a picture or record video or use the media player to play music files. You can also provide services to other apps. Chapter 9 covers launching an application using an application control.

Bookmark The Bookmark API provides access to the device’s bookmarks. You can use it to retrieve bookmarks, as well as add and remove both bookmarks and bookmark folders.

Bluetooth The Bluetooth API provides access to the Bluetooth protocol, which can be used for transmitting files over short distances between devices.

Calendar The Calendar API allows you to manage events and tasks so that it can handle your schedule or to-do list. Chapter 13 explains the Calendar API in detail.

CallHistory The CallHistory API provides access to the call history functionality, such as finding and removing call history entries.

Chapter 2: Exploring the Tizen Architecture

25

Contacts You use the Contacts API to manage contacts and handle multiple address books. Chapter 12 explains the Contacts API in detail.

Content The Content API lets you search for content on the device, either stored locally or on a memory card. Chapter 9 shows you how to use these features.

DataControl The DataControl API, introduced in Tizen 2.1, is used to access data exported by other applications, for example native applications. You can use the functionality provided by the DataControl API to operate on both SQL and key-value databases.

DataSynchronization The DataSynchronization API, supported from Tizen 2.1, allows you to synchronize device data with a server using the OMA Data Synchronization 1.2 protocol.

Download The Download API, introduced in Tizen 2.0, is used to download files from the Internet and monitor the download status.

Filesystem The Filesystem API provides access to the device’s file system. The SDK includes more information, including tutorials.

26

Part I: Introducing Tizen

MessagePort The MessagePort API allows you to exchange data with another web application, or with a native application. Data is sent using the RemoteMessagePort, and data is received from the LocalMessagePort.

Messaging The Messaging service allows you to send SMS, MMS, and Email messages and search messages on the device. Chapter 11 explains this API in more detail and provides source code for searching SMS messages on your device.

NetworkBearerSelection The NetworkBearerSelection API, new to Tizen 2.1, allows you to specify a particular network connection to be used from your web applications to connect a given domain or host.

NFC Near Field Communication (NFC) is used for short range wireless communication. NFC enabled devices can be used for mobile payments and in a range of other applications. We explain Near Field Communication (NFC) in detail in Chapter 10. You discover the different applications of NFC technology and how to use NFC in your Tizen web apps.

Notification The Notification API, introduced in Tizen 2.0, provides a way of alerting the user to events happening in your app. You can find details of how to create and manage notifications in the SDK help.

Chapter 2: Exploring the Tizen Architecture

27

Package The Package API, new to Tizen 2.1, allows you to install and uninstall packages, retrieve information about the packages installed on the device, and monitor any changes to installed packages.

Power Another new API introduced in Tizen 2.0, this provides access to a device’s power state and allows you to control display dimming and brightness, for example. More information, including a tutorial are included in the SDK.

Push The Push API, new in Tizen 2.1, allows web applications to receive push notifications from the push server.

SecureElement The SecureElement API, introduced in Tizen 2.1, provides access to secured elements on the device, such as a UICC/SIM, embedded security element or secure SD card.

SystemInfo Provides access to device specific information, such as local storage, battery levels, cellular network, and so on. More information and a tutorial are included in the SDK.

SystemSetting The SystemSetting API, introduced in Tizen 2.0, lets you get and set various device properties. At the time of writing you can get and set the following device properties: the device and lock screen wallpaper, the ringtone for incoming calls and the email message notification sound.

28

Part I: Introducing Tizen

Time Provides date and time functions, including working with the current date and time and locale specific date and time handling. Chapter 13 uses the Time APIs to set the date and time of calendar tasks.

Part II

Getting Practical

I

In this part . . .

n this part we start to get practical. You download and install the Tizen SDK, start to find your way round the tools, and build your first Tizen app. In Chapter 3 you learn enough to get up and running, while Chapter 4 takes you through each component of a Tizen app in detail. You’ll explore some of the sample apps and discover how there’s a world of third-party JavaScript libraries ready for you to use in your apps. Chapter 5 tidies up the messy business of testing and debugging. You might have an existing web app that you want to port to Tizen, in which case you will find some useful tips in Chapter 6. We also explain how you can design your Tizen web app to make it more portable.

Chapter 3

Getting Started In This Chapter ▶ Installing the Tizen SDK ▶ Building your first web app ▶ Getting Help

G

etting to grips with a new platform can feel like travelling to a country for the first time. You may be the kind of traveller who likes to turn up at the airport hours in advance, with a well-planned itinerary, phrase book, and a list of the local hotspots. Or, like some authors we could mention, you may prefer to run to catch your flight, carrying only a pair of sunglasses and a smile. Both travellers will get to their destination, both will probably have a good time, but for all their spontaneity, the less prepared traveller may be left with a nagging feeling that he may have missed out on something. In this chapter, you find everything you need to build your first Tizen app. If you’re feeling adventurous or just can’t wait to get coding, this chapter will be all you need to get started. But if you’re new to web development or the Eclipse IDE or you just want to make sure that you get the most out of the development environment before diving in head first, then think of this chapter as the first part of a trilogy. Chapter 4 looks at each component of a Tizen app in detail, while Chapter 5 uncovers the secrets of testing and debugging. Tizen development may not be everyone’s idea of an adventure, but you’ll be well prepared for the trip.

32

Part II: Getting Practical

Getting perspective A perspective describes the layout of views to help you achieve a particular task. In the case of the default Tizen Web Perspective, that task is web development, so you’ll see views including the Connection Explorer, and HTML Web Page Editor. Chapter 5 introduces the Connection Explorer, while the HTML Web Page

Editor is covered in its own section later in this chapter. You can also open up other useful views not shown in the current perspective by choosing Window➪ Show View. There’s much more detail about perspectives, views, and the workbench in the Tizen SDK help.

Installing the IDE The Tizen SDK provides a set of tools for developing Tizen web applications. The IDE is based on Eclipse, which will be familiar to you if you’ve done any Symbian, Android, or bada development. The SDK also includes a tool chain to build apps for your chosen hardware platform and lots of sample code, tutorials, and documentation to help you get started. This chapter refers to the 2.1 Magnolia version of the Tizen SDK. To begin your journey into Tizen development, you first need to download the SDK from the Tizen website at https:// developer.tizen.org/downloads/sdk. The currently supported platforms are: ✓ Ubuntu (11.10/12.04) 32-bit & 64-bit ✓ Windows XP 32-bit ✓ Windows 7 32-bit & 64-bit ✓ Mac OS X (Intel) 64-bit You can download two files for Windows, Ubuntu or Mac OS X: the installation manager and the SDK Image. The installation manager is responsible for installing the SDK, and you can use it in one of two ways. You can download the SDK from the server during the installation process, or you can download

Chapter 3: Getting Started

33

a separate SDK image file and choose to install the SDK from this package. This latter approach allows you to complete the SDK installation when you’re not connected to the Internet. After you install the SDK, the first time you launch the IDE you’re asked to select a workspace. On the Welcome screen that appears, choose the Workbench option. The Tizen Web Perspective appears, as shown in Figure 3-1.

Figure 3-1: The Tizen Web Perspective

Now you’re ready to start developing apps. If you install the SDK on Mac OS X 10.7.5 or later and an error dialog appears when you launch the Install Manager, then you may need to change your security settings temporarily to prevent the OS X Gatekeeper feature from blocking the installation. Choose Apple Menu➪System Preferences, open the Security preference pane and click on the General tab. Under the heading ‘Allow applications downloaded from’, choose the ‘Anywhere’ radio button. You should now be able to launch the Install Manager.

34

Part II: Getting Practical Once you’ve finished installing the Tizen SDK, restore your settings to the previous state.

Creating Your First Tizen Web App The easiest way to create a new Tizen project is by using the New Project wizard. The wizard allows you to create your application using some predefined templates or create a project from one of the built-in sample apps. You can also use user-defined templates, which we explain in more detail in the ‘User-defined templates’ section.





It’s well worth taking a look at all the templates and sample code provided in the IDE, to give you a head start creating your app. To launch the New Project wizard and choose a template, follow these steps: 1. In the IDE, choose File➪New➪Tizen Web Project.

The New Project wizard appears. You see a selection of templates and sample applications to choose from (see Figure 3-2).

2. Choose the template or sample you want to use.

Tizen offers several predefined template types:

• Basic: A blank application template.



• Tizen WebUI Framework: A set of templates with all the necessary files for creating a web application using the Tizen web UI framework.



• jQuery Mobile: A set of templates containing all the files to create a web application using the jQuery Mobile framework.



• Tizen Web UI Builder: A set of templates containing all the files to create a web application using the Tizen Builder.



3. Name your project.



4. Click Finish.

Chapter 3: Getting Started

35

Figure 3-2: The New Project Wizard.

These templates include the basic structure for an application and all the relevant JavaScript libraries required for the selected UI framework. All you need to do is add your application specific code.

Using a sample app If you want to create a slightly more complicated application, you can use one of the sample applications provided in the SDK as a starting point. Walking through the sample code is also a great way to become familiar with particular features. The New Project wizard provides many sample applications to demonstrate the use of Web technologies and the Tizen APIs. The Tizen developer website also provides other samples that you can use to start developing an application. (See the ‘Importing an existing project’ section, later in this chapter, for more details on how you can use these samples.)

Using your own template If you have an existing template from another web-based platform or you’re developing several applications based on

36

Part II: Getting Practical a common structure, you may want to define your own template. The New Project wizard provides an option for creating an application based on your own user-defined templates. Before you can use this option, you need to create your own application project template. You can create a user template based on any project, using the Export wizard. To use the Export wizard, follow these steps:



1. Right-click the project in the Project Explorer view and choose Export.

The Export dialog box appears.

2. From the Select an Export Destination list, doubleclick the Tizen folder icon and then select the Tizen User Template, as shown in Figure 3-3.

Figure 3-3: The Tizen user template.



3. Click Next.

The User Template Export wizard appears.

4. Enter the name and export location.

Chapter 3: Getting Started

37



5. Select the Import a Template check box so that your template will appear in the New Project wizard.



6. Click Next.

The icon selection screen of the User Template Export wizard appears.

7. Add any icons that you want to be shown in the new wizard.



8. Click Next.

The images and descriptions screen appears.

9. Add any images or descriptions that you want displayed in the new wizard.



10. Click Finish to complete the export of your user template.

Importing an existing project Using the New Project wizard isn’t the only way to create an application; you can also import existing applications into the IDE.

Tizen web application To import an existing Tizen web app, follow these steps:

1. Choose File➪Import.

The Import dialog box, shown in Figure 3-4, appears.

2. From the Select an Import Source list, double-click Tizen and then select Web Projects and Widget file.



3. Click Next.

The Import Widget screen appears.

4. Enter the root directory or click the Browse button to select the projects you want to copy into the workspace.



5. Click Finish. The project is imported into the workspace.

38

Part II: Getting Practical

Figure 3-4: The Import dialog box of the New Project Wizard.

Other web applications If you have a web application developed for the desktop or another mobile platform, you can import it into the IDE by following these steps:

1. Choose File➪New➪Project.



2. In the wizard’s drop-down list, double-click the General folder and then click Project (see Figure 3-5).



3. Click Next.



4. Uncheck the use default location check box and enter the name and location of your project.



5. Click Finish. Your project is now created and loaded into the workspace. After you create the project, you need to edit two files: .project and config.xml. You can find full instructions on how to edit these files on the Tizen developer website: https://developer.tizen.org/downloads/sampleweb-applications/load-web-app-tizen-sdk

Chapter 3: Getting Started

39

Figure 3-5: Import other web apps.

Writing the Code The SDK provides many useful tools to help you write and edit your app’s code. These tools are designed to help you throughout your development process, helping you preview your HTML code as you create it, crafting the look of your pages with CSS Preview, and making the JavaScript coding process easier and more efficient.

HTML Web Page Editor The IDE provides a WYSIWYG editor for editing HTML files. The Web Page Editor allows you to view both the source code and preview the HTML as you’re developing your application (see Figure 3-6). The IDE offers several options, shown in Table 3-1, for viewing your HTML content.

40

Part II: Getting Practical

Table 3-1 HTML View Modes

Web Page Editor View Modes Description Show Design Page & Source Page as Vertical panes Show Design Page & Source Page as Horizontal panes Show Design Page only Show Source Page only

You could choose to handcraft your HTML, but you can also use the palette feature provided in the IDE. HTML4 and HTML5 palettes are provided for you in all views except the Source Page Only mode. To use an object from the palette, just select a component and drag it to the required location on either the Design or Source page.

Figure 3-6: The Web Page Editor.

Chapter 3: Getting Started

41

HTML Preview You can instantly preview a HTML file using the HTML Preview tool (see Figure 3-7). Google Chrome is used to display the Preview, so the appearance will be more accurate than the preview in the Web Page Editor, which uses your system’s default browser.

Figure 3-7: The HTML Preview.

To view your HTML file in the HTML Preview tool, select the Preview button from the IDE’s toolbar.

CSS Preview You can instantly preview the look and feel of any CSS file using the CSS Preview tool, shown in Figure 3-8. Google Chrome is used to display the content in the Preview, and any changes you make will be reflected immediately. To view your CSS file in the CSS Preview tool, select the Preview button from the IDE’s toolbar.

42

Part II: Getting Practical

Figure 3-8: The CSS Preview.

Minifying CSS and JavaScript The IDE provides tools to minify your CSS and JavaScript files if you need to reduce the size of your code.

CSS The CSS tool removes comments, white space, extra semicolons, empty declarations, zero values, and so on from your CSS code. To minify your CSS file, right-click the file in the Project Explorer, and the options in Figure 3-9 appear at the bottom of the list. Choose the Minify CSS option, and the file is minified with a new version of the file (.min.css) created.

Figure 3-9: Minify CSS.

Chapter 3: Getting Started

43

JavaScript The JavaScript tool removes comments and extra white space, replaces identifiers, and performs micro-optimisations in your JavaScript code. To minify your JavaScript file, right-click the file in the Project Explorer, and the options in Figure 3-10 appear at the bottom of the list. Choose the Minify JS option, and the file is minified with a new version of the file (.min.js) created.

Figure 3-10: Minify JavaScript.

Building Your Project A Tizen application is packaged in a .wgt file that can be downloaded and installed on a device or Emulator. You can find out more information about an application package and its content in Chapter 4. When you’re developing your application, if the Build Automatically option is enabled, then the application package will be rebuilt every time you save any changes. Any errors or warnings found in your JavaScript code will be shown in the Problems View at the bottom of the IDE.

Running Your Project You can test whether your application works by running it in the Simulator or Emulator environment or on a Tizen device. For more information about how to test your project, see Chapter 5. If you want to, you can select one of the sample applications introduced in the ‘Using a sample app’ section, earlier in this chapter, and try building and running the app for yourself.

44

Part II: Getting Practical

Help Is on the Way The Tizen SDK provides a comprehensive set of Help documentation, tutorials, and sample code to help you get started. You can find lots of other resources, too, including the developer site, wiki, forums, mailing lists, and a bug tracker. Blogs and forums created by community members are also just a quick Internet search away, and these resources will only increase as the community grows. You can access Help documentation and get information about any APIs by hovering over the function names. The IDE also provides an Auto completion feature to avoid making any typing errors when using the Tizen APIs.

Help documentation You can find the most up-to-date information about Tizen in the SDK Help documentation. You can open the Help from within the IDE, by choosing Help➪Help Contents. You can also access Help on the Tizen website: https://developer.tizen.org/documentation Here are some of the most useful Help sections to consult to find out more about the platform and creating apps: ✓ Getting Started with Tizen/Overview/Architecture describes the platform architecture and introduces the components that make the platform. ✓ Getting Started with Tizen/Development Environment/ Tizen SDK describes the tools available in the SDK and tips on how to use them. ✓ Tizen Web App Programming/API References/Device API Reference provides detailed information about the Tizen device APIs and how to use them within your web application. This specification uses Interface Definition Language (IDL), which is used to describe APIs in a language independent way.

Chapter 3: Getting Started

45

✓ Tizen Web App Programming/Programming Guide includes the Device Guides, which explain the functionality of each device API and provides code examples for the main features. ✓ Tizen Web App Programming/Tutorials includes tutorials that take you step by step through some more detailed examples for the main APIs. ✓ Tizen Web App Programming/API References/UI Framework Reference is a guide to all the Tizen Web UI Framework widgets and offers examples of how to use them in your web application.

Sample applications In addition to the tutorials and the sample applications provided in the SDK, several sample web applications are available for download from the Tizen developer site: https://developer.tizen.org/downloads/sampleweb-applications These applications use a variety of standard HTML5, JavaScript, and CSS3 techniques and can be run either on the desktop or a mobile device. Each application has a tutorial describing the main features of the application and how they were implemented. You can use the instructions described in the ‘Other web applications’ section, earlier in this chapter, to import these projects into the IDE. See Chapter 1 for more details about the Tizen wiki, mailing list, IRC channel, and forums.

46

Part II: Getting Practical

Chapter 4

Piecing Together the Application Jigsaw In This Chapter ▶ Introducing the application package ▶ Getting inside the configuration file ▶ Seeing how a Tizen app fits together

A

s a web developer, you can count on standards, such as the W3C APIs that form part of HTML5, but the apps that use these APIs aren’t so much developed from scratch as assembled from a jigsaw puzzle of pieces. You may have an app that uses W3C APIs, makes use of a library (such as jQuery), and even includes JavaScript, HTML, and CSS files generated by a tool like Dreamweaver. The possibilities are endless, but knowing how to piece all these parts together and add your own code to the mix can be a challenge. In this chapter, we examine the components of the application package, including the configuration file that contains the app settings. We show you how to put the pieces of the puzzle together to create a Tizen web app, from the simplest possible app to a more advanced app that makes use of the Tizen device APIs. Armed with this information, you’ll understand how a Tizen app is put together and have a solid foundation for creating your own apps. For full details about downloading, installing, and taking your first steps with the Tizen SDK, go to Chapter 3. Chapter 5 covers testing and debugging.

48

Part II: Getting Practical

Examining the Pieces The way you work through this chapter is up to you. You can use it as a reference that you dip in and out of as you write your app or follow along with the Tizen IDE in front of you. If you want to follow along, then why not build one of the sample apps as described in Chapter 3? This section isn’t based around one app, but if you have one of the Tizen samples loaded into the IDE, you’ll be able to find the main components as they’re explained.

The Application Package When you build a Tizen app for the Simulator, Emulator, or device, the app is packaged in the W3C standard widget format, a zip format compressed archive that has a file type of .wgt. This package contains all your JavaScript, HTML, and CSS files, together with the images, configuration file, and other resources that your app uses. To take a closer look at the package, double-click the .wgt file in the Project Explorer. The package contents are revealed and look something like the app package shown in Figure 4-1. You can find the specification of the W3C widget format at www.w3.org/TR/widgets.

Figure 4-1: Systeminfo example application – package content and structure.

Chapter 4: Piecing Together the Application Jigsaw



49

If you’ve minified any JavaScript or CSS files to reduce the size of your code, by default both the original and the minified version will be included in the package. You must remember to manually remove the original version either from the final package or from your project and update your project files to use the minified version of the file.

Localized content The example shown in Figure 4-1 is missing one key ingredient of a well-designed web app, and that’s localized content. One of the ways to ensure that your web app displays content appropriate to the current locale is to use folder-based localisation. With this approach, you create a folder for each locale for which you’re creating localized content. For example, for the French locale, put localized HTML files, images, and other resources into the /locales/fr folder at the root level of the application package. If the current locale is set to French, then the platform will first look inside this folder for French localized resources. Figure 4-2 shows the package for an app using folder-based localization.

Figure 4-2: Example application with localized content-package content and structure.

50

Part II: Getting Practical For each locale, you can localize as much application content as is appropriate. For example, in Figure 4-2, the Spanish (es) locale, unlike the French (fr) locale, only has localized content for the index.html file and will fall back to use the default version of the icon.png file. You can create all the necessary files and folders for localizing your app using the Tizen Localization wizard. To launch the wizard, right-click your project in the Project Explorer panel and choose the Localization➪Localization Wizard menu item. This wizard allows you to choose which files to localize, as well as the locales you want to support. You can find the folder naming standards as part of the widget specification at www.w3.org/TR/widgets.

The configuration file The configuration file is an XML file that contains information about the features of the application. The Tizen platform supports the configuration file as defined in the W3C widget specification and adds some Tizen-specific extensions. You can create or edit this XML file either by hand or by using the Configuration Editor provided in the IDE. You must include this configuration file in your application package.

Breaking down the config file Listing 4-1 shows an example of a config.xml file used for a simple Tizen web application:

Listing 4-1  Example config.xml file

Chapter 4: Piecing Together the Application Jigsaw

51

SysteminfoSample

The first line of the config.xml file is the declaration identifying the XML version and encoding used:

The next part of the config.xml file defines the widget element and its attributes:

The namespace declaration will be the same for all Tizen web apps. It just specifies that the app is a W3C format widget that uses the Tizen-specific extensions. The id attribute is mandatory and uniquely identifies your widget – in this case, the Systeminfo sample. If you have your own domain name, then use it in place of yourdomain in Listing 4-1. The id doesn’t have to be a valid URL and is just used for identification. You can also set other optional attributes, including version, height, width, viewmodes, and defaultlocale. The widget element can also contain a number of optional child elements, representing additional information about your application. We explain what these elements are used for in the next section.

52

Part II: Getting Practical SysteminfoSample

Finally, the Tizen application id, package and minimum API version attributes are defined. The Tizen application id and package attributes are Tizen specific extensions which are used to identify a Tizen application. The package attribute is mandatory, and is represented with a randomly generated 10-character alphanumeric value. The application id is also mandatory, and is represented by the package id and the application’s project name:

config.xml the easy way: the Configuration Editor Rather than creating the config.xml file by hand, the Tizen IDE makes things easier by including a Configuration Editor. This tool automatically adds all the mandatory elements and helps you generate a valid config.xml file. To open your config.xml file for editing in the Configuration Editor, right-click the file in the Project Explorer panel and choose Open With➪Widget Configuration Editor. Figure 4-3 shows the Configuration Editor open at the Overview window. (You may recognize some of the information in Figure 4-3 if you read the last section.) The Configuration Editor displays the contents of the config.xml file in nine separate tabs: Overview, Widget, Features, Privileges, Access, Localization, Preferences, Tizen, and Source. The following sections describe the content of each tab.

Overview In the Overview tab, you can enter general information about your application.

Chapter 4: Piecing Together the Application Jigsaw

53

Figure 4-3: The Configuration Editor.

The items shown in Table 4-1 are the attributes that you can set through the Overview tab in the Configuration Editor.

Table 4-1

Attributes in the Overview Tab

Type

Description

Identifier

IRI identifier for the widget

Version

The current version of the widget

Name

Full human-readable name for a widget (for example, for use in an application menu)

Content

Custom start file that the user agent is expected to use when it instantiates the widget

Icon

Custom icon for the widget

Widget In the Widget tab, you can enter specific information about your application. The items shown in Table 4-2 and Table 4-3 are the attributes that you can set through the Widget tab in the Configuration Editor.

54

Part II: Getting Practical

Table 4-2

Specific Information in the Widget Tab

Type

Description

Author

People or an organization associated with the creation of the widget

E-mail

Email address associated with the author Web

Web Site

IRI associated with the widget – for example, your website, Facebook id, and so on

License

Software license, including copyright and redistribution terms

License URL

Valid IRI or a valid path that points to the detailed license information

Description

Human-readable description of the widget

Table 4-3 Attribute Information in the Widget Tab Type

Description

Width

Preferred viewport width of the instantiated custom start file

Height

Preferred viewport height of the instantiatedcustom start file

View Modes

Author’s preferred view mode (full screen, and maximized)

Features In the Features tab, you can declare all the mandatory hardware and software components that are required by your application. This information will be used by the Tizen application store to filter applications, ensuring that only those applications which are compatible with a user’s device are shown. To add a feature to your application’s config.xml file, select the Features tab and click the Add button. A new row is added to the Features table, and you can add the feature string.

Chapter 4: Piecing Together the Application Jigsaw

55

Privileges A privilege is a URI-identifiable runtime component – for example, an API such as http://tizen.org/privilege/ systeminfo. In order to access an API at runtime, your application must register it in the config.xml file. To add a new privilege to your application’s config.xml file, select the Privileges tab and click the Add button, as shown in Figure 4-4. If you select the Internal radio button, you’ll be able to select from a list of Tizen’s built-in privileges. Optionally, using the other radio buttons and text boxes, you can enter a URL or the name of a file that contains a privilege definition.

Figure 4-4: Add a new privilege.

After you select the new privileges, click the Finish button. After you finish making changes to the configuration file, choose File➪Save or close the config.xml window and click Yes when you’re prompted to save your changes.

Access The Tizen platform supports WARP, the W3C Access Request Policy. So by default, applications are restricted from accessing network resources. If your application needs to access any network resources, you must add them in the config.xml file.

56

Part II: Getting Practical To allow access to a network URL, select the Access tab and click the Add button. Enter the network URL and select whether the application should be able to access the URL’s subdomains. In the ‘Example 1: A 5-Minute Application’ section, later in this chapter, we show you how to create a simple app that displays content from the Food Network’s website, as shown in Figure 4-7. We’ll leave it to you to decide if we’re partial to cakes. You’ll notice that http://m.foodnetwork.com was added to the access origin section of the config.xml file. The app needs to access this external resource in order to retrieve the data to display.

Localization The Tizen platform supports localization of selected elements in the config.xml file, including the application name and description. Any elements that you can localize will be displayed in the Localization tab. To localize a config.xml element:

1. Right-click the element and choose Select Languages.

The Select the Locales dialog box, shown in Figure 4-5, appears.

Figure 4-5: Locales. Add any new locales you want to support.

Chapter 4: Piecing Together the Application Jigsaw

57



2. To do so, choose the required locales from the Available locales list and click the Add button to add them to the Selected locales list.



3. Click OK to return to the Localization window, shown in Figure 4-6.

Figure 4-6: Localizing the application name.

Elements that can be localized appear with a triangle icon on the left side.

4. To add the required localized strings for each language, start by clicking the triangle icon to reveal a list of the locales selected in Step 2.

Figure 4-6 shows the application name expanded to show the Italian and Korean locales. In this example, you can provide a localized version of the application name for these locales by entering text in the box labeled Selected Element:Name.

5. Choose a locale from the list and type the localized text in the Selected Element box at the bottom of the window.



6. Repeat Step 5 for all the elements and locales for which you want to provide localized content.



7. Choose Save or close the config.xml window when you’re done.

Preferences A preference is a persistently stored name-value pair that is associated with the application. You usually use a preference

58

Part II: Getting Practical to store application settings, such as whether a calendar app was last opened in month or day view, for example. To add a preference name-value pair to your application’s config.xml file, select the Preferences tab and click the Add button. A new row is added to the Preferences table, and you can add the name, value, and whether the preference is read-only.

Tizen In the Tizen tab, you can enter any Tizen-specific information about your application. This information includes the application’s id, the minimum version of the APIs that the application supports, the location of the start file if hosted on an external server, settings such as screen orientation, support for context menus, background support, encryption and installation location, and any app control information. Table 4-4 shows the attributes that you can set in the Tizen tab if your application provides an application control for other applications to use.

Table 4-4

Tizen Information

Type

Description

src

Page that provides the functionality described by operation, scheme, and mime

operation

Action to be performed by the application

scheme

URI scheme to describe what type of URI can be handled

mime

mime type that can be handled

Source The Source tab shows the XML content of the config.xml file. You can use this tab to view the values you’ve set up using the other configuration tabs. You can also manually edit the file.



The config.xml file must conform to the XML formatting rules and the W3C specification requirements, so be careful when manually editing this file.

Chapter 4: Piecing Together the Application Jigsaw

59

Start file The start file is the file that is loaded by the web runtime on application startup. The New Project wizard provided in the IDE creates a default application start-up file for you called index.html. Your start file doesn’t have to be named index.html. You can give it any name you like, but you must define the name of the start file in the content element’s src attribute in the config.xml file. For example:

The start file is where you create your web application’s visual content, structure, and controls. You can edit this file using the HTML Web Page Editor tools provided in the IDE, as described in Chapter 3.

JavaScript If your application requires any interactive elements, you can program them using JavaScript code. You can include this code directly in your index.html file within a element, or you can load it from an external JavaScript file. The New Project wizard provided in the IDE creates a default external script file called main.js for you to add to your JavaScript code. In order to load your external JavaScript code, you must include your script in the header section of the index.html file using the following code:

If you’re using multiple JavaScript files, don’t forget to load them all in the header section of the index.html file. If you’ve minified your JavaScript files, don’t forget to include this version in the index.html file instead of the original – for example:

60

Part II: Getting Practical

Style sheet Generally, your index.html file should contain only the basic content and structure of your application, with any style and presentation information contained within style sheets. The New Project wizard provided in the IDE creates a default style sheet called style.css, which you can use to apply styles and presentation information to the elements used in your application. To load a style sheet, include the following link in the header section of the index.html file:

You can preview the look and feel of any style elements using the CSS Preview tool, as described in Chapter 3.



If you’ve minified your CSS files, don’t forget to load this version in the index.html file instead of the original – for example:

Application icon The icon.png file is the application’s default icon file and should contain a logo or some other graphical representation of the application. The use of this icon file depends on the Tizen device you’re developing for, but it generally appears in the application menu screen.

Author signature An author can digitally sign any application to ensure its integrity. This signature file, which cryptographically covers all nonsignature files within the application package, is the author signature.

Chapter 4: Piecing Together the Application Jigsaw

61

This file isn’t mandatory in the package, but if the application is signed by the author, only one author-signature.xml file can exist. Check out the SDK Help for more details about creating an author signature.

Distributor signature A distributor can also sign an application to ensure its integrity. This signature file, which cryptographically covers all nonsignature files and the author signature, if it exists, is the distributor signature. This file isn’t mandatory in the package. The package can contain more than one distributor signature, so the naming convention is signature1.xml, signature2.xml, and so on. Check out the SDK Help for more details about creating a distributor signature.

You can find additional information about author and distributor signatures in the XML Digital Signatures for Widgets specification at www.w3.org/TR/widgets-digsig.

Third-party source code or libraries Sometimes you may want or need to use external libraries to implement UI controls or functionality that isn’t a standard part of the Tizen platform. Using third-party libraries is a really simple way to reuse existing technology and implement advanced features in your application. After you add the libraries to the project and load them in the start file, you can use them in your application code.



Before making use of any third-party source code or libraries in your application, please ensure that you check the license thoroughly and comply with the terms and conditions of use.

62

Part II: Getting Practical

Adding source code or libraries to a project You can add source code or libraries to your application project in several ways: You can add a new file by right-clicking your project in the Project Explorer panel and choosing New from the menu. You can then choose to add a new folder or source file (html, css, and so on) to the project. You can add existing files to your project by right-clicking the required project folder in the Project Explorer panel and choosing Import➪General➪File System. Then choose the files you want to import. Alternatively, you can add files by dragging and dropping them into the project via the Project Explorer panel.

Adding source code or libraries in index.html In order to use any external source code or libraries in an application, you need to load them in the application’s start file, index.html. In this example, all the external source code and libraries shown in Listing 4-2 are loaded in the head section of the index.html document.

Listing 4-2  Loading External Source in index.html

Chapter 4: Piecing Together the Application Jigsaw

63



Make sure that you load your JavaScript files in the order dictated by any dependencies. For example, in this code, the main.js file is loaded last because it’s dependent on features provided in the wijmo libraries.

Putting the Pieces Together In the previous section, we identify the role of each piece of the Tizen application jigsaw. In this section, we explain how you can slot together this mix of your own JavaScript code, third-party JavaScript libraries, and services provided by websites and even other applications to create your own Tizen web app. We introduce two sample apps to demonstrate what you can do with Tizen. The first is one of the simplest possible web apps, while the other is a more complex example. These examples should give you a good idea of how different types of Tizen applications are put together so that you’re ready to create your own.

Example 1: A 5-minute application A simple Tizen web application is a package that contains only a start file and a configuration file. In this example, we show you how to quickly create a simple web application to run on your mobile device.



The most simple web application you can create is a hostedweb application. Basically, it’s an application that launches a mobile web-page into your web-runtime.

64

Part II: Getting Practical

Creating the application project Create an application using the Basic Template as described in Chapter 3. Because this template contains more parts than you actually need, you can delete the css, js, and images folders in the project from the Project Explorer panel.

Editing the icon file You should create an icon file with an image or logo representing your application so that it can be displayed in the menu. The size and format of this icon depends on the platform you’re developing for. Replace the default icon.png file in your project with the new icon.

Editing the configuration document Open the Configuration Editor and modify the default config.xml file. Add the application identifier, name, version, and any other information you want to include. On the Access tab, add any relevant network resource URLs for ensuring that your application has access to the website. When complete, your config.xml should look similar to the one shown in Listing 4-3.

Listing 4-3  config.xml My-App Hosted web application example

Chapter 4: Piecing Together the Application Jigsaw

65



When you save your changes, the IDE will verify that the config.xml file is valid. If any errors occur, the IDE displays a warning dialog box.

Editing the start file Open the index.html and replace the content with the code shown in Listing 4-4, substituting the URL for your required website in the script to set the window.location.

Listing 4-4  index.html window.location=”http://m.foodnetwork.com”;

Running the application After you make these changes, you can build the application and run it on your device, the Emulator (see Figure 4-7), or the Simulator. For instructions on running the application, see Chapter 5. If you haven’t set the network URL(s) correctly in the config.xml file, the application won’t be able to display the web page, and the system will launch the device’s browser and display it there instead.

66

Part II: Getting Practical

Figure 4-7: Simple app running in the Emulator.

Example 2: Something a bit more complicated In this example, we introduce the use of JavaScript, CSS, and Tizen APIs in a web application. Rather than showing you a step-by-step guide to creating this more complicated app, we look at the default Systeminfo sample application provided in the SDK. First, you need to build and run the Systeminfo app from the Tizen SDK. You can find detailed instructions in the Chapter 3.

Chapter 4: Piecing Together the Application Jigsaw

67

If you already know your way around, just choose File➪New➪ Tizen Web Project from the menu. Then choose Systeminfo from the list of samples and build and run the app in the Simulator or Emulator. The opening screen is shown in Figure 4-8. This sample application uses the Tizen Web UI Framework and demonstrates how to use the System Info Tizen APIs. It’s a good starting point to understand how to include JavaScript and CSS functionality in a web application and also to see how to use the Tizen APIs.

Figure 4-8: Systeminfo sample application.

68

Part II: Getting Practical

Using the Tizen APIs Because this application is using Tizen APIs to get information from the device, the following privileges are registered in the config.xml file:

When these features are registered, the application can immediately access the functionality provided by the Application and Systeminfo objects. So for example, to retrieve the current battery level on the device, the following code is used: tizen.systeminfo.getPropertyValue(“BATTERY”, onBatterySucess, onError);

The getPropertyValue() method is an asynchronous method, which returns immediately. The platform attempts to retrieve the battery level and either returns the value in the onBatterySuccess() callback function, or an error is returned in the onError() callback function. Many of the device APIs provided in the Tizen platform use this common technique.

Looking at index.html At the beginning of the index.html file is the head section of the document. This section contains elements for defining the character set and an application description. This section is also where any JavaScript files and style sheets are loaded. In this index.html, we load a single style sheet and JavaScript files for jQuery, the Web UI Framework, and our app: Systeminfo

Chapter 4: Piecing Together the Application Jigsaw

69



This index.html file is a little more complicated than the one in Example 1 because it also contains some elements in the document body. The application contains two pages: one for the list of System Info items and the other for displaying the data. The first page, with the id main, contains text in the header area, a list element in the content area, and control bar element in the footer area: System Information Storage Battery CPU Display Device orientation

The second page, with the id info, contains text in the header area and a list element in the content area:

70

Part II: Getting Practical

Figuring out what is in main.js JavaScript code is event driven, triggered by a user action or an external event, so JavaScript files mainly contain a collection of related functions. Any variables that are defined in a JavaScript file will get initialised when the JavaScript file is loaded from the index.html file. If your application needs to perform any initialisation actions on startup, you can do this when the page is loaded. Because this example uses the Tizen Web UI Framework, which is based on jQueryMobile, initialisation occurs when the pageinit event is fired. So, for example, to handle the back button being pressed, you add the following code in your main.js file: $(document).delegate(“#main”, “pageinit”, function() { $(“#main .ui-btn-back”).bind(“vclick”, function() { tizen.application.getCurrentApplication().exit(); return false; }); });

You can also bind any other actions to events during initialisation in the same way. In this sample application, all the click events for the items in the list elements are implemented in this way: $(“#display-info”).bind(“vclick”, getSystemProperty(“DISPLAY”, return false; });

function() { onDisplaySuccess);

The remainder of the main.js file contains the functions for retrieving system information and formatting it for display on the page. These functions are all invoked by the actions that were bound to the user events during initialisation. This is how the appropriate piece of system information is displayed when the user clicks an item in the list.

Chapter 4: Piecing Together the Application Jigsaw

71

Defining style attributes in style.css In a Tizen Web UI Framework application, the style attributes are defined in theme files – for example, in the tizen-webui-fw-theme.css file. If you want to override any of these style or layout attributes or add any custom ones, you can do so in the style.css file. For example, in this application, the following colour attribute is set for the list label element: li>label { color:#646464; }

You can modify style and layout attributes and preview them immediately using the CSS Preview feature provided by the IDE, as shown in Chapter 3. Multiple style sheets can be used in your application to style your elements, but due to the way that cascading style sheets are merged, you must be careful about the order they are linked to in the index.html document head.

Looking at other options Performing the initialization while handling the pageinit event is just one way to write your initialisation code. You can also take several other approaches. If you’re using jQuery, then you usually perform your initialisation when the documentready event is triggered, which is when all the HTML elements in the page have finished loading. Alternatively, you may decide to do your initialisation when the standard window onload event is triggered. The drawback of the onload event

is that it’s generated only when all the content of a page, including images, has loaded. This situation may be a problem if your page contains images and other content stored on remote servers, which may take a while to load. Ultimately, you should choose whichever method is suitable for your application, based on the application type, the quantity of content that it displays, and the type of initialisation actions you need to perform.

72

Part II: Getting Practical

Chapter 5

Testing and Debugging In This Chapter ▶ Testing your app on the Simulator, Emulator, and a device ▶ Debugging your application

I

n an ideal world, your application will emerge fully formed, free from bugs and working smoothly on all released devices – some of which may not have even been thought of yet. But because you probably don’t live in an ideal world, it’s vital to test your app at all stages of the development process. From adding the first few elements of functionality and user interface ideas right through to the final finishing touches before release, you need to ensure that your app is tested on as many devices and in as many situations as possible. The Tizen SDK includes a set of tools to help you with testing and debugging throughout your development process. The Simulator and Emulator let you test your application before you run it on a device, while the Remote Web Inspector helps you track down the bugs that creep into even the most carefully written project. In this chapter, we give you a tour of these tools and explain how you can use them to make sure that your app is a well prepared as possible when you, as its proud parent, send it out into the wide world. This chapter refers to the tools included with the 2.1 Magnolia release of the Tizen SDK.

74

Part II: Getting Practical

Testing Your App

The quickest way for you to test and debug your applications without having to package and install them on the Emulator or a device is to use the Simulator. The Simulator is based on the Ripple UI framework and runs in the Google Chrome browser, so you must have Chrome installed on your development machine. The Simulator uses the Chrome/WebKit backend to render your application’s layout, and you can debug your app using all the standard Chrome development features, including the Web Inspector. In the Simulator, the Tizen device APIs are implemented using JavaScript, so you may see differences between running your app in the Simulator and running on the Emulator or a real device.



In the Simulator shipped with the Tizen 2.1 release, the implementation of some of the APIs may be incomplete, check the Tizen 2.1 Release Notes for more information.

Running in the Simulator To run your application in the Simulator, right-click your project in the Project Explorer window and choose Run As ➪ Tizen Web Simulator Application or click the Run icon at the top of the IDE window and choose Simulator from the Run As dialog box, shown in Figure 5-1.

Figure 5-1: Run As dialog box.

Chapter 5: Testing and Debugging

75

Figure 5-2 shows the Simulator running in a Google Chrome browser window. The Simulator lets you control device settings so that the simulated environment is closer to the one you’re developing for. You can also inject events, such as incoming calls, location information, and sensor values, to check that your app responds to these events correctly. The Tizen Emulator’s Event Injector is even more powerful; we discuss it in more detail in the ‘Using the Event Injector’ section, later in this chapter. Press F12 to launch the Web Inspector to debug your code and view console log messages.

Figure 5-2: The Simulator.

Testing with the Emulator The Simulator is best used for perfecting the look and feel of your app and testing functionality that isn’t Tizen specific. For testing device specific functions, you’ll want to turn to the Emulator.

76

Part II: Getting Practical The Emulator in the Tizen SDK is based on the open source QEMU project. You can think of the Emulator as a strict implementation of a device specification, matching the device much more closely than the Simulator. It emulates the entire platform, including built-in applications, user settings, and access to the file system, including movies and images, just like a real device. You can also control the screen size and pixel density of the Emulator image, inject events into your application, and create multiple Emulator images, all of which help ensure your app is running smoothly before you run it on a real device. Of course, you still encounter differences when testing on the Emulator versus a device – for example, Bluetooth and Wi-Fi aren’t supported in the current version. However, if you don’t have access to a device, the Emulator is the next best thing. In version 2.1 of the Tizen SDK, the Emulator supports only images that use the x86 architecture, but later versions will support ARM. You can enhance the performance of x86 Emulator images on the host machine using hardware virtualization support built into Intel processors that support Virtualization Technology (VT). If you’re running on Windows or Mac OS X, you’ll need to install the HAXM (Intel Hardware Accelerated Executed Manager) soft- ware to enable this feature, while on Linux, you need to use a Kernel Based Virtual Machine (KVM). This feature really makes a big difference to the performance of the Emulator.



You can find the system requirements and instructions for installing the Intel HAXM on Windows or Mac OS X on the developer website at: https://developer.tizen.org/downloads/ sdk/installing-sdk/hardware-acceleratedexecution-manager

Using the Emulator Manager to create an image Before you can launch your application in the Emulator, you need to use the Emulator Manager to create an Emulator

Chapter 5: Testing and Debugging

77

image. To launch the Emulator Manager, click the Emulator Manager icon in the Connection Explorer panel. The Emulator Manager window appears, as shown in Figure 5-3. You can also launch the Emulator Manager from the command line or from the application menu.

Figure 5-3: The Emulator Manager.

To create a new Emulator image:

1. In the Emulator Manager, click the Create New option for the version of the platform you’re targeting.

The detail panel on the right of the window now includes a Create button.

2. Click the Create button and give the Emulator a name.

Confirm and Cancel buttons now appear at the bottom of the window. You can configure several options for the Emulator, including the display resolution and density.





If your system supports hardware acceleration through KVM or HAXM, make sure that the HW Virtualization option is marked as Enabled. 3. Click Confirm.

Your new Emulator appears in the Emulator Manager list.

78

Part II: Getting Practical

Launching an Emulator instance To launch an Emulator instance, select the required Emulator image in the Emulator Manager list and click the Launch button. The Emulator launches. After the Emulator is connected, it appears in the Connection Explorer panel. You can configure several options of the running Emulator. Simply right-click the Emulator and choose items from the menu shown in Figure 5-4. You can set the device rotation and the scale, take screenshots, and set the USB keyboard options. You can also launch an sdb shell command window by clicking the shell option. For more about the Smart Development Bridge (SDB), see the section ‘The Smart Development Bridge’, later in this chapter.

Figure 5-4: The Emulator configuration menu.

Chapter 5: Testing and Debugging

79

Using the Connection Explorer The Connection Explorer is used to view and manage connected devices – both Emulator instances and actual devices. You can also use the Connection Explorer to view and modify the contents of the device or Emulator’s file system. Figure 5-5 shows the file system of a connected device.

Figure 5-5: Viewing and modifying the Emulator file system.

A great feature of the SDK is that it allows you to test your application on multiple Emulators and devices simultaneously. This ability is really useful when you want to compare your UI design running on multiple different screen resolutions. When you use this feature, the currently active device or Emulator instance is highlighted in the Connection Explorer, as shown in Figure 5-6.

Figure 5-6: The Connection Explorer.

80

Part II: Getting Practical This highlighting is important because it helps you ensure that you’re launching your application or injecting events into the correct Emulator instance.

Running your application in the Emulator To run your application in the Emulator, right-click your project in the Project Explorer window and choose Run As➪Tizen Web Application or click the Run icon at the top of the IDE window and choose web application from the Run As dialog box, shown in Figure 5-7.

Figure 5-7: The Run As dialog box.

Your application is then copied, installed, and run on the currently active running Emulator. Figure 5-8 shows the Systeminfo sample application launched in the Emulator. While your app is being installed on the Emulator, you can see the status of the operation in the Progress panel.

Using the Event Injector While your app is running in the Emulator, you can use the Event Injector to inject real device events into the Emulator to see how your app responds. If you have a location-aware app, for example, you can test it by injecting a latitude and longitude value into the Emulator. In Version 2.1 of the Tizen SDK, the Event Injector can simulate device, location, NFC, sensor, and telephony events. Figure 5-9 shows the Event Injector window.

Chapter 5: Testing and Debugging

Figure 5-8: Application running in the Emulator.

Figure 5-9: Event Injector.

81

82

Part II: Getting Practical The Event Injector is located in the IDE on the right-hand side of the default Tizen Web Perspective, as shown in Figure 5-10. If you don’t see the Event Injector, go to the Window menu in the IDE and choose Show View➪Event Injector.

Figure 5-10: The Tizen Web Perspective.

The Event Injector is a very powerful testing tool. You can inject events into the currently active Emulator instance by selecting various options from the different tabs in the Event Injector. The device events you can send to the Emulator include simulating battery and RSSI levels, ear jack and USB connections,and mounting SD card images. From the Locations tab, you can choose to enter a manual location or prelogged GPS data from a log file. You can simulate the detection of NFC tags, inject values for the accelerometer, magnetic, proximity, and other sensors, and even simulate receiving and sending sms messages and calls.

Testing your app on a device Testing your app using the Simulator and Emulator can only take you so far. Before your app is finished, you need to test it on a real Tizen device. The Tizen SDK makes testing your app on a device relatively easy, and it’s a very similar process to testing using the Emulator.

Chapter 5: Testing and Debugging

83

You must set your device date and time to the current date, or you’ll be unable to deploy any web applications to it.

Connecting the device If you’re using the Windows version of the SDK, you need to download and install the Windows USB driver from www. samsung.com/sec/support/pcApplication/USB. When the Windows USB driver is installed correctly or you’re using the Linux or Mac OS X version of the SDK, you can connect the device to the computer using a USB cable. The connected device appears in the Connection Explorer, as shown in Figure 5-11. To select the device, highlight it in the Connection Explorer.

Figure 5-11: The Tizen device shown in Connection Explorer.

Running your app on the device Running your app on the device is just like running on the Emulator: Right-click your project in the Project Explorer window and choose Run As➪Tizen Web Application or click the Run icon at the top of the IDE window. Your application is copied, installed, and run on the device.

Tracking Down the Bugs If you live in an ideal world, you don’t even need to read this section. Your code will perform flawlessly on the Emulator and device, and you won’t need to even launch the debugger. For those of you that aren’t so talented, the presence of powerful, easy-to-use development tools is vital when developing for any platform. Fortunately, Tizen provides a range of debugging options.

84

Part II: Getting Practical The Tizen SDK includes the Remote Inspector tool, which allows you to remotely debug and profile your web application running in the Emulator and on the device. The Remote Inspector is based on the WebKit Web Inspector and has been enhanced to support remote debugging. You can also debug applications running on the Simulator, which supports the standard WebKit Web Inspector. You can use both the Remote Web Inspector and the Simulator Web Inspector to debug JavaScript and inspect the Document Object Model (DOM), CSS, and resources. It also provides profiling based tools such as stack analysis and storage usage analysis. The key bindings of the Web Inspector conflict with the key bindings of Eclipse, with Eclipse taking precedence. So if you want to use the Web Inspector shortcut keys, you need to unmap the Eclipse key bindings. You can find more information by searching for key bindings in the SDK Help.

Debugging in the Simulator To debug your web application in the Simulator using the Web Inspector, you first need to launch it using one of the methods described in the earlier ‘Running in the Simulator’ section. Then you can launch the Web Inspector by pressing the F12 function key (see Figure 5-12).

Figure 5-12: The Web Inspector.

Chapter 5: Testing and Debugging

85

After you open the Web Inspector, you’re ready to debug your JavaScript as described in the ‘Debugging JavaScript’ section, later in this chapter.

Debugging in the Emulator To debug your application in the Emulator with the Remote Inspector, right-click your project in Project Explorer and choose Debug As➪Tizen Web Application or click the Debug icon at the top of the IDE window. Your application is then copied, installed, and launched in the currently active Emulator, and the Remote Inspector is displayed in a new Chrome browser window, as shown in Figure 5-13.

Figure 5-13: The Remote Inspector.

To use the Remote Inspector, you must have the Google Chrome browser installed on your host machine.

86

Part II: Getting Practical

Debugging on the device To debug your application on the device, you just perform the same operations as if you’re using the Emulator: Rightclick your project in the Project Explorer window and choose Debug As➪Tizen Web Application or click the Debug icon at the top of the IDE window. Your application is then copied, installed, and launched on the device, and the Remote Inspector appears in a new Chrome Browser window.

Debugging JavaScript Note: This information is relevant for whichever debugging environment you’re using. To debug your JavaScript, choose the Sources option from the menu to view the JavaScript files in the Remote Inspector window, as shown in Figure 5-14. You can select the required JavaScript file to debug by clicking the arrow next to the filename.

Figure 5-14: The Remote Inspector sources view.

Chapter 5: Testing and Debugging

87

To set a breakpoint in the JavaScript, right-click the number next to the line of code you want to add the break point to and choose the Add Breakpoint from the menu, as shown in Figure 5-15. Then perform the operation in the Emulator that will execute the code where you’ve added the breakpoint. When the breakpoint is hit, the code execution pauses (see Figure 5-16), and you can inspect variables, view the call stack, and step through the code.

Figure 5-15: Setting a breakpoint.

You can also debug your JavaScript by adding debug statements into your code using the console.log() function. Any log messages will be displayed in the IDE’s console panel at the bottom of the Web Perspective.

88

Part II: Getting Practical

Figure 5-16: Hitting a breakpoint.

Using the Smart Development Bridge The SDK includes a device management tool called Smart Development Bridge (SDB). You can use this command line tool to manage multiple device connections and provide basic commands useful for application development. You can use SDB with either the Emulator or a Tizen device. To use SDB with a Tizen device, you must set the device to SDB mode. You can set this mode from the device by choosing Settings➪More System Settings➪Developer Options from the menu and enabling the USB Debugging mode To use SDB commands to communicate with your device or Emulator instances, you need to open a terminal window on your computer and either navigate to the $INSTALL_LOC/ tools folder or add this directory to your $PATH environment variable.

Using SDB commands Table 5-1 shows a list of SDB commands that you can use to interact with a device or Emulator instance.

Chapter 5: Testing and Debugging

Table 5-1

SDB Commands

Command

Description

sdb connect [:]

Connect to device through TCP/IP

sdb disconnect [:]

Disconnect from a TCP/IP device

sdb push

Copy file/dir to device

sdb pull []

Copy file/dir from device

sdb shell

Run remote shell interactively

sdb shell

Run remote shell command

sdb dlog [option] []

View device log

sdb forward

Forward socket connections, such as sdb forward tcp:26102 tcp:9999

sdb help

Show the Help message

sdb version

Show version number

sdb start-server

Start the server

sdb kill-server

Stop the server if it’s running

sdb get-state

Print the target device connection status

sdb get-serialno

Print

sdb status-window

Continuously print device status for a specified device

In the Emulator, you can also open an SDB shell from the Emulator configuration menu (refer to Figure 5-4).

Discovering the connected devices You can find out what devices or Emulator instances are connected using this command: sdb devices This command returns a list of the devices attached. This list is the same as the list of devices displayed in the IDE’s Connection Explorer (refer to Figure 5-11).

89

90

Part II: Getting Practical If you have more than one device or Emulator instance connected, you need to specify which instance to direct the SDB command to: sdb –s emulator-26100 shell Table 5-2 shows the options that you can use to direct the commands to the required device or Emulator instance.

Table 5-2

SDB Options

Option

Description

-d

Directs the command to the only connected USB device; returns an error if more than one USB device is present

-e

Directs the command to the only running Emulator; returns an error if more than one Emulator is present

-s

Directs the command to the USB device or Emulator with the given serial number

Chapter 6

Porting Your Web App to Tizen In This Chapter ▶ Getting a web app primer ▶ Solving common porting problems

A

s any mobile developer knows, the write-once, run-anywhere promise of HTML5 is still a long way from being realized. Web developers face a lot of challenges, including designing CSS style sheets to cope with different screen sizes, fine-tuning JavaScript code to handle subtle differences in device APIs, and even deciding which app store to sell their wares in. But those same developers also know a good opportunity when they see one and won’t let a few problems get in their way. In this chapter, we examine different aspects of the web app landscape, including platforms, JavaScript frameworks, web API standards, and app stores. We focus on some of the most common web porting problems and provide some solutions. If you’ve built a web page or developed a web app for another platform, this chapter acts as your guide to porting your web app to Tizen. If you want to make your Tizen web apps more portable, we’re here to help with that, too.

92

Part II: Getting Practical

Everything You Wanted to Know about Web Apps (But Were Afraid to Ask) With the improvement in the performance and capability of HTML5, web applications are booming on mobile. They’re easy to install and maintain, and they allow developers to create platform independent apps. On one hand, the popularity of mobile web applications brings a lot of focus and interest. On the other, the landscape and ecosystem are becoming very crowded. (Figure 6-1 shows you just how crowded.) Before you jump onto the bandwagon, it’s worth considering all the aspects of mobile web app landscape.

Figure 6-1: The web app landscape.

Chapter 6: Porting Your Web App to Tizen

93

The origins of web apps The web application (or web app) concept was first introduced in the Java world as a collection of servlets, HTML pages, classes, and other resources that can be bundled and run on multiple containers from multiple vendors. This is defined in the Java Servlet Specification v2.2. When the XMLHttpRequest (XHR) and asynchronous web technologies,

such as Asynchronous JavaScript and XML (AJAX), became popular, a web application was redefined as a client application using the web browser as a runtime (sometime referring to as a thin client) to access the information from web server or local storage. The early popular web applications included webmail, online stores, and wikis.

Web apps on different platforms Tizen isn’t the first platform to provide an environment for web apps, and it won’t be the last. Many platforms support web apps to some extent, including Blackberry OS, iOS, Android, Windows Phone, Firefox OS (formerly Boot2Gecko), and WebOS. Each of these platforms takes a different approach to web app support. For example, on iOS and Android, the primary development environment is native applications, and web apps are very much second-class citizens by comparison. Device access for these web apps is limited to the features provided by the W3C device APIs. On Tizen, by contrast, the primary development environment is HTML5. Web apps work just like normal apps. Using W3C device APIs and extended Tizen APIs, you can do pretty much everything you need to do from within a web app.

94

Part II: Getting Practical

Tools and frameworks One big advantage of creating apps using web technologies is the huge range of existing tools available. You can use frameworks to build your UI and make it suitable for mobile devices. These frameworks include jQuery Mobile and Zepto. js, which contain utility functions to make your job easier. Some UI frameworks, such as SenchaTouch, even make your web app look exactly a native app on certain platforms. You can also use JavaScript libraries to add particular functionality – for example, Box2DJS, a physics engine used in a lot of games, and RGraph, which you can use to create pie charts, bar charts, and other good-looking graphs. Another useful JavaScript library is Modernizr, which detects whether particular HTML5 and CSS3 features are supported by your browser.



Taking the time to explore existing technologies and choosing the right tool for your job will definitely help shorten your development time.

Standards Another good thing about the web technology is that it’s open and standards driven. The World Wide Web Consortium (W3C) is the main body that drives these standards – for example, the device APIs on mobile. But other organisations, such as the GSM Association (GSMA), publish requirements and APIs for web apps. The GSMA OneAPI is designed to allow developers to create platform independent apps containing features such as operator billing that work for all network operators. This builds on the work of previous organisations such as the Wholesale Application Community (WAC), which is now integrated into GSMA.

Chapter 6: Porting Your Web App to Tizen



95

Some platforms extend the W3C device APIs by defining their own proprietary device APIs. However, using these APIs makes your web app less portable, so you gain features at the expense of compatibility. It’s the web app developer’s dilemma.

Distribution The final part of web app landscape is the distribution channel, including the app stores in which you sell your web apps. The distribution channel is the most important part of the ecosystem because it’s how you’ll start making money from your app. However, supporting multiple stores on multiple platforms can also become complicated. Some stores, such as the Chrome Web Store and the Mozilla Marketplace, accept stand-alone web apps, but use different packaging formats. The Chrome store requires web apps to be packaged as .crx files, while Mozilla Marketplace requires .xpi packages. Other stores, including the Apple iOS App Store and Google Play, accept only native applications, so you’ll have to wrap your web code in a native app in order to gain entry to these stores. Note: The Tizen store is in the preparation stage at the time of writing.

Porting Problems Solved Creating a web app that provides a consistent user experience and performs well across all platforms is still a challenge for developers. The reasons are varied, from different mobile web browsers, web engines, and varying implementations of WebKit and W3C standards to device-specific differences, such as screen size and ratio.

96

Part II: Getting Practical In this section, you find solutions to some of the most common porting problems and discover how to make your web app work well on Tizen.

Handling different package formats Table 6-1 shows the packaging formats used by different platforms. To port your web app from one of these platforms to Tizen, you need to package your files as in the standard W3C web widget format, a .wgt file. .xpi stands for Mozilla Cross-platform Installer. .crx stands for Google Chrome Extension. Web apps come in three different styles: ✓ A hosted web app hosts its content on a web server and is accessed using a browser. It’s easy to maintain and doesn’t need anything installed on the device, but it requires a network connection to retrieve its content. ✓ A packaged web app, such as a Tizen web app, is installed on the device, works just like a native app, and can work offline without a network connection. Many of these apps also access content from remote web servers, which, of course, requires a network connection. ✓ A hybrid app is built using the same web technologies as hosted and packaged apps, but wrapped up in a native app shell from within which your web code is run. The iOS App Store and Google Play only accept native apps, so to sell your app in these stores, you must build it as a hybrid app.

(installable bundle)

myscript.js*

.crx

*This file/folder is optional

.xpi

options.xul*

main.html

Format

install.rdf*

icon.png

/img folder*

manifest.webapp

manifest.json

Content

Mozilla Marketplace

Chrome Store

.zip

/img folder

splashscreen.png .ipk

sources.json

/css folder

/js folder

index.html

icon.png

appinfo.json

webOS

/img folder*

/css folder

/js folder

default.html

package.appxmanifest

Windows Phone

Web App Package Formats

Stores

Table 6-1

.wgt

/img folder*

/css folder*

/js folder*

index.html

icon.png*

config.xml

Tizen

Chapter 6: Porting Your Web App to Tizen

97

98

Part II: Getting Practical

Making your layout flexible If you use hard-coded values for the layout design in your CSS file, your app will probably not display correctly when running on a device with a different screen resolution or ratio (16:9 compared to 4:3, for example). The solution to this layout problem is to use percentage values (fluid layout) or em values (elastic layout) for the layout or to adjust the viewport using the media queries provided by CSS3. Figure 6-2 shows an example of a web page with a fixed layout. The elements inside the container have a fixed width, and the layout won’t be adjusted when the app is run on a device with a different screen resolution or ratio.

Figure 6-2: Fixed layout design.

If you run the original Aura sample on a device with greater horizontal and vertical resolution, the layout won’t use the full screen, and the results will look something like Figure 6-3.

Chapter 6: Porting Your Web App to Tizen

99

The following CSS code is taken from the main.css file of an open source application called Aura: .stage { width: 1024px; height: 600px; position: relative; overflow: hidden; -webkit-transform: translateZ(0); }



You can download the original Aura source code from https://github.com/blackberry/WebWorks-Samples/ tree/master/Aura. The preceding code was initially designed for the Blackberry PlayBook, which has a screen resolution of 1024 × 600. If you run the same application on the Tizen reference device, which has a higher resolution of 1280 × 720, the background image occupies only part of the screen, as shown in Figure 6-3. To solve this problem, you can use the percentage values for the DOM elements, and the fluid layout example is shown in Figure 6-4.

Figure 6-3: Aura on Tizen.

Our updated CSS code for a fluid layout of the Aura app looks like this: .stage { width: 100%; position: relative; overflow: hidden; -webkit-transform: translateZ(0); }

100

Part II: Getting Practical

Figure 6-4: Fluid layout design.

The principle of a fluid layout is to use percentage values to accommodate a change in screen resolution. Because the percentage value is a relative value, it refers to the size of its parent element. In Figure 6-4, you can see that the width of each element is specified as a percentage of the width of the containing block.



When using HTML5 in strict mode, the parent element of percentage element must also have its size in percent. Otherwise, an error occurs. You can use other methods, such as the viewport and media queries, to optimise your mobile app’s layout. You can set the layout viewport to the device width with this HTML code:

This code ensures that your app is optimized to take advantage of the full device width of a mobile device. The media query in CSS3 allows you to detect the screen size of device and adjust the style accordingly:

Chapter 6: Porting Your Web App to Tizen

101

@media screen and (max-width: 1024px){ .stage { width: 1024px; height: 600px; position: relative; overflow: hidden; -webkit-transform: translateZ(0); } } @media screen and (max-width: 1280px){ .stage { width: 100%; position: relative; overflow: hidden; -webkit-transform: translateZ(0); } }

Fixing inconsistent behavior One common reason that you may have problems when porting your web app to Tizen is the inconsistent behavior of HTML5 device APIs. The WebKit comparison table created by Peter-Paul Koch (available on his blog at www.quirksmode.org) illustrates that none of the current mobile platforms provides an identical implementation of WebKit. Koch ran compatibility tests on 19 different versions of WebKit running on browsers on platforms including iOS, Android, Blackberry, and Symbian, and the inconsistent results he received led him to declare, ‘There is no WebKit on Mobile.’ Just because a browser or web runtime is based on WebKit, you can’t rely on consistent behavior when you port your web app between platforms. When Aura was first ported from the Blackberry Playbook to Tizen, the behavior of the accelerometer produced some interesting results. In Figure 6-5, notice that the clouds are flying at a 90-degree angle instead of falling straight down. Either some quite unexpected weather was on the way, or the code that used the accelerometer was producing some strange results. Digging into Aura’s JavaScript code of rope.js, we found the explanation: The PlayBook implements the accelerometer’s x, y, and z axes differently to Tizen (and most other platforms).

102

Part II: Getting Practical

Figure 6-5: Accelerometer performance.

The W3C device orientation API definition states that ‘The device coordinates frame is defined relative to the screen in its standard orientation, typically portrait.’ But the portrait mode as implemented by the PlayBook corresponds to the landscape mode of most other devices. When it comes to the implementation of gravity and acceleration in Aura, on Playbook, it looks like this: //rope.js ... var gravity = new Vector(0, 9.8); var acc = new Vector(0, 0); ... window.addEventListener(“devicemotion”, function(event) acc.x = event.accelerationIncludingGravity.x; acc.y = -event.accelerationIncludingGravity.y; }, true); ... function draw(){ ... if(acc.x * acc.x + acc.y * acc.y > 9) { var accAngle = Math.atan2(acc.y, acc.x); gravity.x = Math.cos(accAngle) * 9.82; gravity.y = Math.sin(accAngle) * 9.82; } else { gravity.x = 0; gravity.y = 9.82; } ... }

{

Chapter 6: Porting Your Web App to Tizen

103

The variable accAngle represents the angle between the rope and the x axis. To fix the cloud problem on a Tizen reference device that is implemented according to the W3C standards, you have to change one line of the JavaScript to this: var

accAngle = Math.atan2(-acc.x, acc.y);

This is just one real-life example of the pitfalls of porting web apps between platforms. Other inconsistencies may include the availability of JavaScript code acceleration, which may affect performance, or the permissions required to access device APIs.

Porting device specific libraries Some platforms include particular frameworks and libraries to make web app development easier, but this can create a porting problem. For example, webOS uses the Enyo framework, which was previously used only by webOS apps. Now Enyo is a cross-platform framework that you can use on different platforms, such as Tizen. In this section, we show you how to port OnyxSampler, which is an Enyo UI library sample, to Tizen. To port OnyxSampler to Tizen, follow these steps:

1. Create a new Tizen web app using one of the templates in the SDK



2. Download the OnyxSampler source.

You can find the OnyxSampler source at: https:// github.com/enyojs/onyx/tree/2.0-beta5/ examples/OnyxSampler.

3. Copy the index.html file from OnxySampler to your project, replacing the original file



4. Copy the App.js file from OnyxSampler to your project’s js folder



5. Update the JavaScript paths in index.html.

104

Part II: Getting Practical 6. Add the following to your index.html file, replacing any existing elements:

By adding the URLs of enyo.js, enyo.css and other related files to the index.html file, you are specifying that these files should be loaded at runtime. While this means that you have to have an internet connection for the app to run, it does ensure that you’re always using the latest version of the libraries. An alternative approach would be to copy all the JavaScript files to your project, but this increases the memory footprint of your app and of course these files might become outdated. Notice that we’ve also included App.js which you copied to the project in Step 4.

7. Run your app on the Simulator or device from within the Tizen IDE. Figure 6-6 shows OnyxSampler running on Tizen.

Making your app more portable Unfortunately, you can’t rely on web browsers to implement HTML5 features in a consistent fashion. To allow for this variation, you need to ensure that your JavaScript code is adaptable.

Chapter 6: Porting Your Web App to Tizen

105

Figure 6-6: OnyxSampler on Tizen.

For example, the following code shows how to implement support for the vibration API in a browser-independent way: function getVibrationFunc() { var vibrate = function() {}; if (navigator.vibrate) { vibrate = function(p) {navigator.vibrate(p);}; } else if (navigator.mozVibrate) { vibrate = function(p) {navigator.mozVibrate(p);}; } else if (navigator.webkitVibrate) { vibrate = function(p) {navigator.webkitVibrate(p);}; } return vibrate; }

106

Part II: Getting Practical You can also use the mondernizr.js library to detect whether certain HTML5 and CSS3 features are supported by your browser. Modernizr makes it easier to write conditional JavaScript and CSS to handle different situations. You can find out more from http://modernizr.com.

Part III

Tizen in Detail

I

In this part . . .

n this part we look at the Tizen device APIs in detail. You develop code using a mixture of Tizen-specific features and HTML5 APIs. We focus on what you need to know to develop a fully-featured web app, together with hints and tips to make your development easier. You learn how to use the Tizen UI Framework to build a great-looking user interface and how to make use of features such as location and sensors. You find out how to access the device’s contacts and calendars, and how to play back audio and video using a mixture of Tizen-specific features and the HTML5 APIs.

Chapter 7

Building Your UI In This Chapter ▶ Introducing jQuery Mobile ▶ Using basic controls ▶ Taking advantage of UI building tools ▶ Creating advanced UIs

O

f all the ingredients that go to make up that killer app, a well-designed, attractive and fluid user interface is the most important. No matter how great your app may be, if the user interface is cluttered, slow, or difficult to navigate, then your app will gather virtual dust on the shelves of your favourite app store. Take the time to create a great UI, and your app will stand out from the crowd. Users will discover its features and will be more likely to recommend your app to their friends. Your app will be well on its way to bestseller status, and you can look forward to lying on a beach, being brought drinks with their own little umbrellas. Creating the user interface for a touch-based device represents its own set of challenges. Your application needs to be consistent, but it should also be innovative and stand out from the crowd. One example is the Flipboard app, which has been a success on both iOS and Android. In this chapter, we introduce Tizen’s web UI Framework and show you how you can create apps with simple and easy-touse UIs. We explain the basic UI elements, how to use the UI builder and how Tizen’s support for the latest CSS features allow you to create Flipboard-like effects. This chapter puts you well on the way to creating a great UI. We leave the rest of your killer app to you.

110

Part III: Tizen in Detail

Delving into the Nuts, Bolts, and jQuery Mobile Tizen’s UI Framework is built on jQuery Mobile, an open source framework that makes use of the features of the jQuery and jQuery UI open source frameworks. Using jQuery Mobile, developers can create cross-platform UIs for mobile web apps. Tizen adds its own features and user interface elements to give your apps a unique Tizen flavour. To understand the jQuery Mobile framework, you should know some of the basic concepts first. So, without further ado, the following sections examine the important nuts and bolts.

Embedded custom data attributes In the HTML5 specification, custom data attributes are intended to be used to store custom data private to a web page or app. The jQuery Mobile framework makes heavy use of custom data attributes to embed data into HTML5 markup. These data attributes are used to initialize and configure UI elements.

Page structure To use jQuery Mobile, you just need to create an HTML5 page. The page must start with an HTML5 doctype to take advantage of jQuery Mobile library. In the head tag, you can specify a meta data tag viewport for the initial scale and screen size of your mobile web app. Under the body tag, you can create a single or multiple jQuery Mobile page by using data-role= ”page” inside the div. This creates a view that uses up to the full screen of your mobile device if the status bar area is hidden. Inside the page div, you can also add the header, content, and footer sections, as shown in Figure 7-1.

Chapter 7: Building Your UI

111

Figure 7-1: Page structure.

Events jQuery Mobile also provides various types of custom events to create useful hooks between the UI and your JavaScript code. These events cohabit nicely with the native events of the platform. For example, touch-related events include tap, taphold, swipe, swipeleft, swiperight, and pinch. To assign the event to your UI, you just use the following method: $(document).on(‘swipeleft’, function(event, data){ //your implementation of swipeleft event });

While we explain some of the basic concepts of jQuery Mobile, for much more detail, visit http://jquerymobile. com. jQuery is also included with and used by Tizen. Its offi cial website is http://jquery.com.

112

Part III: Tizen in Detail

Exploring the Tizen UI Widgets The Tizen Web UI Framework is an extension of jQuery and jQuery Mobile plus other open source components, such as Globalize. It adapts a lot of common concepts and widgets from the jQuery Mobile library and adds Tizen-specific UI widgets and themes to make your Tizen web app look just like a native app. Table 7-1 shows the widgets available in the Tizen UI Framework. Some widgets are provided by jQuery Mobile (marked as JQM), while Tizen-specific widgets are marked as New. As you can see, quite a few new widgets are specifically designed to match the native UI of Tizen, including a tabbar, data time picker, and a multimedia view. The TizenWinset sample in the SDK demonstrates the use of many of these UI widgets.

Table 7-1

Widgets in the Tizen UI Framework

Name

From

Description

Checkbox

JQM

Basic check box

Radio Button

JQM

Radio button

Button

JQM

Basic buttons

Search filter bar

JQM

Input form for text search

Segment Control

JQM

Group of buttons appearing as a single button

Slider

JQM

Set values as the handle is dragged

Progressbar

jQueryUI

Show the progress of an ongoing operation

Lists

JQM

List of items

List Divider

JQM

List separator for grouping lists

Virtual List

New

List with dynamic data management

Extendable List

New

List that can be extended

Swipe List

New

List item that can be swiped out

Popup

JQM

Pop-up window

Chapter 7: Building Your UI

113

Name

From

Description

Context Popup

JQM

Small pop-up containing a list

Flip Toggle Switch

JQM

Simple two-state switch

Notification

New

Small pop-up indicating device events

Gallery

New

Image collection

Tabbar

New

Grouped items in a header or footer

DateTime Picker

New

Date and time picker

Handler

New

Touch friendly scroll bar

Multimedia View

New

Video and audio player

VirtualGrid

New

Grid with dynamic data management

FastScroll

New

Scroll around a large list using shortcuts

Split View

New

Display different HTML content in two divided panes

Gallery 3D

New

Display images along a curved path on a 3-dimensional coordinate system

Note: These are the UI elements available at the time of writing. For more details consult the UI Framework Reference in the SDK help.

The UI Builder: Just Drag and Drop The UI Builder, introduced in Tizen 2.0, lets you build your user interface visually. You can build your UI by dragging and dropping rather than manually coding HTML. To use the UI Builder, you first need to create a new Tizen web project in the IDE (choose File➪New➪Tizen Web Project) and choose Tizen Web UI Builder from the list of templates. Go through the steps to create the new project, and you see that a file called page1.page has been created inside your project’s page folder. You use this file with UI Builder to create your UI.

114

Part III: Tizen in Detail

Choosing your widgets Getting to grips with the UI Builder is easy, especially if you’ve used similar tools for desktop or mobile development. Figure 7-2 shows the UI Builder interface, while Figure 7-3 shows the page folder and page files in the Project Explorer. The Palette, which is shown on the left of the Page Design View in Figure 7-2, contains all the widgets and elements that are available to use in your app. These widgets are grouped into different categories, such as Buttons, HTML, and Form Elements. You drag and drop widgets from the palette to the Page Design View to construct your UI. (For more detail about the IDE, see Chapter 4.)

Figure 7-2: Page Design View.

Two tabs appear at the bottom of the Page Design View: ✓ Design: Select the Design tab while you’re building the UI. ✓ Preview: Select Preview to see the result as your design develops.

Chapter 7: Building Your UI

115

Figure 7-3: The UI Builder.

The Outline and Properties Views, which are shown on the right-hand side of Figure 7-3, are used a lot during the UI design process. The Outline View shows the hierarchy of div elements within the page. This view provides easy access to elements on the page. In the example shown in Figure 7-4, which was generated using the Navigator UI template, you can see that the List Item elements appear within the List.

Figure 7-4: The Outline View.

116

Part III: Tizen in Detail After you drag the UI widget to the page, you can adjust its default properties from the Properties View. In the example shown in the Figure 7-5, we change the text of the List Item from ‘In The Gym’ to the more realistic ‘In The Kitchen’.

Figure 7-5: Widget Properties View.

Implementing events in the UI builder The UI Builder can also generate code to handle the events supported by Tizen’s predefined UI widgets. For example, a list item supports the SwipeLeft event, and you can generate the skeleton JavaScript code to handle this event from within UI Builder. Highlight the list item in the UI Builder and click the Event Handler tab in the Property Panel. You see a drop-down menu, which lists all the events the List Item widget supports. Choose SwipeLeft to assign this event to the List Item and click the triangle that appears below the menu, as shown in Figure 7-6.

Chapter 7: Building Your UI

117

Figure 7-6: Adding the SwipeLeft handler to the list item.

Clicking the triangle will generate the code to handle this event. The UI Builder will generate the skeleton code to handle this event and add it to the JavaScript file page1.js /** * @param {Object} event * @base _page1_page * @returns {Boolean} */ _page1_page.prototype.listitem3_onswipeleft = function(event) { };

Adding Some Flourish to Your UI Tizen supports the latest HTML5 CSS3 features, which allow you to build some slick user interface effects into your apps.

118

Part III: Tizen in Detail In this section, we show you how to create a UI using the CSS3 3D animation features. While these features aren’t Tizen specific, they do demonstrate the compatibility and performance of the Tizen web runtime. (You can find more details about CSS3 support in Tizen in the W3C API Specifications section of the SDK Help.) The Flipboard app is an example of a successful mobile app with an innovative user interface. Flipboard is an app that creates your own social news magazine from your Twitter, Facebook, Google+, and other news feeds. Flipboard makes use of the flipping gesture as the primary way to navigate through content. Flipboard is consistent, easy to use, and fun – a lot of the reason that the app was successful. There is an open source project that provides an experimental Flipboard layout and user experience. It’s primarily designed for mobile web sites, but thanks to the HTML5 capabilities of Tizen web apps, it’s easy to integrate into your own app. You can download the project source code at https://github.com/botelho/flipboard-layout The project provides a plugin for the jQuery library called jquery.flips.js. This plugin defines several classes for the page elements:

✓ f-page is for the pages between the cover and back that you need to flip. ✓ f-cover is the cover page. ✓ f-cover-back is the back of the cover. For the page layout, the box class presents the content of the page – for example, the images and articles. These boxes each need an additional “height” and “width” class to give the element percentage-based dimensions.

Chapter 7: Building Your UI

119

A sample HTML page looks like this: Headline Published May 7, 2012 Some text

Figures 7-7 and 7-8 show the final code running on the Tizen development device. The cover page contains the image and flip text.

Figure 7-7: Cover page – f-cover on the Tizen developer device.

120

Part III: Tizen in Detail

Figure 7-8: Flip pages – f-page on the Tizen developer device

The Flipboard type page layout example uses some other open source elements to provide extra functionality, including: ✓ modernizr.js for checking your browser support of CSS properties ✓ jquery.touchSwipe.js for dragging and swiping the pages ✓ jquery.history.js for keeping track of the current state/pages

Chapter 8

Taking Advantage of Location-Based Services In This Chapter ▶ Displaying a map ▶ Converting between addresses and co-ordinates ▶ Dropping a pin on a map

W

ith GPS now a standard feature on smartphones, app stores are heaving under the weight of apps taking advantage of the opportunities offered by location-based services. There are navigation apps, location-based social networking services (such as FourSquare, Path, and Google Latitude), and even apps designed for local search. Users love location-based services because they provide a sense of connection with the world around them. You can discover what’s happening at your current location, find where your friends are, and even be notified of offers at a nearby store. Location is about far more than finding your way home. There are lots of third-party solutions that make it easy to add location based features, such as maps and geocoding, to your Tizen web apps. In this chapter, we show you how to use one such service, Google Maps, together with the W3C geolocation API to display your current location on a map. We also explain how to translate between a location, given as longitude and latitude, and a human readable address.

122

Part III: Tizen in Detail

Finding Your Way Map data normally refers to the geographic data and mapping information that is collected by location service providers, such as Navteq, Telemap, Tele Atlas, and Open Street Map (OSM). These companies provide geographic databases and mapping services to third parties. Location service providers define APIs, which let you access services such as mapping, routing, and POIs. Some of these APIs are highly dependent on the services of a particular provider, such as Google Maps, OSM, and Navteq. The OpenLayer and deCarta APIs are more flexible and aggregate the services of many different providers. You can find more information about the location services provided by OpenLayer and deCarta, on their websites: ✓ OpenLayer JavaScript APIs: http://dev.openlayers.org/releases/ OpenLayers-2.12/doc/apidocs/ files/OpenLayers-js.html

✓ deCarta JavaScript APIs: http://developer.decarta.com/Apis/ JavaScript

Displaying a Map While you can use any of the JavaScript mapping APIs for displaying a map in your Tizen web app, we use the Google Maps API for this example. Here’s how you display a map based on your current location:

1. Get your current location.

You need to use the W3C geolocation API to retrieve the longitude and latitude of the device’s current location:

Chapter 8: Taking Advantage of Location-Based Services

123

navigator.geolocation.getCurrentPosition( function(position) { console.log(‘Latitude: ‘ + position.coords.latitude + ‘Longitude: ‘ + position.coords.longitude); }, function(error) { console.err(‘Failed to get current position’); } );



2. Create the map options.

After you have your current position from Step 1, make sure that the map is centred on these co-ordinates. The Google Maps API lets you specify a set of mapOptions for specifying how the map is displayed. This includes the map centre, zoom level, map type, and Google Street View options: var mapOptions = { center : new google.maps.LatLng( position.coords.latitude, position.coords.longitude), zoom : 6, // zoom value from 0 up to 18 mapTypeId : google.maps.MapTypeId.HYBRID, streetViewControl : false };



3. Display the map.

The final step is to assign the div element that contains the map. For example, if you want to display the map in the page content, add the following to your HTML file:

Then create the map object in your JavaScript code: var map = new google.maps.Map(document. getElementById(‘map’), mapOptions);

124

Part III: Tizen in Detail Figure 8-1 shows a map displayed in the Tizen Emulator.

Figure 8-1: Displaying a map in the Tizen Emulator using the Google map APIs.

You need to request an API key in order to use the Google Maps API. You can find more information here: https://developers.google.com/maps/documentation/ javascript/tutorial You also need to include the Map API URL in your Tizen project config.xml file because it’s an external resource that is accessed from your Tizen app. See Chapter 4 for more details about how to add a URL to the access section of config.xml.

Chapter 8: Taking Advantage of Location-Based Services

125

Finding an Address Displaying a map given a longitude and latitude is relatively simple, but sometimes all you have is a human-readable address. Converting this address into a longitude and latitude is known as geocoding, while the process of translating coordinates to a human-readable form is referred to as reverse geocoding. In this section, we show you how to make use of the Google geocoding service, but there are many other third party geo­ coding APIs available.

Google Geocoder API The Google Maps API provides a geocoder class for geocoding addresses dynamically from user input using the google. maps.Geocoder object. Suppose that you have a text input bar in your HTML code. Listing 8-1 shows how you would translate the user input into coordinates.

Listing 8-1  Geocoding an Address to Co-Ordinates var geocoder; function codeAddress() { var geocoder = new google.maps.Geocoder(); var address = document.getElementById(‘address’).value; geocoder.geocode({ ‘address’: address}, function(results, status) { if (status == google.maps.GeocoderStatus.OK) { map.setCenter(results[0].geometry.location); var marker = new google.maps.Marker({ map: map, position: results[0].geometry.location}); } else { alert(‘Geocode was not successful for the following reason: ‘ + status); } } ); }

126

Part III: Tizen in Detail As shown in Listing 8-1, the google.maps.Geocoder() method is used to create a new Geocoder object. The geocode() method then translates the address that the user entered, with the results returned via a callback function. Two objects are returned in the callback function: GeocoderResult and GeocoderStatus. The GeocodeResult has four properties:

✓ An array of GeocoderAddressComponents ✓ A string containing the human-readable address of this location ✓ A GeocoderGeometry object ✓ An array of strings denoting the type of the returned geocoded element. The GeocoderResult result objects are returned as an array because one geocoder request may return multiple GeocoderResult objects. In our example, we just read the first object from the array. The GeocoderStatus object tells you the status of your geocoder request. The predefined values are ERROR, INVALID_ REQUEST, OK, OVER_QUERY_LIMIT, REQUEST_ DENIED, UNKNOWN_ERROR, or ZERO_REQUEST. Google also provides the Geocoding web service. You can use an HTTP request to access the geocoder directly. This service is designed for geocoding static addresses for placement of app content on a map. It’s not designed to respond in real time to user input. For more information about Google Maps Geocoder API, go to https://developers.google.com/maps/documentation/ javascript/3.exp/reference#Geocoder

X Marks the Spot You need to pin the location you searched (or geocoded) with a marker on the map. Because no Tizen map device API is available at the time of writing, we use the Google Maps overlay API to display the marker on the map.

Chapter 8: Taking Advantage of Location-Based Services

127

To create the marker in Google Maps API, you need two objects: the map where the marker will be displayed and the location for the marker. The following code creates a marker at the specified co-ordinates on a map you created in the ‘Displaying a Map’ section. var marker = new google.maps.Marker({ map: map, position: results[0].geometry.location });

The marker appears on the map, as shown in Figure 8-2.

Figure 8-2: Displaying a marker on a map.

If the map property isn’t specified when the marker object is created, you can use the setMap() method to display the marker once the map object is available: marker.setMap(map)

128

Part III: Tizen in Detail

Chapter 9

Working with Multimedia In This Chapter ▶ Discovering content ▶ Capturing audio, images, and video ▶ Playing video and audio ▶ Streaming from the camera and microphone

W

hile the calendar and contacts of a smartphone hold the key to organizing our lives, it’s the multimedia features that help us relax. We carry the latest movies with us on long journeys, listen to our favourite songs on our daily commute, and use the camera to capture pictures of our friends, with outfits and hairstyles that may come back to haunt them in years to come. Multimedia features are vital for any smart device platform. In Tizen, multimedia support is implemented using a mixture of device APIs and W3C APIs. Multimedia is a fast moving area, so much so that some of the information in this chapter is subject to change. But it’s also one of the most exciting areas of web app development. In this chapter, we explain how to use Tizen’s content features to search for media on your device. We show you how to play back audio and video files, capture images using the camera, and push the boundaries of W3C features by implementing video conferencing type features. So, hold on to your hats – or failing that, make sure that you’re sitting comfortably – and enjoy a practical ride through the latest multimedia possibilities for your Tizen web apps.

130

Part III: Tizen in Detail

Introducing the Multimedia APIs Note: Some of the features mentioned in this chapter are based on draft versions of W3C specifications, so they may change in the future due to the evolving nature of these specifications. Table 9-1 shows APIs you need to use to implement various multimedia features in your Tizen web apps. Some of these are Tizen-device APIs, and some, like getusermedia, are at a very experimental stage.

Table 9-1

Multimedia Features

Feature

Recommended API

Multimedia content discovery

Tizen Device API: Content

Capturing audio

Not currently supported

Capturing images

Tizen Device API: Application

Capturing video

Tizen Device API: Application

Playback of audio files

HTML5 audio element

Playback of video files

HTML5 video element

Streaming video from the device’s camera

W3C API: getUserMedia

If you don’t have access to a Tizen device, you can use a webcam with the Emulator to try out the multimedia functionality described in this chapter. See the SDK Help documenta tion for more information about how to set up a webcam with your system.

Discovering Content The Tizen Content API provides functionality for searching for content stored either locally on your device or an external memory card. You don’t want this sensitive information falling into the wrong hands, and the Tizen platform restricts app access to

Chapter 9: Working with Multimedia

131

the content by using permissions. There are different permission levels, which your app will set depending on whether you want to just find an item or modify an item’s attributes. These permissions are set in the config.xml file. (See the ‘Getting Permission’ section, later in this chapter, for more details). If the appropriate permissions are set, a ContentManager object is created and stored in the content property of your app’s tizen object. You then use this ContentManager to locate content. If the correct permissions are set, you can also update any item’s editable attributes. You can find details of the available methods and the editable attributes in the SDK Help documentation.

Content A content item is an object that contains the attributes of a single piece of content, rather than the content itself. You use the Content interface to access an item’s attributes. In the Tizen platform, the Content interface is extended by the AudioContent, ImageContent, and VideoContent interfaces with attributes specific to the content type. Table 9-2 lists these attributes.

Table 9-2

Attributes supported by Content

Content Type

Attributes

Content

id, name, type, mimeType, title, contentURI, thumbnailURIs, releaseDate, modifiedDate, size, description, and rating

AudioContent

album, genres, artists, composers, lyrics, copyright, bitrate, trackNumber, and duration

ImageContent

geolocation, width, height, and orientation.

VideoContent

geolocation, album, artists, duration, width, and height

132

Part III: Tizen in Detail

Getting permission Because content is private data, the Tizen platform restricts access to this data using different permission levels. Permissions are set in the config.xml file. (See Chapter 4 for more on permissions.) Here are the permissions related to content: ✓ Adding http://tizen.org/privilege/content. read to your permissions gives you access to the methods in the API for searching for content, and watching for added, updated or removed content. ✓ Adding http://tizen.org/privilege/content. write to your permissions gives you access to the methods in the API for updating the attributes of items.

Example: Creating a playlist In this example, we show you how to create a playlist of your ten most recently added audio rock tracks, using the Content APIs. You need to use the find() method to search through all the content, specifying some filters and a sort mode to narrow down the result to your most recently added tracks. Before you start to use the Content APIs, you must set the correct permission in your application’s config.xml file. In this example, you need to set the http://tizen.org/ privilege/content.read permission level. Then you create a couple of attribute filters to narrow down your search to audio content and tracks classified as rock: var audioFilter = new tizen.AttributeFilter(“type”, “EXACTLY”, “AUDIO”); var genreFilter = new tizen.AttributeFilter(“genres”, “CONTAINS”, “rock”);

Chapter 9: Working with Multimedia

133

You can combine these filters using a composite filter with the INTERSECTION filter type, which is equivalent to a logical AND: var searchFilter = new tizen.CompositeFilter(“INTERSECTION”, [audioFilter, genreFilter]);

Because you want to create a list of the most recently added tracks, you need to create a sort mode for sorting the items based on the modifiedDate attribute, presenting the data in a descending order: var sortMode = new tizen.SortMode(“modifiedDate”, “DESC”);

Then you can use the find() method to search for the first ten items that match your search requirements: tizen.content.find(audioFoundCb, errCb, null, searchFilter, sortMode, 10);

As the find() method is asynchronous, you must define a success callback in which to handle the response: function audioFoundCb(content) { // List the audio files found for (var i=0; i

Our application contains a header, content, and footer section within the page area. ✓ Header: The header contains a title and search bar and is fixed to the top of the page. The search bar used is an input element of type search. ✓ Content: The content section contains a list of the SMS messages. The list element uses the data-role listview to apply all the necessary styles and list functionality provided by the UI framework. Because the actual content of the list will be dynamically created based on the search result, you don’t need to add any other information to this index.html file. ✓ Footer: The Footer contains the default back button and is fixed to the bottom of the page. That’s all you need to do to create the application page. The next two sections look at how to fill the message list and implement the search functionality.

Chapter 11: Messaging

165

Filling the message list The content section of the page contains a list of all the SMS messages on the device that meet the search criteria. When the application is started, no search string is entered, so all the SMS messages stored on the device are displayed in the list.

Initialisation This example uses the Tizen UI Framework, which is based on jQuery Mobile, and applications are developed using a page structure. Any initialisation code that needs to be run when the page is loaded should be executed when the pageinit event is fired. In this example, the initialisation code includes functionality to retrieve the SMS message service, and event bindings for the page and the search box. This is implemented in the main.js file, as shown in Listing 11-2.

Listing 11-2  Page Initialisation var init = function () { $(‘div[data-role=”page”]:first .ui-btn-back’).bind(“click”, function(event) { var currentApp = tizen.application.getCurrentApplication(); currentApp.exit(); }); $(“#searchBox”).bind(“input”, updateList); $(“#searchBox”).bind(“change”, updateList); // get message service getMessageService(); }; $(document).bind(‘pageinit’, init);

Searching for messages The message service callback function returns an array containing message service objects. In this example, the SMS message service object is retrieved from the array and stored in a local variable.

166

Part III: Tizen in Detail To search for all the SMS messages on the device, you need to use the message storage object’s findMessages() method with a tizen filter. In this example, you should create an attribute filter to narrow down your search to SMS messages only, as shown in Listing 11-3.

Listing 11-3  Message SERVICE Callback var msgService = null; var msgStore = null; function errCb(err) { console.log(“Error: “ + err.message); } function msgServiceCb(services) { msgService = services[0]; msgStore = msgService.messageStorage; var typeFilter = new tizen.AttributeFilter(“type”, “EXACTLY”, “messaging.sms”); msgStore.findMessages(typeFilter, msgFoundCb, errCb); }

Drawing the list The findMessages() method is asynchronous, so when the action is completed, the callback function is returned with an array containing all the messages that meet the search criteria. At this point, all the SMS messages stored on the device are returned within the array. If no SMS messages are found, the success callback is invoked with an empty array. If any errors occur while searching for contacts, the optional error callback is invoked. To display the messages as shown in Figure 11-1, you need to populate the msgList list element that was defined in the index.html file. The list items are displayed using Tizen UI Framework bubble class elements, with incoming messages displayed on the lefthand side and outgoing messages displayed on the right-hand side.

Chapter 11: Messaging

167

Listing 11-4 shows the code to create and display the message list. The first action is to clear any previous list data using the remove() method, and then you can append the new list data. To differentiate between the incoming and outgoing messages, you can check the from message attribute, which will be empty for outgoing messages. To create each list item, you need to append a list item element with the relevant bubble class type to the msgList list element. In this example, the body text and timestamp of the message is added to the list item. After the list has been populated, you tell the framework to update the list using the List View’s refresh() method.

Listing 11-4  List Drawing function addZero(time) { return time < 10 ? “0” + time : time; } var msgData = null; function drawList() { // Clear the list $(‘#msgList li’).remove(); // Draw the bubble list if(msgData){ for(var i=0; i