Merge pull request #266 from joelcox/feature/tutorial

User guide tutorial 

6 files changed, 612 insertions, 1 deletions

diff --git a/user_guide_src/source/index.rst b/user_guide_src/source/index.rst
index e53182550..0e6bc5003 100644
--- a/user_guide_src/source/index.rst
+++ b/user_guide_src/source/index.rst
@@ -42,4 +42,5 @@ CodeIgniter is right for you if:
 	libraries/index
 	database/index
 	helpers/index
-	documentation/index
\ No newline at end of file
+	documentation/index
+	tutorial/index
\ No newline at end of file
diff --git a/user_guide_src/source/tutorial/conclusion.rst b/user_guide_src/source/tutorial/conclusion.rst
new file mode 100644
index 000000000..48fbdcc8a
--- /dev/null
+++ b/user_guide_src/source/tutorial/conclusion.rst
@@ -0,0 +1,26 @@
+##########
+Conclusion
+##########
+
+This tutorial did not cover all of the things you might expect of a
+full-fledged content management system, but it introduced you to the
+more important topics of routing, writing controllers, and models. We
+hope this tutorial gave you an insight into some of CodeIgniter's basic
+design patterns, which you can expand upon.
+
+Now that you've completed this tutorial, we recommend you check out the
+rest of the documentation. CodeIgniter is often praised because of its
+comprehensive documentation. Use this to your advantage and read the
+"Introduction" and "General Topics" sections thoroughly. You should read
+the class and helper references when needed.
+
+Every intermediate PHP programmer should be able to get the hang of
+CodeIgniter within a few days.
+
+If you still have questions about the framework or your own CodeIgniter
+code, you can:
+
+-  Check out our `forums <http://codeigniter.com/forums>`_
+-  Visit our `IRC chatroom <http://codeigniter.com/wiki/IRC>`_
+-  Explore the `Wiki <http://codeigniter.com/wiki/>`_
+
diff --git a/user_guide_src/source/tutorial/create_news_items.rst b/user_guide_src/source/tutorial/create_news_items.rst
new file mode 100644
index 000000000..003b94bd8
--- /dev/null
+++ b/user_guide_src/source/tutorial/create_news_items.rst
@@ -0,0 +1,153 @@
+#################
+Create news items
+#################
+
+You now know how you can read data from a database using CodeIgnite, but
+you haven't written any information to the database yet. In this section
+you'll expand your news controller and model created earlier to include
+this functionality.
+
+Create a form
+-------------
+
+To input data into the database you need to create a form where you can
+input the information to be stored. This means you'll be needing a form
+with two fields, one for the title and one for the text. You'll derive
+the slug from our title in the model. Create the new view at
+application/views/news/create.php.
+
+::
+
+    <h2>Create a news item</h2>
+
+    <?php echo validation_errors(); ?>
+
+    <?php echo form_open('news/create') ?>
+
+        <label for="title">Title</label> 
+        <input type="input" name="title" /><br />
+
+        <label for="text">Text</label>
+        <textarea name="text"></textarea><br />
+
+        <input type="submit" name="submit" value="Create news item" /> 
+
+    </form>
+
+There are only two things here that probably look unfamiliar to you: the
+form_open() function and the validation_errors() function.
+
+The first function is provided by the `form
+helper <../helpers/form_helper.html>`_ and renders the form element and
+adds extra functionality, like adding a hidden `CSFR prevention
+field <../libraries/security.html>`_. The latter is used to report
+errors related to form validation.
+
+Go back to your news controller. You're going to do two things here,
+check whether the form was submitted and whether the submitted data
+passed the validation rules. You'll use the `form
+validation <../libraries/form_validation.html>`_ library to do this.
+
+::
+
+    public function create()
+    {
+        $this->load->helper('form');
+        $this->load->library('form_validation');
+        
+        $data['title'] = 'Create a news item';
+        
+        $this->form_validation->set_rules('title', 'Title', 'required');
+        $this->form_validation->set_rules('text', 'text', 'required');
+        
+        if ($this->form_validation->run() === FALSE)
+        {
+            $this->load->view('templates/header', $data);   
+            $this->load->view('news/create');
+            $this->load->view('templates/footer');
+            
+        }
+        else
+        {
+            $this->news_model->set_news();
+            $this->load->view('news/success');
+        }
+    }
+
+The code above adds a lot of functionality. The first few lines load the
+form helper and the form validation library. After that, rules for the
+form validation are set. The set\_rules() method takes three arguments;
+the name of the input field, the name to be used in error messages, and
+the rule. In this case the title and text fields are required.
+
+CodeIgniter has a powerful form validation library as demonstrated
+above. You can read `more about this library
+here <../libraries/form_validation.html>`_.
+
+Continuing down, you can see a condition that checks whether the form
+validation ran successfully. If it did not, the form is displayed, if it
+was submitted **and** passed all the rules, the model is called. After
+this, a view is loaded to display a success message. Create a view at
+application/view/news/success.php and write a success message.
+
+Model
+-----
+
+The only thing that remains is writing a method that writes the data to
+the database. You'll use the Active Record class to insert the
+information and use the input library to get the posted data. Open up
+the model created earlier and add the following:
+
+::
+
+    public function set_news()
+    {
+        $this->load->helper('url');
+        
+        $slug = url_title($this->input->post('title'), 'dash', TRUE);
+        
+        $data = array(
+            'title' => $this->input->post('title'),
+            'slug' => $slug,
+            'text' => $this->input->post('text')
+        );
+        
+        return $this->db->insert('news', $data);
+    }
+
+This new method takes care of inserting the news item into the database.
+The third line contains a new function, url\_title(). This function -
+provided by the `URL helper <../helpers/url_helper.html>`_ - strips down
+the string you pass it, replacing all spaces by dashes (-) and makes
+sure everything is in lowercase characters. This leaves you with a nice
+slug, perfect for creating URIs.
+
+Let's continue with preparing the record that is going to be inserted
+later, inside the $data array. Each element corresponds with a column in
+the database table created earlier. You might notice a new method here,
+namely the post() method from the `input
+library <../libraries/input.html>`_. This method makes sure the data is
+sanitized, protecting you from nasty attacks from others. The input
+library is loaded by default. At last, you insert our $data array into
+our database.
+
+Routing
+-------
+
+Before you can start adding news items into your CodeIgniter application
+you have to add an extra rule to config/routes.php file. Make sure your
+file contains the following. This makes sure CodeIgniter sees 'create'
+as a method instead of a news item's slug.
+
+::
+
+    $route['news/create'] = 'news/create';
+    $route['news/(:any)'] = 'news/view/$1';
+    $route['news'] = 'news';
+    $route['(:any)'] = 'pages/view/$1';
+    $route['default_controller'] = 'pages/view';
+
+Now point your browser to your local development environment where you
+installed CodeIgniter and add index.php/news/create to the URL.
+Congratulations, you just created your first CodeIgniter application!
+Add some news and check out the different pages you made.
diff --git a/user_guide_src/source/tutorial/index.rst b/user_guide_src/source/tutorial/index.rst
new file mode 100644
index 000000000..eb6f11e34
--- /dev/null
+++ b/user_guide_src/source/tutorial/index.rst
@@ -0,0 +1,47 @@
+########
+Tutorial
+########
+
+This tutorial is intended to introduce you to the CodeIgniter framework
+and the basic principles of MVC architecture. It will show you how a
+basic CodeIgniter application is constructed in step-by-step fashion.
+
+In this tutorial, you will be creating a **basic news application**. You
+will begin by writing the code that can load static pages. Next, you
+will create a news section that reads news items from a database.
+Finally, you'll add a form to create news items in the database.
+
+This tutorial will primarily focus on:
+
+-  Model-View-Controller basics
+-  Routing basics
+-  Form validation
+-  Performing basic database queries using "Active Record"
+
+The entire tutorial is split up over several pages, each explaining a
+small part of the functionality of the CodeIgniter framework. You'll go
+through the following pages:
+
+-  Introduction, this page, which gives you an overview of what to
+   expect.
+-  `Static pages <static_pages.html>`_, which will teach you the basics
+   of controllers, views and routing.
+-  `News section <news_section.html>`_, where you'll start using models
+   and will be doing some basic database operations.
+-  `Create news items <create_news_items.html>`_, which will introduce
+   more advanced database operations and form validation.
+-  `Conclusion <conclusion.html>`_, which will give you some pointers on
+   further reading and other resources.
+
+Enjoy your exploration of the CodeIgniter framework.
+
+.. toctree::
+	:glob:
+	:hidden:
+	:titlesonly:
+	
+	index
+	static_pages
+	news_section
+	create_news_items
+	conclusion
\ No newline at end of file
diff --git a/user_guide_src/source/tutorial/news_section.rst b/user_guide_src/source/tutorial/news_section.rst
new file mode 100644
index 000000000..fe8e41607
--- /dev/null
+++ b/user_guide_src/source/tutorial/news_section.rst
@@ -0,0 +1,214 @@
+############
+News section
+############
+
+In the last section, we went over some basic concepts of the framework
+by writing a class that includes static pages. We cleaned up the URI by
+adding custom routing rules. Now it's time to introduce dynamic content
+and start using a database.
+
+Setting up your model
+---------------------
+
+Instead of writing database operations right in the controller, queries
+should be placed in a model, so they can easily be reused later. Models
+are the place where you retrieve, insert, and update information in your
+database or other data stores. They represent your data.
+
+Open up the application/models directory and create a new file called
+news_model.php and add the following code. Make sure you've configured
+your database properly as described
+`here <../database/configuration.html>`_.
+
+::
+
+    <?php
+    class News_model extends CI_Model {
+
+        public function __construct()
+        {
+            $this->load->database();
+        }
+    }
+
+This code looks similar to the controller code that was used earlier. It
+creates a new model by extending CI\_Model and loads the database
+library. This will make the database class available through the
+$this->db object.
+
+Before querying the database, a database schema has to be created.
+Connect to your database and run the SQL command below. Also add some
+seed records.
+
+::
+
+    CREATE TABLE news (
+        id int(11) NOT NULL AUTO_INCREMENT,
+        title varchar(128) NOT NULL,
+        slug varchar(128) NOT NULL,
+        text text NOT NULL,
+        PRIMARY KEY (id),
+        KEY slug (slug)
+    );
+
+Now that the database and a model have been set up, you'll need a method
+to get all of our posts from our database. To do this, the database
+abstraction layer that is included with CodeIgniter — `Active
+Record <../database/active_record.html>`_ — is used. This makes it
+possible to write your 'queries' once and make them work on `all
+supported database systems <../general/requirements.html>`_. Add the
+following code to your model.
+
+::
+
+    public function get_news($slug = FALSE)
+    {
+        if ($slug === FALSE)
+        {
+            $query = $this->db->get('news');
+            return $query->result_array();
+        }
+        
+        $query = $this->db->get_where('news', array('slug' => $slug));
+        return $query->row_array();
+    }
+
+With this code you can perform two different queries. You can get all
+news records, or get a news item by its `slug <#>`_. You might have
+noticed that the $slug variable wasn't sanitized before running the
+query; Active Record does this for you.
+
+Display the news
+----------------
+
+Now that the queries are written, the model should be tied to the views
+that are going to display the news items to the user. This could be done
+in our pages controller created earlier, but for the sake of clarity, a
+new "news" controller is defined. Create the new controller at
+application/controllers/news.php.
+
+::
+
+    <?php
+    class News extends CI_Controller {
+
+        public function __construct()
+        {
+            parent::__construct();
+            $this->load->model('news_model');
+        }
+
+        public function index()
+        {
+            $data['news'] = $this->news_model->get_news();
+        }
+
+        public function view($slug)
+        {
+            $data['news'] = $this->news_model->get_news($slug);
+        }
+    }
+
+Looking at the code, you may see some similarity with the files we
+created earlier. First, the "\_\_construct" method: it calls the
+constructor of its parent class (CI\_Controller) and loads the model, so
+it can be used in all other methods in this controller.
+
+Next, there are two methods to view all news items and one for a
+specific news item. You can see that the $slug variable is passed to the
+model's method in the second method. The model is using this slug to
+identify the news item to be returned.
+
+Now the data is retrieved by the controller through our model, but
+nothing is displayed yet. The next thing to do is passing this data to
+the views.
+
+::
+
+    public function index()
+    {
+        $data['news'] = $this->news_model->get_news();
+        $data['title'] = 'News archive';
+
+        $this->load->view('templates/header', $data);
+        $this->load->view('news/index', $data);
+        $this->load->view('templates/footer');
+    }
+
+The code above gets all news records from the model and assigns it to a
+variable. The value for the title is also assigned to the $data['title']
+element and all data is passed to the views. You now need to create a
+view to render the news items. Create application/views/news/index.php
+and add the next piece of code.
+
+::
+
+    <?php foreach ($news as $news_item): ?>
+
+        <h2><?php echo $news_item['title'] ?></h2>
+        <div id="main">
+            <?php echo $news_item['text'] ?>
+        </div>
+        <p><a href="news/<?php echo $news_item['slug'] ?>">View article</a></p>
+
+    <?php endforeach ?>
+
+Here, each news item is looped and displayed to the user. You can see we
+wrote our template in PHP mixed with HTML. If you prefer to use a
+template language, you can use CodeIgniter's `Template
+Parser <../libraries/parser.html>`_ class or a third party parser.
+
+The news overview page is now done, but a page to display individual
+news items is still absent. The model created earlier is made in such
+way that it can easily be used for this functionality. You only need to
+add some code to the controller and create a new view. Go back to the
+news controller and add the following lines to the file.
+
+::
+
+    public function view($slug)
+    {
+        $data['news_item'] = $this->news_model->get_news($slug);
+
+        if (empty($data['news_item']))
+        {
+            show_404();
+        }
+
+        $data['title'] = $data['news_item']['title'];
+
+        $this->load->view('templates/header', $data);
+        $this->load->view('news/view', $data);
+        $this->load->view('templates/footer');
+    }
+
+Instead of calling the get\_news() method without a parameter, the $slug
+variable is passed, so it will return the specific news item. The only
+things left to do is create the corresponding view at
+application/views/news/view.php. Put the following code in this file.
+
+::
+
+    <?php
+    echo '<h2>'.$news_item['title'].'</h2>';
+    echo $news_item['text'];
+
+Routing
+-------
+
+Because of the wildcard routing rule created earlier, you need need an
+extra route to view the controller that you just made. Modify your
+routing file (application/config/routes.php) so it looks as follows.
+This makes sure the requests reaches the news controller instead of
+going directly to the pages controller. The first line routes URI's with
+a slug to the view method in the news controller.
+
+::
+
+    $route['news/(:any)'] = 'news/view/$1';
+    $route['news'] = 'news';
+    $route['(:any)'] = 'pages/view/$1';
+    $route['default_controller'] = 'pages/view';
+
+Point your browser to your document root, followed by index.php/news and
+watch your news page.
diff --git a/user_guide_src/source/tutorial/static_pages.rst b/user_guide_src/source/tutorial/static_pages.rst
new file mode 100644
index 000000000..0bbf51b1b
--- /dev/null
+++ b/user_guide_src/source/tutorial/static_pages.rst
@@ -0,0 +1,170 @@
+############
+Static pages
+############
+
+**Note:** This tutorial assumes you've downloaded CodeIgniter and
+`installed the framework <../installation/index.html>`_ in your
+development environment.
+
+The first thing you're going to do is set up a **controller** to handle
+static pages. A controller is simply a class that helps delegate work.
+It is the glue of your web application.
+
+For example, when a call is made to:
+``http://example.com/news/latest/10`` We might imagine that there is a
+controller named "news". The method being called on news would be
+"latest". The news method's job could be to grab 10 news items, and
+render them on the page. Very often in MVC, you'll see URL patterns that
+match:
+``http://example.com/[controller-class]/[controller-method]/[arguments]``
+As URL schemes become more complex, this may change. But for now, this
+is all we will need to know.
+
+Create a file at application/controllers/pages.php with the following
+code.
+
+::
+
+    <?php 
+    class Pages extends CI_Controller { 
+
+        public function view($page == 'home') 
+        {
+	
+        }
+		 
+    }
+
+You have created a class named "pages", with a view method that accepts
+one argument named $page. The pages class is extending the
+CI_Controller class. This means that the new pages class can access the
+methods and variables defined in the CI_Controller class
+(system/core/Controller.php).
+
+The **controller is what will become the center of every request** to
+your web application. In very technical CodeIgniter discussions, it may
+be referred to as the *super object*. Like any php class, you refer to
+it within your controllers as $this. Referring to $this is how you will
+load libraries, views, and generally command the framework.
+
+Now you've created your first method, it's time to make some basic page
+templates. We will be creating two "views" (page templates) that act as
+our page footer and header.
+
+Create the header at application/views/templates/header.php and add the
+following code.
+
+::
+
+    <html>
+        <head>
+            <title>CodeIgniter 2 Tutorial</title>
+        </head>
+        <body>
+
+            <h1>CodeIgniter 2 Tutorial<h1>
+
+The header contains the basic HTML code that you'll want to display
+before loading the main view, together with a heading. It will also
+output the $title variable, which we'll define later in the controller.
+Now create a footer at application/views/templates/footer.php that
+includes the following code:
+
+::
+
+            <em>&copy; 2011</em>
+        </body>
+    <html>
+
+Adding logic to the controller
+------------------------------
+
+Earlier you set up a controller with a view() method. The method accepts
+one parameter, which is the name of the page to be loaded. The static
+page templates will be located in the application/views/pages/
+directory.
+
+In that directory, create two files named home.php and about.php. Within
+those files, type some text − anything you'd like − and save them. If
+you like to be particularly un-original, try "Hello World!".
+
+In order to load those pages, you'll have to check whether the requested
+page actually exists:
+
+::
+
+    <?php 
+    public function view($page = 'home')
+    {
+                
+        if ( ! file_exists('application/views/pages/'.$page.'.php'))
+        {
+            // Whoops, we don't have a page for that!
+            show_404();
+        }
+        
+        $data['title'] = ucfirst($page); // Capitalize the first letter
+        
+        $this->load->view('templates/header', $data);
+        $this->load->view('pages/'.$page, $data);
+        $this->load->view('templates/footer', $data);
+
+    }
+
+Now, when the page does exist, it is loaded, including the header and
+footer, and displayed to the user. If the page doesn't exist, a "404
+Page not found" error is shown.
+
+The first line in this method checks whether the page actually exists.
+PHP's native file\_exists() function is used to check whether the file
+is where it's expected to be. show\_404() is a built-in CodeIgniter
+function that renders the default error page.
+
+In the header template, the $title variable was used to customize the
+page title. The value of title is defined in this method, but instead of
+assigning the value to a variable, it is assigned to the title element
+in the $data array.
+
+The last thing that has to be done is loading the views in the order
+they should be displayed. The second parameter in the view() method is
+used to pass values to the view. Each value in the $data array is
+assigned to a variable with the name of its key. So the value of
+$data['title'] in the controller is equivalent to $title in the view.
+
+Routing
+-------
+
+The controller is now functioning! Point your browser to
+[your-site-url]index.php/pages/view to see your page. When you visit
+index.php/pages/view/about you'll see the about page, again including
+the header and footer.
+
+Using custom routing rules, you have the power to map any URI to any
+controller and method, and break free from the normal convention:
+``http://example.com/[controller-class]/[controller-method]/[arguments]``
+
+Let's do that. Open the routing file located at
+application/config/routes.php and add the following two lines. Remove
+all other code that sets any element in the $route array.
+
+::
+
+    $route['default_controller'] = 'pages/view';
+    $route['(:any)'] = 'pages/view/$1';
+
+CodeIgniter reads its routing rules from top to bottom and routes the
+request to the first matching rule. Each rule is a regular expression
+(left-side) mapped to a controller and method name separated by slashes
+(right-side). When a request comes in, CodeIgniter looks for the first
+match, and calls the appropriate controller and method, possibly with
+arguments.
+
+More information about routing can be found in the URI Routing
+`documentation <../general/routing.html>`_.
+
+Here, the second rule in the $routes array matches **any** request using
+the wildcard string (:any). and passes the parameter to the view()
+method of the pages class.
+
+Now visit index.php/about. Did it get routed correctly to the view()
+method in the pages controller? Awesome!