Permalink
Browse files

Port over rest of existing topics from xml -> markdown.

  • Loading branch information...
joshthecoder committed Apr 29, 2010
1 parent fedb376 commit c480ad57ce733998072c9976c2f47fb739a91ace
Showing with 567 additions and 2 deletions.
  1. +123 −0 Topics/application.md
  2. +7 −0 Topics/basics.md
  3. +97 −0 Topics/database.md
  4. +171 −0 Topics/menus.md
  5. +44 −0 Topics/notification.md
  6. +123 −0 Topics/windows.md
  7. +2 −2 tiapp.xml
View
@@ -0,0 +1,123 @@
+Application
+===========
+##Useful methods
+
+The API module also contains information about the currently-running Titanium
+application, which may be retrieved via <tt>Titanium.API.getApplication</tt>.
+The <tt>Application</tt> object that is returned by this method has a multitude of
+[useful properties](href="http://developer.appcelerator.com/apidoc/desktop/1.0/Titanium.API.Application.html").
+
+ :::javascript
+ var app = Titanium.API.application;
+ alert(app.getDataPath());
+ alert(app.getGUid());
+
+The App module also contains some very useful API points for dealing
+with the currently-running application. In particular you may wan to
+convert an <tt>app://</tt> URL into a path.
+
+ :::javascript
+ // The two alerts should be the same.
+ alert(Titanium.App.appURLToPath("app://images/kitten.png"));
+ alert(Titanium.Filesystem.getFile(Titanium.API.application.resourcesPath,
+ "images", "kitten.png"));
+
+One of the main benefits of the App module though is that it can
+return values from the <tt>tiapp.xml</tt> file. This might be useful for
+displaying the application version to the user or presenting a link to
+your URL.
+
+ :::javascript
+ alert("Welcome to " + Titanium.App.getName() +
+ " " + Titanium.App.getVersion());
+
+##Application properties
+
+Application properties provide a light-weight alternative to HTML5
+databases or the Titanium Database module. They come in two varieties:
+system properties and user properties. System properties are read-only
+properties that are defined via the <tt>tiapp.xml</tt> file, while user properties
+can be stored at any file path.
+
+###System properties
+
+In the KitchenSink <tt>tiapp.xml</tt>, the following properties are defined
+as children of the `<ti:app>` node:
+
+ :::xml
+ <property name="myString" type="string">I am a String</property>
+ <property name="myDouble" type="double">1.23</property>
+ <property name="myBool" type="boolean">true</property>
+ <property name="myInt" type="int">1</property>
+ <property name="myList" type="list">1,2,3</property>
+ <property name="myDefaultString">I am a default string</property>
+
+It is possible to access these properties by getting an instance of
+the system properties object:
+
+ :::javascript
+ var properties = Titanium.App.getSystemProperties();
+ alert(properties.getString("myString"));
+ alert(properties.getInt("myInt"));
+
+System properties are read-only, because an application may not have write
+access to it's installation directory (where <tt>tiapp.xml</tt> resides). To
+store properties, it's recommended that you write a user properties file to the
+application data directory.
+
+###User properties
+
+User properties have the same interface as system properties, but can be stored
+in any file on the filesystem. Generally speaking, it's best to store these in
+in the application data directory, which is a per-user are to store application
+files. On Linux this is in <tt>~/.titanium/appdata/</tt>, on OS X,
+<tt>~/Library/Application Support/Titanium/appdata</tt> and on Windows in
+<tt>%appdata%/Titanium/appdata</tt>.
+
+Here is an example of reading and writing to a user properties file:
+
+ :::javascript
+ var file = Titanium.Filesystem.getFile(
+ Titanium.API.application.dataPath, "demo.properties");
+
+ // Load the file if it exists.
+ var properties = null;
+ if (file.exists())
+ properties = Titanium.App.loadProperties(file);
+
+ // If the file doesn't exist, yet just create a new properties object.
+ if (properties === null)
+ properties = Titanium.App.createProperties({
+ val1: true,
+ val2: 1.1,
+ val3: ['a', 'b', 'c'],
+ val4: "123"
+ });
+
+ // Update the properties object and save it.
+ alert(properties.getString('val4'));
+ properties.setString('val4', '321');
+ properties.saveTo(file);
+
+##Exiting and restarting
+
+It is possible to exit and restart your application. This is useful
+for creating a custom exit button. The application will also exit when
+the last top-level window closes. It is alos possible to prevent your
+application from exiting by listening for the <tt>EXIT</tt> event.
+One complication with this approach is that the <tt>EXIT</tt> event is
+fired after the last window closes, so you might need to recreate the
+main window. A better approach is to simply catch <tt>CLOSE</tt> events.
+
+ :::javascript
+ // Exit KitchenSink
+ Titanium.API.addEventListener(Titanium.EXIT, function(event)
+ {
+ if (!confirm("Are you sure you want to exit?"))
+ event.preventDefault();
+ });
+ Titanium.App.exit();
+
+ // Restart KitchenSink
+ Titanium.App.restart();
+
View
@@ -7,6 +7,7 @@ is an object shared between all JavaScript contexts. Each frame, including
the top-level frame of each window, has its own JavaScript context. This
makes sharing data between frames a snap:
+ :::javascript
Titanium.DataDump = {}
Titanium.DataDump.value = "foo";
alert(Titanium.DataDump.value);
@@ -19,19 +20,22 @@ Almost all instantiated objects in Titanium are accessor-objects. This means
that properties can be accessed and modified in two styles. For example, take
this use use of *API.Application.getName()*:
+ :::javascript
alert(Titanium.API.getApplication().getName());
alert(Titanium.API.getApplication().name);
alert(Titanium.API.application.name);
Likewise a similar method can be used for modifiers:
+ :::javascript
Titanium.UI.currentWindow.setTitle("Title1");
Titanium.UI.currentWindow.title = "Title2";
##Logging
Titanium provides an API for logging. There are two supported methods.
+ :::javascript
Titanium.API.critical("critical message");
Titanium.API.debug("debug message");
Titanium.API.error("error message");
@@ -57,6 +61,7 @@ The Web Inspector only logs WARN messages or higher.
If you want to control the level of logging that is displayed via stdout,
you can set the logging level.
+ :::javascript
alert("The current log level is: " + Titanium.API.getLogLevel());
Titanium.API.setLogLevel(Titanium.API.FATAL);
alert("The current log level is: " + Titanium.API.getLogLevel());
@@ -68,6 +73,7 @@ Titanium allows you to access environment variables via the
by this function is live representation of all environment variables,
which allows you to query and update the environment easily.
+ :::javascript
var env = Titanium.API.getEnvironment();
alert(env['PATH']);
@@ -83,6 +89,7 @@ may need to inercept all events after they've bubbled up to the
top-level object. This is possible by installing an event handler
on the Titanium object.
+ :::javascript
Titanium.API.addEventListener("CustomEvent", function(event)
{
alert("Top-level got " + event.type + " event!");
View
@@ -0,0 +1,97 @@
+Database
+========
+##Introduction
+
+There are two ways to use databases in Titanium: HTML 5 databases
+and the database API. In some cases you access the same database
+file with both APIs as well. Currently both APIs use SQLite backends.
+
+##Opening a Database
+
+There are two ways to open Titanim databases, <tt>Titanium.Database.open</tt>
+and <tt>Titanium.Database.openFile</tt>. <tt>open</tt> will create (if necessarY0
+and open a database in the same directory and schema as WebKit HTML 5 databases.
+Use this method if you'd like to use a single database with both APIs.
+
+ :::javascript
+ // Create a WebKit-compatible database given, the database name.
+ var db = Titanium.Database.open('mydatabase');
+
+You may also create a database using <tt>Titanium.Database.openFile</tt>
+which can be given a file path or <tt>Titanium.Filesystem.File</tt> object.
+If the database file does not exist, the method will create it and open it.
+
+ :::javascript
+ var db = Titanium.Database.openFile(Titanium.Filesystem.getFile(
+ Titanium.Filesystem.getApplicationDataDirectory(), 'mydatabase.db'));
+
+Note: It's recommended that you store all data in the application data
+directory and not the application Resources or contents directory, as those
+may not be writeable.
+
+##Simple Queries
+
+Once a database is open you may execute simple queries on it. For instance,
+to create a table:
+
+ :::javascript
+ var db = Titanium.Database.openFile(Titanium.Filesystem.getFile(
+ Titanium.Filesystem.getApplicationDataDirectory(), 'mydatabase.db'));
+ db.execute("CREATE TABLE IF NOT EXISTS test(id INTEGER, name TEXT)");
+
+Note: Be sure your query is SQLite-compatible! SQLite has different data
+types than MySQL, check them out [here](http://www.sqlite.org/datatype3.html).
+
+Find a way to detect databases that already exist.
+
+Inserting and retrieving data works in a very similar way:
+
+ :::javascript
+ var db = Titanium.Database.openFile(Titanium.Filesystem.getFile(
+ Titanium.Filesystem.getApplicationDataDirectory(), 'mydatabase.db'));
+
+ db.execute("CREATE TABLE IF NOT EXISTS test(id INTEGER, name TEXT)");
+ db.execute("INSERT INTO test VALUES(123, 'a')");
+
+ var resultSet = db.execute("SELECT * FROM test");
+ alert("Found " + resultSet.rowCount() + " rows");
+ while (resultSet.isValidRow())
+ {
+ var text = "";
+ for (var i = 0; i &lt; resultSet.fieldCount(); i++)
+ text += resultSet.fieldName(i) + ":"
+ + resultSet.field(i) + " ";
+ alert(text);
+ resultSet.next();
+ }
+
+##Advanced Queries
+
+You should never used unescaped input in SQL queries. In these situations
+Titanium provides a query template mechanism:
+
+ :::javascript
+ var db = Titanium.Database.openFile(Titanium.Filesystem.getFile(
+ Titanium.Filesystem.getApplicationDataDirectory(), 'mydatabase.db'));
+
+ var id = prompt("Enter entry id");
+ if (!id)
+ return;
+ var value = prompt("Enter entry value");
+ if (!value)
+ return;
+
+ db.execute("CREATE TABLE IF NOT EXISTS test(id INTEGER, name TEXT)");
+ db.execute("INSERT INTO test VALUES(?, ?)", id, value);
+
+ var resultSet = db.execute("SELECT * FROM test");
+ alert("Found " + resultSet.rowCount() + " rows");
+ while (resultSet.isValidRow())
+ {
+ var text = "";
+ for (var i = 0; i &lt; resultSet.fieldCount(); i++)
+ text += resultSet.fieldName(i) + ":"
+ + resultSet.field(i) + " ";
+ alert(text);
+ resultSet.next();
+ }
Oops, something went wrong.

0 comments on commit c480ad5

Please sign in to comment.