Web App Toolkit

The Web App Toolkit is a plugin for creating Windows, Android and iOS apps based on existing web content. It depends on the Hosted Web App Plugin. Used in the right way, it can facilitate the creation of compelling extensions to your web content for users across platforms.

Getting Started

The following tutorial requires you to install the Cordova Command-Line Inteface.

Hosting a Web Application

The plugin leverages the functionalimaty from the Hosted WebApp Plugin. The following steps describe how you can create and configure a sample application and use it with the Web App Toolkit.

1. Create a new Cordova application.
   cordova create sampleapp yourdomain.sampleapp SampleHostedApp

2. Go to the sampleapp directory created by the previous command.

3. Download or create a W3C manifest describing the website to be hosted by the Cordova application and copy this file to its root folder, alongside config.xml. If necessary, rename the file as manifest.json.

   Note: You can find a sample manifest file at the start of this document.

4. Add the Web App Toolkit plugin to the project.
   cordova plugin add cordova-plugin-webapptoolkit

5. Add one or more platforms, for example, to support Android.
   cordova platform add android

6. Build the application.
   cordova build

Known Issues [Windows only]

1. The cordova build command will fail on a machine that does not have the SDK and tools for Windows 8.1 because WinJS 2 is not installed. For the plugin to work correctly, and if you are on Windows 10, before running the build command, open the Visual Studio solution and remove the references to WinJS 2 in the Windows 8.1 and Windows Phone 8.1 projects. The cordova build command should succeed after this.

2. Uninstalling the plugin will not remove the WinJS files that were added during the installation process.

Manual steps required [Windows only]

In order to make the project work there are a few things that need to be taken care of:

1. Changing the TargetDeviceFamily's MaxVersionTested and MinVersion values to 10.0.00000.0 in the appxmanifest.

Before you submit your app [Windows only]

Make sure you replace the reference to Windows.ApplicationModel.Store.CurrentAppSimulator with Windows.Applicationmodel.Store.CurrentApp, which is located in WATShare.js

Features

The following section shows examples of how you can enable the plugin's features in the manifest.json file.

The following table describes the supported features for each of the platforms.

| | Windows | iOS | Android | |:--------------|:-----------:|:-----------:|:-----------:| |wat_share | yes | | | |wat_customScript| yes | yes | yes | |wat_appBar | yes | | | |wat_navBar | yes | | | |wat_livetile | yes | | | |wat_redirects | yes | yes | yes | |wat_settings | yes | | | |wat_styles | yes | yes | yes | |wat_header | yes | | | |wat_secondaryPin| yes | | | |wat_navigation | yes | yes | |

wat_share

This controls the use of the share charm within the application.

| Option | Description |:-----------|:---------------| | enabled | Toggles the share charm functionality on or off (true/false) | showButton | Toggles visibility of a Share button on the app bar (true/false) | buttonText | Text used for the Share app bar button if it is enabled | buttonSection | This sets the sharebutton into a particular section of the app bar (if you have sections set up) the default is primary http://msdn.microsoft.com/en-us/library/windows/apps/Hh700497.aspx | title | Defines the title passed into the share charm | url | Defines a url that is shared via the share contract. You can use {currentURL} to share the current URL of the webview. | screenshot | Enables the sharing of a screenshot (true/false) | message | Defines a message for the share contract contents. You can use {currentURL} to reference the current url or {url} to reference the base url.

Example

wat_customScript

An array of custom script files stored within the app package that are injected into the DOM. Paths are relative to the root of the app package.

Example

wat_appBar

This controls the application bar at the bottom of the screen.

|Option|Description| |:---------|:--------------| | enabled | Toggles the app bar visibility (true/false) | buttons | An array of objects, each of which represent a button within the application bar. Each object has three parameters: |      label | the text for the button. Leave this blank to omit the text |      icon | the icon for the button. A list of available icons is at dev.windows.com. Leave this blank to omit the icon |      action | The action for the button. This defines either the url location that the button links to or it can be set to a eval to executes the javascript defined in the 'data' field |      data | Javascript that gets executed if the action is set to 'eval'

Example

wat_navBar

This controls the navigation bar at the top of the screen.

|Option|Description | |----------|----------------| | enabled | Toggles the navigation bar visibility (true/false) | maxRows | Sets the maximum number of rows that are used to display buttons before the nav bar starts paging | buttons | An array of objects, each of which represent a button within the navigation bar.Each object has the following parameters: |      label | The text for the button. Leave this blank to omit the text |      icon | The icon for the button. A list of available icons is at dev.windows.com. Leave this blank to omit the icon |      action | The action for the button. This defines either the url location that the button links to or a special keyword. back Takes the app back to the most recent page. home Takes the app to the base url. nested Allows the inclusion of children node. eval Executes the javascript defined in the 'data' field |      data | Javascript that gets executed if the action is set to 'eval' |      children | An array of nodes that are shown beneath the parent node. Children nodes take the same format as parent nodes. Only used if the parent node's action is set to 'nested'.

