New Tutorial

doc/tutorial/template.md

@@ -30,132 +30,72 @@ as an iOS project.
 
 ** Creating tables
 
-First, let's create a table with 3 columns using the typed table interface:
+First, let's create a table with 2 columns using the typed table interface:
 
 @@example create_table @@
 
-The <code>REALM_TABLE_3</code> is a macro which creates the appropriate Objective C classes
-including <code>PeopleTable</code>.
+The <code>REALM_TABLE_2</code> is a macro which creates the appropriate Objective C classes
+including <code>RLMDemoTable</code>.
 
-The above code instantiates a Realm table with 3 typed columns called: <code>Name</code>, <code>Age</code>,
-and <code>Hired</code>.
+The above code creates a Realm table type with 2 typed columns called 
+<code>title</code> and <code>checked</code>.
 
-We add rows to the end of the table using the method <code>addRow</code>.
-The method <code>addRow</code> allows you to add a row
-using object literals either by using an array or a dictionary.
-The order of the elements in the array must be the same as the order in
-which we created the table columns with <code>REALM_TABLE_3()</code>
-while order is not important when you add a row using a dictionary.
+There are really just two types of operations you can do in Realm: read and write. 
+All these operations need to be done within a context. Even though Realm is built to 
+be super fast however you use it, we can still gain a performance boost by reusing 
+contexts as much as possible. A good way to reuse contexts is to set them as properties: 
+a smart context for reading and a regular context for writing.
 
-The code below appends 5 rows to our table:
+@@example setup_contexts @@
 
-@@example insert_rows @@
+Using `RLMContext`, tables can be accessed simultaneously by 
+multiple threads, processes, or applications.
 
-Since tables are ordered, you can also insert rows at specific row positions:
+Creating a table can be done using a write block on our <code>writeContext</code>:
 
-@@example insert_at_index @@
-
-To get the number of row in of your table (number of rows) you can use the
-<code>rowCount</code> property.
-
-@@example number_of_rows @@
-
-** Working with individual rows
-
-To access the individual rows of our table, we use square brackets
-(<code>[]</code>) or the <code>rowAtIndex</code> method. In general a row is
-represented as a special object. In the
-general a row an instance of the <code>RLMRow</code> class. In the
-case of the typed table, the class is named <code>PeopleTableRow</code>.
+@@example create_table @@
 
-@@example accessing_rows @@
+Calling <code>isEmpty</code> on the <code>RLMTransaction</code> is a good way to 
+make sure the table is only created once.
 
-You can easily access the first and last row like this:
+When using smart contexts as is the case here, it's important to observe 
+<code>RLMContextDidChangeNotification</code> to know when tables have been updated:
 
-@@example last_row @@
+@@example: setup_notifications @@
 
-It is possible update an entire row using object literals:
+Adding a row to a table must be done within a write block on a regular context:
 
-@@example updating_entire_row @@
+@@example: add_row @@
 
-Deleting a specific row can be done with <code>removeRowAtIndex</code>:
+The code above highlights the two main ways to add a new row: using an array and 
+using a dictionary. It's important to preserve the order of columns when adding 
+a row with an array, but not when adding with a dictionary.
 
-@@example deleting_row @@
+Deleting rows must be done within a write block on a regular context:
 
-Using the <code>for ... in</code> construct, you can
-easily iterate over every row in a table:
+@@example delete_row @@
 
+It's also possible to iterate over a table's rows using a <code>for...in</code> loop:
 
 @@example iteration @@
 
-Which will output the following:
-
-<div class="code">
-<pre>
-John is 20 years old.
-Mary is 21 years old.
-Lars is 32 years old.
-Eric is 50 years old.
-Anni is 43 years old.
-</pre>
-</div>
-
-** Queries
-
-Queries can be performed through query objects. Advanced
-queries can involve more than one column and when the query is
-defined once different operations can be performed with it. A query
-is instantiated with the <code>where</code> method. In the general case, a
-query object is an instance of the <code>RLMQuery</code> class but for
-the typed table <code>PeopleTable</code> class, the class is named
-<code>PeopleTableQuery</code>.
-
-The query class has methods to perform operations relevant for the
-particular column type. All comparison operations return the query
-object itself, so they can be chained.
-
-You can perform some operations with the query itself, or use the
-<code>findAll</code> method to get a view of all matching rows.
-
-The code below illustrates the simplicity and expressiveness of the
-query interface (albeit with a somewhat hypothetical query):
-
-@@example advanced_search @@
-
-Note that the result is a live table view, which allows you to
-directly access and modify the values in the original table.
-
-You can do much more advanced queries with parenthesis and <i>or</i>
-operators etc. Please see the reference manual for details.
-
-** Transactions
-
-You can create your tables within a context, and use such a context to serialize
-your data to/from disk. The context is implemented
-by the class <code>RLMContext</code>.
-
-The transactional support in Realm is provided by the
-<code>RLMTransaction</code> class. It provides an atomic access to your
-data, and transactions are divided into read and write
-transactions. If a write transaction succeeds, your data is persistent
-to your device. Using transactions, tables can be accessed
-simultaneously by multiple threads, processes, or applications.
-
-@@example transaction @@
+Another powerful way to extract rows from an <code>RLMTable</code> is to filter 
+its rows with an <code>NSPredicate</code>:
 
+@@example query @@
 
 ** Next steps
 
 <ol>
 
-<li>You can now play with the basic features of Realm by changing and executing the tutorial code.
-It may be helpful to refer to the <a
-href="http://www.realm.io/documentation/ObjectiveC_ref/1/Reference/">reference
-documentation</a> for all the details of the API. </li>
+<li>This was just a brief overview of what's possible with Realm. Feel free to download 
+the sample code from this tutorial to play with Realm. It may be helpful to refer to the 
+<a href="http://www.tightdb.com/documentation/ObjectiveC_ref/1/Reference/">reference
+documentation</a> for more in-depth information about the API.</li>
 
-<li>Feel free to contact <a
+<li>Feel free to contact <a href="mailto:support@tightdb.com">support</a> 
 href="mailto:support@realm.io">support</a> for help or inspiration
-to cracking your particular problems - we appreciate your feedback and
-challenges!</li>
+for help or inspiration to tackling your particular problems - we appreciate 
+your feedback, feature requests and challenges!</li>
 
 </ol>

examples/README.md

@@ -1,12 +1,11 @@
-Running the tutorial
-====================
+# Sample Project
 
+You'll find a sample Xcode project in the `RLMDemo` directory. It's a very simple project that demonstrates how to create a `UITableViewController` backed by TightDB.
 
-Tutorial
-========
-Within this folder you find an Xcode project named TightdbTutorial.xcodeproj.
-The project includes tutorial.m.
-This file contains the source code for the tutorial. 
-To run the tutorial, press Run
+![Screenshot](RLMDemo/screenshot.png)
 
-See our website for more documentation.
+You can add rows by tapping the add button and remove rows by swiping right-to-left.
+
+You'll have to drag in `Tightdb.framework` into the project before being able to run it.
+
+See [tightdb.com](http://tightdb.com) for more documentation.