Copyright (c) 2007 Manuel Dalla Lana
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
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 [Wikipedia] and http://textism.com/tools/textile/ Dean Allen.
Installation
You can install sfTextile plugin via PEAR (recommended) package manager or manually.
PEAR installation
The easiest way to install sfTextile plugin is to use PEAR package manager.
$ symfony plugin-install http://plugins.symfony-project.com/sfTextilePlugin
Now clear the cache with symfony clear-cache command
$ symfony cc
Manual installation
Alternatively, if you don't have PEAR installed, you can download the latest package attached to this plugin's wiki page and extract it under your project's plugins/ directory
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.
sf_textile_plugin_dir holds sfTextilePlugin directory. By default its value is a folder called sfTextile within your default symfony project plugin directory.
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.
sfTextile::doConvert($text) converts a text to HTML and returns it
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
Todo
- implement restricted text conversion (i.e. in user comments)
Contacts
If you have any questions or feedback feel free to contact me at 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.
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.