Example

wat_livetile

This controls the applications live tile notifications on the users start screen.

|Option|Description| |----------|---------------| | enabled | Toggles the live tile functionality (true/false) | periodicUpdate | Number which defines how often the tile updates based on the PeriodicUpdateRecurrence enumeration. Valid values are 0, 1, 2, 3 or 4. 0 is most frequent (half an hour), 4 is the least frequent (daily) | enableQueue | Toggles multiple live tile updates on or off. When set to true the live tile on the start screen will cycle through muliple tile updates either via the RSS feed or multple push notification updates. (true/false) | tilePollFeed | The url for the RSS feed that will drive the live tile updates. This can be any RSS feed.

Example

wat_redirects

Enables you to specify which urls remain inside the app and which ones open in the browser. This feature is useful for those users who are already using the Web App Template and want to keep their configuration file unmodified.

|Option | Description | |-----------|-----------------| | enabled | Toggles the redirect functionality (true/false) | enableCaptureWindowOpen | This captures popups (new windows) think about this as a way to catch facebook logins and things like that that need to happen in the app, once this value is enabled, you can control this on each of the redirects (true/false) | refreshOnModalClose | If you need to have the app refresh when this model closes, (like in a login scenario) set this to true (true/false) | rules | An array of objects, each of which represent a re-direction. Each object has three parameters: |      pattern | The pattern that the rule should match to take effect |      action | The action associated with this operation, this can be one of four options showMessage, popout, redirect or modal. |      url | The url to redirect to if action is set to url |      message | The message that is used if the action is set to showMessage |      hideCloseButton | Hides close button on modal windows |      closeOnMatch | A url that when it is loaded, it forces the modal to close (usefull for login scenario)

Example

wat_settings

This controls the use of the setting items within the application bar.

|Option| Description| |----------|----------------| | enabled | Toggles the settings functionality (true/false) | privacyUrl | Defines a url link to the application's privacy policy. A privacy policy is typically required for app to pass store certification. | items | Defines an array of item that are used in the settings charm | title | Defines the text for the settings item | page | Defines the url for the settings item | loadInApp | Defines whether the url is opened in the app or the browser (true/false)

Example

wat_styles

This allows the user to configure the application's view of their website.

|Option|Description| |----------|---------------| |suppressTouchAction| (Windows only) Toggles whether the top level touch events are surpressed or not. This is quite helpful with SPA where you don’t want to be able to see scrolling or ruberbanding of the page (true/false) |hiddenElements| An array of strings that reference HTML elements. This enables you to hide any website HTML elements from your application. This is ideal for removing any unwanted top navigation, footers etc from the application view |backButton| (Windows only) An array of style rules that are applied to the back button |wrapperCssFile|(Windows only) A path to the /css/wrapper-styles.css file. This file applies styles to the native aspects of the app such as app bars, back button etc. Generally speaking you should not need to change this |customCssFile| A path to the /css/injected-styles.css file. This file injects styles into the web view control and can overide CSS within the website itself. Generally speaking you should not need to change this |customCssString| This enables you to embed CSS styles which get inserted over the existing styles on your website. This is great for adjusting the style of the site when it is presented as an application. This can be used as an alterntive to the injected-styles.css.

Example

wat_header

This enables use of a native page header within the application. This can make the app appear less like a website when use in conjunction with hiding the website's header elements.

|Option|Description| |----------|---------------| |enabled| Toggles the header on or off (true/false) |backgroundColor| A hex coe that defines tha background colour for the header |logo| The path to an image that is used as a logo in the header. This is only used if the title is disabled |title| Settings that control the title text that is used in the header. The text is taken from the Title metadata of the page that is being displayed |enabled| Toggles the title text functionality (true/false) |displayOnHomePage| Toggles whether to display the title text on the home page. If false, the title text will still be applied to all other pages (true/false)

Example

wat_secondaryPin

This option sets the secondary pin functionality in the app bar.

|Option|Description |----------|---------------| |enabled| Toggles the secondary pin functionality (true/false) |buttonText| Text that is used on the pin button |tileTextTheme| The visual theme for the tile (light/dark) |buttonSection| This sets the sharebutton into a particular section of the app bar (if you have sections set up) the default is primary http://msdn.microsoft.com/en-us/library/windows/apps/Hh700497.aspx |squareImage| A path to a square image that is used for secondary tiles |wideImage| A path to a wide image that is used for secondary tiles |customImageSelector| A CSS selector that specifies the img element corresponding to the image that will be used for the tile.

Example

wat_navigation

Controls options on how users navigate around the app.

|Option|Description |----------|---------------| |hideOnPageBackButton| This toggles visibility of the back button on the main canvas across the entire application (true/false) |hideBackButtonOnMatch| This toggles visibility of the back button on specific pages. An array of objects, each of which is a url on which back button will be hidden. You can use {baseUrl} to signify the url defined in 'start_url'

Example