PhoneGap. Cross-platform Programming Lecture 2. Alessandro Grazioli. Università Degli Studi di Parma. Distributed Systems Group

Transcription

1 Crossplatform Programming Lecture 2 PhoneGap [email protected] 2015 Parma

2 Outline Introduction Installation The Command Line Interface (CLI) Create, build and install apps with the CLI Plugins PhoneGap Build Service Useful commands Configuration Preferences Features APIs 2015 Parma

3 Introduction Originally developed by Nitobi, it was acquired by Adobe in 2011 Sometimes referred to as PhoneGap, sometimes as Cordova The original name of the project was PhoneGap In 2011 Adobe donated the codebase to the Apache Software Foundation (ASF) to maintain a transparent and open governance and to make it easier for large organizations to contribute To avoid intellectual property fetters, PhoneGap had to be renamed Since the project was born in Nitobi office, located in Cordova Street, Vancouver, the new name for the project was chosen as Cordova PhoneGap is a distribution of Apache Cordova (i.e. Cordova is the engine that powers PhoneGap, similar to how Webkit is the engine for Chrome or Safari) As of January 2015, Cordova and PhoneGap are the same project, but in the future, the latter may include new features not suitable for an ASF project 2015 Parma

4 Introduction Adobe PhoneGap is a standardsbased, opensource development framework for building crossplatform mobile apps with HTML, CSS and JavaScript for ios, Android, Windows Phone, webos, BlackBerry, Tizen, and more Its purpose is to allow HTMLbased web applications to be deployed and installed as native applications These web apps are wrapped in a native application and can be installed via the app stores for multiple OS To develop PhoneGap applications, you must install SDKs for each mobile platform you are targeting To develop for ios, you need Mac OS due to the restrictions imposed by Apple 2015 Parma

5 Supported platforms and features iphone / iphone 3G iphone 3GS and newer Android Blackberry OS 6.0+ Blackberry 10 Windows Phone 8 Ubuntu Firefox OS Accelerometer Camera Compass X X Contacts File X Geolocation Media X X Network Notification (Alert) Notification (Sound) Notification (Vibration) Storage 2015 Parma

6 PhoneGap installation PhoneGap requires the installation of the command line tools To install the Command Line Interface (CLI): download and install Node.js from to use npm package manager open a terminal and install the phonegap utility by running the following command (g flag specifies a global installation) sudo npm install g phonegap Alternatively, you can install cordova with the following command sudo npm install g cordova On Linux and Mac OS, if during the installation of Node.js your password was required, you need to prefix sudo, since npm was installed with root privileges and therefore needs such privileges to run 2015 Parma

7 Create a new app with PhoneGap To create a new app, use the CLI as follows: phonegap create hello n HelloWorld i com.example.hello The first argument, hello, specifies the directory to be generated for your project its www subdirectory houses your application's home page, along with various resources under css, js, and img The other two arguments are optional: the second argument, HelloWorld, provides the application's display text (its name in the menu of the device) the third argument, com.example.hello, provides your project with a reverse domainstyle identifier The i and n commandline options (you can also use name and id) make these explicit By default, PhoneGap s creation script generates a skeletal webbased application whose home page is www/index.html, with its default logic referenced from www/js/index.js 2015 Parma

8 Building an app with PhoneGap To build an app use the CLI as follows phonegap build ios cordova build ios phonegap build android cordova build android if you use cordova, first you have to download target platform files with cordova platform add ios cordova platform add android The build command compiles an application for whichever platform you specify and generates platformspecific files within the project's platforms subdirectory If you need lowlevel details, use the V (verbose) option The first time you build for a platform, PhoneGap downloads missing Cordova libraries for that specific platform Also, the first time you compile, platformspecific subdirectories of platform directory are created (e.g. platform/ios or platform/android) and the compiled files are stored in those 2015 Parma

9 Università Degli Studi di Parma To test the way an application interacts with platform features, install it onto a device or emulator phonegap install ios phonegap install android Building an app with PhoneGap cordova install ios cordova install android If your device is connected and properly configured, the application displays there by default, otherwise it displays on the emulator (you can add emulator option to force installing on emulators) To run it on a real Android device, you have to enable the USB debugging option on the device, and possibly add a USB driver depending on your development environment build and install commands are deprecated, so use the run command performs them both phonegap run ios phonegap run android The first time you run a program for ios, PhoneGap may ask you to install additional tools such as iossim and iosdeploy which respectively allow running the ios simulator and installing apps from the command line sudo npm install g iossim sudo npm install g iosdeploy 2015 Parma

