Textile Markup

Category:Library::Markup | Category:Library::External

Textile is a lightweight markup language originally developed by Dean Allen and billed as a "humane Web text generator". Textile converts its marked-up text input to valid, well-formed XHTML and also inserts character entity references for apostrophes, opening and closing single and double quotation marks, ellipses and em dashes.

Previously, the use of TextilePHP was the recommended way to get Textile for use with CI. However, TextilePHP now seems to be defunct. You might think that downloading Textile from the Textile homepage would seem like a good option, but the Textile version 2.0 available for download from the Textile homepage is outdated and contains at least one bug relating to outputting lists.

For the most up to date Textile, download the latest Textpattern, extract the files and grab the classTextile.php file. Even though this file is also designated as version 2.0 it is in fact newer than the one that you get from the Textile homepage and works better.

Integrating Textile in to CodeIgniter is pretty straight forward, and is ideal for content-based websites where it makes sense to use Textile-formatted text for page content - it can be stored in plain text files and loaded as views, or it can be stored in a database.

Textile as a CI Library

To use Textile in Code Igniter is very simple - just take the classTextile.php file, rename it to Textile.php and drop it in to your application/libraries folder.

Add the following line immediately after the opening <?php tag:

if (!defined('BASEPATH')) exit('No direct script access allowed');

Textile is now ready to load into your controllers and models or in config/autoload.php.

Using Textile - basic example

Controller

function index(){
  // Load library
  $this->load->library('Textile');
  // Load the contents of a view into a variable. This view contains Textile-formatted text.
  $textile = $this->load->view('text/example', NULL, True);
  // Get Textile library to process the Textile-formatted text into HTML
  $html = $this->textile->TextileThis( $textile );
  // Set layout title
  $layout['title'] = 'Textile example';
  // Set the body of the page to the formatted page
  $layout['body'] = $html;
  // Load final view
  $this->load->view('layout', $layout);
}

View: text/example.php

h3. This is a subhead

p{color:red}. This is some text of dubious character. Isn't the use of "quotes" just lazy writing -- and theft of 'intellectual property' besides? I think the time has come to see a block quote.

* This is a list item
* So is this
* And this one, too!

Output

The resulting page will contain a Size 3 heading, a red-coloured paragraph of text, and an unordered list:

<h3>This is a subhead</h3>

<p style="color:red">This is some text of dubious character. Isn't the use of "quotes" just lazy writing -- and theft of 'intellectual property' besides? I think the time has come to see a block quote.</p>

<ul>
<li>This is a list item</li>
<li>So is this</li>
<li>And this one, too! </li>
</ul>

Using Textile - best practice

When processing large Textile pages, it may take longer than desired to load a page, as the text has to be processed each and every time it is loaded. Therefore, it is considered best practice to retrieve only the HTML each time for a given page. There are two methods you can do this in Code Igniter.

*** Method one - caching**. Use the native Code Igniter caching facility to cache the HTML output (obviously the page has to be loaded atleast once). However, you must consider how you will handle changes to the page.

*** Method two - database**. Have a form to handle the editing of pages - take the Textile input and store it and the HTML output in a database. When the page is loaded - only retrieve the HTML field for the given page; but when editing the page retrieve the Textile source so that it can be changed and updated.

Consider the following basic example code.

Database table structure

CREATE TABLE `pages` (
`page_id` INT NOT NULL ,
`title` VARCHAR( 100 ) NOT NULL ,
`textile` LONGTEXT NOT NULL ,
`html` LONGTEXT NOT NULL ,
PRIMARY KEY ( `page_id` )
);

Controller or model function to fetch page title and HTML

function GetPage($page_id){
  $query_str = "SELECT title,html FROM pages WHERE page_id='$page_id' LIMIT 1";
  $query = $this->db->query($query_str);
  if($query->num_rows() == 1){
    return $query->row();
  } else {
    return false;
  }
}

Controller function to show page

function page($id){
  $page = $this->GetPage($id);
  $layout['title'] = $page->title;
  $layout['body'] = $page->html;
  $this->load->view('layout', $layout);
}

Function to handle update from form

function UpdatePage($id){
  if($this->input->post('textile')){
    // Form submitted
    // IMPORTANT: must use stripslashes
    $data['textile'] = stripslashes($this->input->post('textile'));
    $data['html'] = $this->textile->TextileThis($data['textile']);
    // Update database
    $where = " page_id='$id' ";
    $query_str = $this->db->update_string('pages', $data, $where);
    $this->db->query($query_str);
  }
}