root/plugins/sfTextilePlugin/README

= sfTextilePlugin =

== Overview ==

sfTextile plugin is a Symfony plugin. It allows you to parse and convert text written with Textile syntax into HTML.

Textile is a lightweight markup language originally developed by Dean Allen and billed as a "humane Web text generator".
You can find more details about Textile thanks to [http://en.wikipedia.org/wiki/Textile_(markup_language) Wikipedia] and [http://textism.com/tools/textile/ Dean Allen].

== Installation ==

You can install sfTextile plugin via PEAR (recommended) package manager, via SVN repository or manually.

=== PEAR installation ===

 1. The easiest way to install sfTextile plugin is to use PEAR package manager.

 {{{
 $ symfony plugin-install http://plugins.symfony-project.com/sfTextilePlugin
 }}}

 2. Now clear the cache with symfony clear-cache command

 {{{
 $ symfony cc
 }}}

=== SVN installation ===

 1. Enter your `plugins/` directory
 2. Checkout the plugin from svn

 {{{
 $ svn co http://svn.symfony-project.com/plugins/sfTextilePlugin/
 }}}
 
 3. Now clear the cache with symfony clear-cache command

 {{{
 $ symfony cc
 }}}

=== Manual installation ===

 1. Alternatively, if you don't have PEAR or SVN installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's `plugins/` directory

 2. Now clear the cache with symfony clear-cache command

 {{{
 $ symfony cc
 }}}


== Configuration ==

sfTextile plugin comes with 2 additional sf_ configuration properties.
In most cases you don't need to change them but, if you do, here's a quick reference.

 1. `sf_textile_plugin_dir` holds sfTextilePlugin directory. By default its value is a folder called `sfTextile` within your default symfony project plugin directory.

 2. `sf_textile_parser_lib` holds the path to Textile parser library.


''Note''. To change a configuration '''don't change sfTextile configuration file''' but overwrite the variable at application/module level via Symfony settings.yml configuration file or with `sfConfig::set()` statement.


== Usage ==

sfTextile plugin provides both a PHP class and a new set of Helpers.
Helpers are intended to be used only inside a Symfony template while the class can be instantiated and called everywhere in your Symfony application.

=== sfTextile class  ===

sfTextile class currently provides both static and not static methods to do basically the same things.
In the future, not static methods will give you more power while static methods will exist only for the purpose of providing a quick way to parse and convert a text to HTML.

For the moment, you just need to remember two methods.

 1. `sfTextile::doConvert($text)` converts a text to HTML and returns it

 2. `sfTextile::doConvertFile($file)` converts a file to HTML and returns it

`sfTextile::doConvertFile()` may throw a `sfTextileException()` if `$file` doesn't exist or isn't readable.


=== TextileHelpers ===

Before using TextileHelpers you need to load them with `use_helper` statement.

{{{
    <?php use_helper('Textile'); ?>
}}}

Now you can call available helpers in your template:
 1. `convert_textile_text($text)`
 2. `convert_textile_file($file)`
 3. `include_textile_text($text)`
 4. `include_textile_file($file)`


== Changelog ==

2007-08-14: 0.2.0 alpha

 * Changed textile library to be more php5 compliant

2007-08-12: 0.1.0 alpha

 * Initial release

== Todo ==

 * implement restricted text conversion (i.e. in user comments)

== Contacts ==

If you have any questions or feedback feel free to contact me at [mailto:manuel@sonsof.net manuel@sonsof.net].

Please include sfTextilePlugin in the mail subject, this will help me tracking the conversation.


== License ==

sfTextilePlugin is a Symfony plugin created by Manuel Dalla Lana, inspired by sfMarkdownPlugin created by Simone Carletti.
[http://textile.thresholdstate.com/ classTextile] is a PHP class created by Alex Shiels.

For the full copyright and license information, please view the LICENSE file that was distributed with this source code.