Defining applications (config.xml) - nth-iteration/savvy GitHub Wiki
Savvy apps are defined in a single file, config.xml
, in the project root directory. This file is an extension of the W3C's Packaged Web Apps standard and an extension of the config.xml file used by Apache Cordova and Adobe PhoneGap.
Each config.xml
file contains a root <widget>
element. This should contain an id
(in reverse domain name notation) and version
(in semantic version format) for the application as attributes.
The <name>
, <description>
, <author>
and <license>
child tags of <widget>
are also recommended. These follow the W3C's Packaged Web Apps, the same specification as for Cordova and PhoneGap applications.
A recommended non-standard attribute to add to the root <widget>
element is savvy:theme="sparrow"
this sets the (optional) Savvy CSS theme to apply to HTML in the application. For more information on themes in Savvy, see [Styling Savvy applications](Styling Savvy applications)
The outline of a basic config.xml
is as follows:
<?xml version="1.0" encoding="UTF-8" ?>
<widget xmlns = "http://www.w3.org/ns/widgets"
xmlns:savvy = "https://savvy.nth-iteration.ie/ns/1.0"
id="com.example.savvy" version="1.0.0" savvy:theme="sparrow">
<name>Savvy Example</name>
<description>
An example Savvy application.
</description>
<author email="[email protected]" href="http://www.example.com">
John Smith
</author>
...
</widget>
Savvy then extends the format by allowing you to define a deck of cards that make up the application.
A single card in a deck described in XML as follows:
<savvy:deck>
<card id="Home" title="Welcome" default="yes">
<html>html/home.html</html>
<css>css/home.css</css>
<js>js/home.js</js>
</card>
...
</savvy:deck>
Each <card>
must have an id
attribute. The value of the id
attribute must be a) be a valid JavaScript identifier; b) be unique; and c) must not conflict with any object on the JavaScript window
object. Each <card>
should have a title
attribute.
A <card>
node may contains any number of <html>
, <css>
and <js>
nodes. These nodes define the HTML, CSS and JavaScript snippets that are included in that card.
The text content of <html>
, <css>
and <js>
nodes must be a URL path to a HTML, CSS or JavaScript snippet. These paths may be relative from the root directory of the Savvy project (e.g. html/home.html
) or absolute (e.g. http://fonts.googleapis.com/css?family=Jolly+Lodger
).
The <savvy:deck>
node may contain any number of <card>
nodes. One of these must have a default
attribute with a value of yes
. This will be the default card for the application and will be the first card displayed when the application loads.
The HTML, CSS, JSON and JavaScript defined in a card is scoped to that card and is unavailable from other cards. This allows you to develop individual cards without worrying about how styling one card will affect others or if variables used in JavaScript in one context will conflict with JavaScript elsewhere.
However, as well as HTML, CSS and JavaScript used by individual cards, Savvy apps may contain "global" HTML, CSS and JavaScript. Global HTML is appended to the body of the HTML document and CSS is unscoped.
Global JavaScript is run in the context of the JavaScript window
object and is accessible by all other scripts. In particular, it is useful to link JavaScript libraries in this way.
Global <html>
, <css>
and <js>
nodes are added as children of the <savvy:deck>
, as follows:
<savvy:deck>
<html>html/global.html</html>
<css>css/styles.css</css>
<js>js/script.js</js>
...
</savvy:deck>
Any number of HTML, CSS and JavaScript files can be linked in this way.
Two unique types of "cards" are <header>
and <footer>
nodes. These child nodes of the <savvy:deck>
node append HTML snippets to a header
and footer
child of the HTML document body. By default, these are styled to appear at the top and bottom of the application screen and remain fixed when a user navigates between screens.
<savvy:deck>
...
<header>
<html>html/header.html</html>
<css>css/header.css</css>
<js>js/header.js</js>
</header>
<footer>
<html>html/footer.html</html>
<css>css/footer.css</css>
<js>js/footer.js</js>
</footer>
...
</savvy:deck>
For more information on the headers and footers in Savvy, see [Styling header and footer elements](Styling header and footer elements).
config.xml
extends the config.xml
file used by Apache Cordova and Adobe PhoneGap to create hybrid applications for mobile and tablet devices.
For more information on config.xml
for Apache Cordova or Adobe PhoneGap see:
See also [Building hybrid apps with Savvy](Building hybrid apps with Savvy)