10 PhoneGap plugins Plugins are necessary to communicate closely with various devicelevel features A plugin is an addon code that provides an interface to native components You can design your own for advanced and custom functionalities, or add the available ones to enable PhoneGap's basic devicelevel features To add plugins to your app, use the phonegap plugin add command which requires you to specify the repository for the plugin code 2015 Parma

11 PhoneGap plugins Basic device information (Device API) allows getting device model, platform, UUID, version ad name phonegap plugin add org.apache.cordova.device Network Connection type (Ethernet, WiFi, 2G, 3G, 4G, ) and Battery Status (notifies whenever battery charge changes of 1%) phonegap plugin add org.apache.cordova.networkinformation phonegap plugin add org.apache.cordova.batterystatus Accelerometer, Compass, and Geolocation phonegap plugin add org.apache.cordova.devicemotion phonegap plugin add org.apache.cordova.deviceorientation phonegap plugin add org.apache.cordova.geolocation 2015 Parma

12 PhoneGap plugins Camera (provides access to the device's default camera application), Media Playback and Capture (provides access to the device's audio, image, and video capture capabilities) phonegap plugin add org.apache.cordova.camera phonegap plugin add org.apache.cordova.pluginmedia phonegap plugin add org.apache.cordova.mediacapture Access files on device or network (File and Filetransfer APIs) phonegap plugin add org.apache.cordova.file phonegap plugin add org.apache.cordova.filetransfer Notification via dialog box or vibration phonegap plugin add org.apache.cordova.plugindialogs phonegap plugin add org.apache.cordova.pluginvibration 2015 Parma

13 PhoneGap plugins Access Contacts phonegap plugin add org.apache.cordova.contacts Access locale settings (i.e., language, date, numbers and currency formats) with Globalization API phonegap plugin add org.apache.cordova.globalization Show/hide a SplashScreen phonegap plugin add org.apache.cordova.splashscreen Open a browser window with InAppBrowser phonegap plugin add org.apache.cordova.inappbrowser 2015 Parma

14 PhoneGap plugins Use plugin list command to view currently installed plugins phonegap plugin list To remove a plugin, use plugin remove command and refer to it using the identifier that appears in the list (this corresponds to subdirectories within the project's plugins directory) For example, to remove support for the camera use: phonegap plugin remove org.apache.cordova.camera 2015 Parma

15 PhoneGap Build service By default, building an application generates files in various subdirectories within platforms, and relies on locally installed SDK tools as an alternative, you can build the application remotely using Adobe's PhoneGap Build service It allows building and compiling mobile applications without SDKs, compilers and hardware Compiling is provided as a cloud service so that programmers do not need to maintain native SDKs Developers only need to upload their HTML5, CSS, and JavaScript assets to the service and Adobe does the work of compiling It is available for ios, Android and Windows Phone 8 Open source apps Free Plan Paid Plan Adobe Creative Cloud Membership unlimited (must be pulled from a public Github repo) Private apps 1 25 Max app size 50 MB 100 MB 1 GB Core cordova plugins YES 3rd party plugins YES Upload plugins NO YES Collaborators Price unlimited (invite people to your app as either developers or testers) Free Starting at $9.99/mo Sign in with your Adobe ID 2015 Parma

16 PhoneGap Build service You need an account on the PhoneGap Build site to use the login command and associate your commandline environment with the account phonegap remote login u my @myprovider.com p mypassw0rd phonegap remote login username my @myprovider.com password mypassw0rd To compile your app remotely, prefix the build command with the additional remote command phonegap remote build ios To use plugins, you must first add them locally as previously described, then build remotely The remote compiling generates a QR Code in the PhoneGap Build interface Use a QR Code reader to scan the image, and the app installs overtheair onto your device 2015 Parma

17 PhoneGap useful commands To update PhoneGap to the last version use the CLI as follows: sudo npm update g phonegap The version command, or the v option, displays the currently running version phonegap version phonegap v The following commands apply to Cordova sudo npm update g cordova cordova v 2015 Parma

18 PhoneGap configuration Global configuration settings are stored in config.xml file It is placed on top of the asset directory, along with the app s home page For projects created with the CLI and PhoneGap Build, the config.xml file can be found in the toplevel www directory app/www/config.xml When using CLI to build, versions of the file are passively copied (along with other webasset source files) into various platforms/* subdirectories and platformspecific elements will be added to them app/platforms/ios/www/config.xml app/platforms/blackberry10/www/config.xml For Android the path is different since it includes an additional assets directory app/platforms/android/assets/www/config.xml 2015 Parma

19 PhoneGap configuration widget: its id attribute provides the app's reversedomain identifier, and version its full version number name specifies the app's formal name, as it appears on the device's home screen and within the appstore description and author specify metadata and contact information that may appear within appstore listings wcontent (optional): defines your app's starting page in the toplevel web assets directory (by default it s index.html) <widget id="com.example.hello" version="0.0.1"> <name>helloworld</name> <description> A sample Cordova application. </description> <author ="dev@ .com" href=" Developers Team </author> <content src="index.html" /> <access origin="*" /> <preference name="fullscreen" value="true" /> <preference name= ="true" /> <feature name="geolocation"> <param name="iospackage" value="cdvlocation" /> </feature> </widget> A platformspecific config.xml sample access defines the set of external domains the app is allowed to communicate with preferences sets various options as name/value pairs (see next slides) features specify included plugins (only available in platformspecific config.xml files) 2015 Parma

20 PhoneGap configuration Global preferences Commonly used global preferences Fullscreen allows hiding the status bar at the top of the screen (default is false) <preference name="fullscreen" value="true" /> Orientation allows locking the orientation and prevent the interface from rotating in response to changes in orientation Possible values are default, landscape, or portrait default value means both landscape and portrait orientations are enabled (BlackBerry uses auto instead of default) <preference name="orientation" value="landscape" /> 2015 Parma

21 PhoneGap configuration Multiplatform preferences DisallowOverscroll (boolean, default is false): set to true if you don't want the interface to display any feedback when users scroll past the beginning or end of content <preference name="disallowoverscroll" value="true"/> Applies to Android and ios On ios, overscroll gestures cause content to bounce back to its original position On Android, they produce a more subtle glowing effect along the top or bottom edge of the content BackgroundColor sets the app's background color <preference name="backgroundcolor" value="0xff0000ff"/> applies to Android and BlackBerry it overrides CSS settings 2015 Parma

22 PhoneGap configuration iosspecific preferences Some preferences only apply to ios EnableViewportScale (boolean, default is false) set to true to allow the user to scale the viewport (i.e., zoom in or out the web view content) MediaPlaybackRequiresUserAction (boolean, default is false) set to true to prevent HTML5 videos or audios from playing automatically AllowInlineMediaPlayback (boolean, defaults to false) set to true to allow HTML5 media playback to use browsersupplied controls rather than native controls (for this to work, add the webkitplaysinline attribute to any <video> element) 2015 Parma

23 PhoneGap configuration iosspecific preferences BackupWebStorage (string) Set to cloud (default) to allow web storage data to backup via icloud Set to local to allow only local backups via itunes sync Set to none prevent web storage backups TopActivityIndicator (string): controls the appearance of the small spinning icon in the status bar valid values are whitelarge, white, and gray (default) KeyboardDisplayRequiresUserAction (boolean, default is true) Set to false to allow the keyboard to appear when firing focus on form inputs SuppressesIncrementalRendering (boolean, defaults to false) Set to true to wait until all content has been received before screen rendering happens 2015 Parma

24 PhoneGap configuration iosspecific preferences PaginationMode (string): valid values are unpaginated (default), lefttoright, toptobottom, bottomtotop, and righttoleft it determines whether content in the web view is broken up into pages that fill the view one screen at a time, or shown as one long scrolling view If set to a paginated form, the web view uses PageLength and GapBetweenPages to relayout its content GapBetweenPages (float, default is 0): the size of the gap, in points, between pages PageLength (float, default is 0): the size of each page in points based on the size of the viewport When PaginationMode is righttoleft or lefttoright, it represents the width of each page When PaginationMode is toptobottom or bottomtotop, it represents the height of each page 2015 Parma

25 PhoneGap configuration Androidspecific preferences Some preferences only apply to Android KeepRunning (boolean, default is true): determines whether the application stays running in the background even after a pause event fires Setting this to false will not kill the app after a pause event, it will only halt execution of code in the web view while the app is in the background LoadUrlTimeoutValue (number in milliseconds, default to 20000): the amount of time to wait before throwing a timeout error when loading a page SplashScreen (string, default is splash): the name of the splash screen image file minus its extension in the res/drawable directory SplashScreenDelay (milliseconds, default is 3000): the amount of time the splash screen image displays 2015 Parma

26 PhoneGap configuration Androidspecific preferences InAppBrowserStorageEnabled (boolean, default is true): controls whether pages opened within an InAppBrowser (a browser window provided by PhoneGap API) can access the same storage location as pages opened with the default browser LoadingDialog (string, default is null): displays a dialog with a specified title, message and a spinner when loading the first page of an application title and message must be separated by a comma LoadingPageDialog (string, default is null): the same as LoadingDialog, but for every page after the first one ErrorUrl (URL, default to null): if set, the app displays a specified page when an error occurs instead of the default error dialog ShowTitle (boolean, default is false): shows the title at the top of the screen LogLevel (string): sets the minimum log level through which log messages from your application will be filtered Valid values are ERROR (default), WARN, INFO, DEBUG and VERBOSE 2015 Parma

27 PhoneGap configuration features When using the plugin command to enable device APIs, the toplevel config.xml file is not modified The command modifies platformspecific config.xml files in platforms subdirectories (feature elements do not need to be added manually to them) If, instead, you are working directly in an SDK, such as Eclipse, and you are using the platformspecific config.xml files as a source, you have to manually add the feature tag to enable devicelevel APIs and external plugins For example, to specify the Device API for Android projects and for ios projects: <feature name="device"> <param name="androidpackage" value="org.apache.cordova.device.device" /> </feature> <feature name="device"> <param name="iospackage" value="cdvdevice" /> </feature> 2015 Parma

28 PhoneGap APIs PhoneGap provides APIs for the management of: Events Accelerometer Camera Contacts Location APIs provide methods through the navigator object which represents the native web view File system access File transfers Database management 2015 Parma

29 PhoneGap APIs Events Events are fired when something happens on the device The basic usage is as follows document.addeventlistener("eventname", oneventfired, false); function oneventfired () { } The first parameter is the event name The second parameter is the callback executed when the event fires The third parameter specifies if the event should be captured in the beginning (true) or in the end (false) 2015 Parma

30 PhoneGap APIs Events Common events ondeviceready fires when Cordova is fully loaded you always have to wait for this one before you can access the device s features! pause and resume fire when the app is put into or resumed from the background online and offline fire when the device connects to or disconnects from the internet batterycritical and batterylow fire when the battery level reaches a critical or low device dependent threshold batterystatus fires when the charge changes of 1% backbutton, searchbutton and menubutton fire when the user presses the Android back, search or menu buttons 2015 Parma

31 PhoneGap APIs Accelerometer To access the accelerometer, use CLI to add or remove the proper feature phonegap plugin add org.apache.cordova.devicemotion phonegap plugin rm org.apache.cordova.devicemotion Platformspecific settings automatically added: For Android, in res/xml/config.xml <feature name="accelerometer"> <param name="androidpackage" value="org.apache.cordova.devicemotion.accellistener" /> </feature> For ios, in the named application directory s config.xml <feature name="accelerometer"> <param name="iospackage" value="cdvaccelerometer" /> </feature> 2015 Parma

32 PhoneGap APIs Accelerometer The Acceleration object contains accelerometer data captured at a specific point in time The plugin provides the following methods to access such an object and use the read values accelerometer.getcurrentacceleration gets the current acceleration along the x, y, and z axes navigator.accelerometer.getcurrentacceleration(onsuccess, onerror); The first parameter is a function called when the data are available; the second is a function called when errors occur function onsuccess(acceleration) { alert('acceleration X: ' + acceleration.x + '\n' + 'Acceleration Y: ' + acceleration.y + '\n' + 'Acceleration Z: ' + acceleration.z + '\n' + 'Timestamp: ' + acceleration.timestamp + '\n' ); }; function onerror() { alert('an error occurred!'); }; 2015 Parma

33 PhoneGap APIs Accelerometer accelerometer.watchacceleration gets the acceleration at regular intervals accelerometer.clearwatch stops watching the Acceleration referenced by the parameter returned by watchacceleration method function onsuccess(acceleration) { alert('acceleration X: ' + acceleration.x + '\n' + 'Acceleration Y: ' + acceleration.y + '\n' + 'Acceleration Z: ' + acceleration.z + '\n' + 'Timestamp: ' + acceleration.timestamp + '\n' ); }; function onerror() { alert('an error occurred!'); }; function stopwatch() { if (watchid) { navigator.accelerometer.clearwatch(watchid); watchid = null; } } var options = { frequency: 3000 }; // Update every 3 seconds var watchid = navigator.accelerometer.watchacceleration(onsuccess, onerror, options); 2015 Parma

34 To access the camera, use CLI to add or remove the proper feature phonegap plugin add org.apache.cordova.camera phonegap plugin rm org.apache.cordova.camera Platformspecific settings automatically added: PhoneGap APIs Camera For Android: <! in app/res/xml/config.xml > <feature name="camera"> <param name="androidpackage" value="org.apache.cordova.camera.cameralauncher" /> </feature> <! in app/androidmanifest > <usespermission android:name="android.permission.write_external_storage" /> For ios, in the named application directory s config.xml <feature name="accelerometer"> <param name="iospackage" value="cdvaccelerometer" /> </feature> 2015 Parma

35 Università Degli Studi di Parma PhoneGap APIs Camera The Camera object provides access to the default device s camera application The plugin provides the following methods to access such an object camera.getpicure take a picture using the camera or retrieve it from the filesystem navigator.camera.getpicture( camerasuccess, cameraerror, [ cameraoptions ] ); The first param is a function called when the photo is taken; the second is a called when errors occur; the third is a list i n c l u d i n g t h e p i c t u r e q u a l i t y, t h e source (Camera.PictureSourceType.PHOTOLIBRARY/ SAVEDPHOTOALBUM/CAMERA), the possibility to edit the photo (allowedit: boolean), the destination type (destinationtype.data_url returns a base64encoded string; destinationtype.file_uri returns an URI to the photo), whether to save the photo (savetophotoalbum: boolean if false images are saved in a temp directory), the encoding type (Camera.EncodingType) and the size. <! Camera options > { quality : 75, destinationtype : Camera.DestinationType.DATA_URL, sourcetype : Camera.PictureSourceType.CAMERA, allowedit : true, encodingtype: Camera.EncodingType.JPEG, targetwidth: 100, targetheight: 100, popoveroptions: CameraPopoverOptions, savetophotoalbum: false }; camera.cleanup removes from temp directory the photos saved with savetophotoalbum set to false 2015 Parma

36 PhoneGap APIs Camera The example on the left takes a picture and returns a base64encoded image (a string) The example on the right takes a picture and returns an URI pointing to it Both set the image as the source for an img element Note that while the URI can be passed as src attribute (right), the base64encoded image must be first decoded by prepending data:image/jpeg;base64 to the image object (left) navigator.camera.getpicture(onsuccess, onfail, { quality: 50, destinationtype: Camera.DestinationType.DATA_URL }); function onsuccess(imagedata) { var image = document.getelementbyid('myimage'); image.src = "data:image/jpeg;base64" + imagedata; } function onfail(message) { alert("failed because: " + message); } navigator.camera.getpicture(onsuccess, onfail, { quality: 50, destinationtype: Camera.DestinationType.FILE_URI }); function onsuccess(imageuri) { var image = document.getelementbyid("myimage"); image.src = imageuri; } function onfail(message) { alert("failed because: " + message); } 2015 Parma

37 To access contacts, use CLI to add or remove the proper feature phonegap plugin add org.apache.cordova.contacts phonegap plugin rm org.apache.cordova.contacts Platformspecific settings automatically added: PhoneGap APIs Contacts For Android <! in app/res/xml/config.xml > <feature name="contacts"> <param name="androidpackage" value="org.apache.cordova.contacts.contactmanager" /> </feature> <! in app/androidmanifest > <usespermission android:name="android.permission.read_contacts" /> <usespermission android:name="android.permission.write_contacts" /> <usespermission android:name="android.permission.get_accounts" /> For ios, in the named application directory s config.xml <feature name="contacts"> <param name="iospackage" value="cdvcontacts" /> </feature> 2015 Parma

38 PhoneGap APIs Contacts The Contact object provides access to the device contacts database The plugin provides the following methods to access such an object contacts.create creates a contact var contact = navigator.contacts.create(properties); navigator.contacts.save(contact); The create method returns a Contact object but does not save it; in order to save it, call contact.save method. Properties is a list of contact data such as displayname (string), phonenumbers, ims (instant messages) and s (arrays of type ContactField), name (an array of type ContactName including the properties familyname, givenname, middlename, honorificprefix, ), note (a string), addresses (an array of ContactAddress type, including the properties streetaddress, locality, region, postalcode, country, ), var contact = navigator.contacts.create(); contact.displayname = "John"; contact.nickname = "Plumber"; // populate some fields var name = new ContactName(); name.givenname = "Jonathan"; name.familyname = "Doe"; contact.name = name; var address = new ContactAddress(); address.city = "New York"; Address.locality = "NY"; Address.postalCode = "12345"; Address.country = "US"; contact. address = address ; 2015 Parma

39 PhoneGap APIs Contacts Contacts.find queries the contacts database and returns a Contact object having the properties described in the previous slide Parameters are the list of properties returned by the research, the function called when the contacts array is retrieved, the function called if errors occur and a ContactFindOptions object used to filter results The example returns the displayed name, the name and the list of phone numbers of all users having Bob in any field function onsuccess(contacts) { for (var i = 0; i < contacts.length; i++) { console.log("display Name = " + contacts[i].displayname); } }; function onerror(contacterror) { alert('an error occurred!'); }; // find all contacts with 'Bob' in any name field var options = new ContactFindOptions(); options.filter = "Bob"; options.multiple = true; var fields = ["displayname", "name", "phonenumbers"]; navigator.contacts.find(fields, onsuccess, onerror, options); 2015 Parma

40 PhoneGap APIs Location To access user s location, use CLI to add or remove the proper feature phonegap plugin add org.apache.cordova.geolocation phonegap plugin rm org.apache.cordova.geolocation Platformspecific settings automatically added: For Android <! in app/res/xml/config.xml > <feature name="geolocation"> <param name="androidpackage" value="org.apache.cordova.geolocation.geobroker" /> </feature> <! in app/androidmanifest > <usespermission android:name="android.permission.access_coarse_location" /> <usespermission android:name="android.permission.access_fine_location" /> For ios, in the named application directory s config.xml <feature name="geolocation"> <param name="iospackage" value="cdvlocation" /> </feature> 2015 Parma

41 PhoneGap APIs Location The GeoLocation object provides access to location data based on the device's GPS sensor or on network signals The plugin provides the following methods to access such an object geolocation.getcurrentposition returns the device's current position as a Position object which includes several properties, such as latitude, longitude, speed, accuracy, var onsuccess = function(position) { alert('latitude: ' + position.coords.latitude + '\n' + 'Longitude: ' + position.coords.longitude + '\n' + 'Altitude: ' + position.coords.altitude + '\n' + 'Accuracy: ' + position.coords.accuracy + '\n' + 'Altitude Accuracy: ' + position.coords.altitudeaccuracy + '\n' + 'Heading: ' + position.coords.heading + '\n' + 'Speed: ' + position.coords.speed + '\n' + 'Timestamp: ' + position.timestamp + '\n' ); }; function onerror(error) { alert('code: ' + error.code + '\n' + 'message: ' + error.message + '\n' ); } navigator.geolocation.getcurrentposition(onsuccess, onerror); 2015 Parma

42 PhoneGap APIs Location geolocation.watchposition watches for changes to the device s location geolocation.clearwatch stops watching for changes to the location referenced by the parameter returned by watchposition method function onsuccess(position) { var element = document.getelementbyid('geolocation'); element.innerhtml = 'Latitude: ' + position.coords.latitude + ' Longitude: ' + position.coords.longitude + element.innerhtml; navigator.geolocation.clearwatch(watchid); } function onerror(error) { alert('code: + error.code + '\n' + 'message: ' + error.message + '\n'); } function stopwatch() { if (watchid) { navigator.geolocation.clearwatch(watchid); watchid = null; } } // Options: throw an error if no update is received every 30 seconds var watchid = navigator.geolocation.watchposition(onsuccess, onerror, { timeout: }); 2015 Parma

43 PhoneGap APIs File System To manage files, use CLI to add or remove the 2 proper plugins phonegap plugin add org.apache.cordova.file phonegap plugin add org.apache.cordova.filetransfer phonegap plugin rm org.apache.cordova.file phonegap plugin rm org.apache.cordova.filetransfer Platformspecific settings automatically added: For Android <! add in app/res/xml/config.xml > <feature name="file"> <param name="androidpackage" value="org.apache.cordova.file.fileutils" /> </feature> <feature name="filetransfer"> <param name="androidpackage" value="org.apache.cordova.filetransfer.filetransfer" /> </feature> <! add in app/androidmanifest > <usespermission android:name="android.permission.write_external_storage" /> For ios, in the named application directory s config.xml <feature name="file"> <param name="iospackage" value="cdvfile" /> </feature> <feature name="filetransfer"> <param name="iospackage" value="cdvfiletransfer" /> </feature> 2015 Parma

44 The File object allows to read, write and navigate file system hierarchies The steps are as follows (see the next slides for code examples) You need to get a reference to the filesystem window.requestfilesystem(localfilesystem.persistent, 0, onfilesystemsuccess, onfilesystemfail); the first parameter is the local filesystem type (PERSISTENT or TEMPORARY) the second parameter indicates how much storage space (bytes) the application expects to need requestfilesystem fails if the availability of the disk is smaller than size param the third and fourth parameters are functions called, respectively, if the reference is available, or in case errors occurred To read the list of files within a directory you need a DirectoryReader object obtained by invoking the createreader method To read a file you need a FileReader object PhoneGap APIs File plugin The getfile method allows to create or to look for a file 2015 Parma

45 PhoneGap APIs Read from a file var fs; window.requestfilesystem(localfilesystem.persistent, 0, onfilesystemsuccess, onfilesystemfail); function onfilesystemsuccess(filesystem) { fs = filesystem; var reader = fs.root.createreader(); // DirectoryReader reader.readentries(readersuccess, readerfail); } function readersuccess(entries) { // Get the first file in the directory fs.root.getfile(entries[0].name, null, gotfileentry, fail); } function gotfileentry(fileentry) { // Get a file object from the file reference fileentry.file(readafile, fail); } function readafile (file) { var reader = new FileReader(); // When the read process ends log on console the results // (i.e. the file content) reader.onloadend = function(evt) { console.log(evt.target.result); }; reader.readastext(file); } 1. Get a reference to the file system by calling requestfilesystem method 2. requestfilesystem executes the success callback onfilesystemsuccess, and passes it a reference to file system 3. onfilesystemsuccess creates a DirectoryReader object and calls its readentries method that allows getting the list of files in a directory (root is the root directory of the file system) 4. readentries executes the success callback readersuccess and passes to it the list of files in the directory 5. readersuccess gets a file from the list as a FileEntry object and executes gotfileentry by passing it a reference to the file FileEntry object provides name, fullpath, isfile (always true) and isdirectory (always false) properties 6. gotfileentry creates a file object from the reference by calling file method 7. file method executes the success callback readafile that creates a FileReader object and calls its method readastext by passing to it the file 2015 Parma

46 PhoneGap APIs Write to a file window.requestfilesystem(localfilesystem.persistent, 0, gotfs, fail); function gotfs(filesystem) { filesystem.root.getfile("readme.txt", null, gotfileentry, fail); } function gotfileentry(fileentry) { fileentry.createwriter(gotfilewriter, fail); } function gotfilewriter(writer) { writer.write("some sample text"); // the file content is now 'some sample text' writer.truncate(11); // the file content is now 'some sample' writer.seek(4); // the file content is still 'some sample', // but the file pointer is after the 'e' in 'some' } function fail(error) { console.log(error.code); } To write to a file, you need a FileWriter object which provides the following methods: write(string s) to write s in the file truncate(int i) which deletes the characters after the ith of the file seek(int i) which moves the cursor to the ith position in the text 2015 Parma

47 PhoneGap APIs FileTransfer plugin To transfer a file from/to a remote server, you need a FileTransfer object which provides the following methods: download requires the URL of the file to download, the path in the local filesystem where the file will be saved, a success function and an error function upload requires an URI to the file to be uploaded, the URL of the remote server that will receive it, a success function, an error function and a list of options (e.g., file name, mime type, ) navigator.camera.getpicture( uploadphoto, // Success callback function(message) { // Error callback alert('get picture failed'); }, { // Camera parameters quality: 50, destinationtype: navigator.camera.destinationtype.file_uri, sourcetype: navigator.camera.picturesourcetype.photolibrary } ); function uploadphoto(imageuri) { var options = new FileUploadOptions(); options.filename = imageuri.substr(imageuri.lastindexof('/') + 1); options.mimetype = "image/jpeg"; var ft = new FileTransfer(); ft.upload(imageuri, " success, error, options); ft.download(" path + "file.png", success, error); } The example takes a picture (getpicture method) and executes, as a success callback, uploadphoto which uploads such a photo to a server and downloads a file from the same server 2015 Parma

48 PhoneGap APIs FileTransfer plugin The download function s second parameter is the path to the local filesystem There is a difference between ios and Android so, to get its value, you can create a dummy file, get its path and delete it var spath; // local filesystem path window.requestfilesystem(localfilesystem.persistent, 0, onfilesystemsuccess, onfilesystemfail); function onfilesystemsuccess(filesystem) { fs.root.getfile( "dummy.html", {create: true, exclusive: false}, // Create a file if it does not exist function gotfileentry(fileentry) { // Success callback (its param is a reference to the file) // get the path of the file (PATH/dummy.html) and remove the dummy.html string from it spath = fileentry.fullpath.replace("dummy.html", ""); fileentry.remove(onfileremovalsuccess, onfileremovalfail); } ); } 2015 Parma

49 PhoneGap APIs Database management PhoneGap uses SQLite to manage databases on mobile devices To open a database, or create one if it does not exist, use the opendatabase method which takes as parameters the name of the database, its version, its display name and its expected size If the database exists, or after it has been created, you can check for the existence of a table and query it using the transaction method its parameters are the method to be executed to query the database, an error callback and a success callback The querying method usually calls once or more times the executesql method, which takes as parameter a string representing the query to execute Performing a SELECT query returns a ResultSet object which provides the ResultSetList property including the records obtained by the query 2015 Parma

50 PhoneGap APIs Database management var db = window.opendatabase("database", "1.0", "PhoneGap Demo", ); db.transaction(populatedb, errorcb, successcb); function populatedb(tx) { tx.executesql('create TABLE IF NOT EXISTS DEMO (id unique, data)'); tx.executesql('insert INTO DEMO (id, data) VALUES (1, "First row")'); tx.executesql('insert INTO DEMO (id, data) VALUES (2, "Second row")'); } function successcb(tx) { db.transaction(selectquery, errorcb); } function selectquery(tx) { tx.executesql('select * FROM DEMO', [], onselectsuccess, errorcb); } function onselectsuccess(tx, results) { var len = results.rows.length; for (var i = 0; i < len; i++) { console.log(results.rows.item(i).id) + " " + results.rows.item(i).data; } } function errorcb(tx, err) { alert("error processing SQL: " + err); } transaction method s first param populatedb is the function to be executed to query the database. Its argument is the transaction itself (transactions represent units of work performed on a database). If populatedb has success, transaction calls successcb, which executes a new transaction described by selectquery. The latter executes a SELECT query and, in case of success, calls onselectsuccess method which browses the result set. Note that executesql can take 1 to 4 params. The second is an array of values used by some queries, e.g.: transaction.executesql("update people set shirt=? where name=?;",[ shirt, name ]); The 2? are replaced with the array values 2015 Parma

51 Università Degli Studi di Parma PhoneGap APIs Notifications To display notifications and use vibration, use CLI to add or remove the proper features phonegap plugin add org.apache.cordova.plugindialogs phonegap plugin rm org.apache.cordova.plugindialogs phonegap plugin add org.apache.cordova.pluginvibration phonegap plugin rm org.apache.cordova.pluginvibration Platformspecific settings automatically added: For Android: <! in app/res/xml/config.xml > <feature name="notification"> <param name="androidpackage" value="org.apache.cordova.dialogs.notification" /> </feature> <feature name="vibration"> <param name="androidpackage" value="org.apache.cordova.vibration.vibration" /> </feature> <! in app/androidmanifest > <usespermission android:name="android.permission.vibrate" /> For ios, in the named application directory s config.xml <feature name="notification"> <param name="iospackage" value="cdvnotification" /> </feature> 2015 Parma

52 Università Degli Studi di Parma PhoneGap APIs Notifications <!DOCTYPE html> <html> <head> <title>notification Example</title> <script type="text/javascript" charset="utf8" src="cordova.js"></script> <script type="text/javascript" charset="utf8"> document.addeventlistener("deviceready", ondeviceready, false); function ondeviceready() {} // process the confirmation dialog result function onconfirm(buttonindex) { alert('you selected button ' + buttonindex); } // Show a custom confirmation dialog function showconfirm() { navigator.notification.confirm( 'Message', onconfirm, // callback to invoke with index of button pressed 'Game Over', // title ['Restart','Exit'] // buttonlabels ); } </script> </head> <body> <p><a href="#" onclick="showconfirm(); return false;">show Confirm</a></p> </body> </html> The callback executed by confirm method takes as parameter the index of the button the user clicked. If your dialog includes a single button, the fourth param of confirm method can be the string representing its label instead than an array Parma