sfPayloadFilterChain_TextTransformationPlugin plugin

The sfPayloadFilterChain_TextTransformationPlugin is an addon to the sfPayloadFilterChainPlugin plugin. It provides filters dedicated to transforming text.

Features

• BBCode to XHTML conversion
• Markdown to XHTML conversion
• Syntax highlighting
• Text tokens to image (emoticons)
• Censorship
• Unit-tested

sfPayloadFilterChainPlugin filters

Here are the filters provided by plugin :

• pfc_text_to_xhtml : Conversion of text markup (BBCode, Markdown) to XHTML
• pfc_expand_emoticons : Transformation of text emoticons (":-)", etc)
• pfc_highlight_code : Code syntax highlighting (only compatible with BBCode)
• pfc_censorship : Replacement of "bad" words (defined in database), with a custom "replacement".

The filters are meant to be used in a filtering profile (defined in config/pfc/profiles.yml. See sfPayloadFilterChainPlugin documentation for further informations.

Installation

• Install the plugin :

  symfony plugin-install http://plugins.symfony-project.com/sfPayloadFilterChain_TextTransformationPlugin
  

• HTML_BBCodeParser is a PEAR package. It can be installed using the PEAR utilities :

  pear install html_bbcodeparser
  

Basics

This addon introduces a new filtering class : pfcTextTransformationFilter. It uses transformers to transform payload's text. One of the transformers (pfcMimeConversionTransformer) users mime converters to turn text written using some markup into another (eg. BBCode to XHTML).

Usage

If you plan to use this plugin in your application, you define a dedicated payload class. This class must implement the pfcTextPayloadInterface interface made available by the plugin. eg. :

<?php
class myForumPostPayload implements pfcTextPayloadInterface
{
}

Once you have a compliant payload, just pass it to filter chain, as explained in sfPayloadFilterChainPlugin documentation.

Reference

pfcTextTransformationFilter

The purpose of this filter class is to transform payload's text into, something else, using "text transformers".

Example config/pfc/filters.yml:

pfc_text_to_xhtml:
  enabled: on
  class:   pfcTextTransformationFilter
  params:
    transformer: pfc_mime_to_mime

pfc_expand_emoticons:
  enabled: on
  class:   pfcTextTransformationFilter
  params:
    transformer: pfc_text_to_image

pfc_highlight_code:
  enabled: on
  class:   pfcTextTransformationFilter
  params:
    transformer: pfc_geshi_highlighter

pfc_censorship:
  enabled: on
  class:   pfcTextTransformationFilter
  params:
    transformer: pfc_censorship

As you can see here, the important part is the transformer. Please read below for details on this subject.

Text transformers

The following text transformers are provided by the plugin :

• pfc_mime_to_mime : Converts text of a certain mimetype to its equivalent in another mimetype, using "mime converters".
• pfc_text_to_image : Expands text tokens into their image equivalent, using an yaml expansion map.
• pfc_geshi_highlighter : Highlights code using [qbnz.com/highlighter/ GeSHi].
• pfc_replacewords : Replaces words by another.

Those are specified in config/pfc/transformers.yml. eg. :

pfc_text_to_image:
  enabled:  on
  class:    pfcTextToImageTransformer
  params:
    theme: crystal

As you can see, each specified transformers uses a class. Some of these classes can take parameters.

The text transformation classes

pfcWordReplaceTransformer

Replaces words by another.

It understands the following parameters :

• peer : the name of the peer class to query for words to replace (default : ReplacementPeer)

pfcGeshiHighlightTransformer

The purpose of this text transformation class is to highlight syntax of parts of the payload that are marked as being code (ie. between <code> and </code> tags or <pre> and </pre> tags). It uses the GeSHi library.

It needs a x-language attribute to be set in the code tag to decide which language file to use for highlighting.

It can understand a x-highlight-lines for highlighting lines. Lines number and / or line ranges to be highlighted must be specified as a comma-separated list. eg :

<code x-lang="php" x-highlight-lines="1,3,9-15">

  <!-- snip -->

</code>

This will highlight lines 1, 3 and lines 9 to 15 (included).

It understands the following parameters :

• show_line_numbers : Display line number in highlighted source (default: false)
• highlight_lines_extra : Enable line highlighting (as described above - default: false)

pfcTextToImageTransformer

This text transformation class turns textual "tokens" to their images equivalents. It's mainly designed for emoticons management, therefore it understands anonymous (";)", ":-S", etc) and named emoticons (":name:").

Configuration

This filter understands the following parameters :

• theme
• host
• images_uri

Image map generation

It's understanding of emoticons is based on your application's %s/config/pfc/text_to_image/<MYTHEME>.yml. This file can be autogenerated using the pfc-rebuild-image-map pake task :

• Create a web/images/emoticons/<MYTHEME> directory
• Put whatever images you want in there (both gif and png are supported)
• Run the task :

  symfony pfc-rebuild-image-map images/emoticons
  

A Yaml configuration file will be created for each child directory of images/emoticons.

Basic aliases will be automatically created :

• arf.* -> ":S", ":-S"
• smile.* -> ":)", ":-)"
• wink.* -> ";)", ";-)"

Edit the files if you want to add some more aliases.

This filter understands the following parameters :

pfcMimeConversionTransformer

The purpose of this transformer is to convert a text formatted in a certain way to another format, through the use of configurable "mime converters".

It does not understand any configuration directive.

Mime converters

The plugin supports the following mime types :

• text/bbcode
• text/markdown

The specification of "mime converters" occurs in config/pfc/mime_converters.yml. It is similar to transformers specification. eg. :

text/bbcode:
  enabled:   on
  class:     pfcPearBbCodeConverter
  params:
    filters: "Basic,Lists,Links,Codes,Images"

The mime conversion classes

pfcMarkdownConverter

Converts Markdown markup to XHTML, using php-markdown.

pfcPearBbCodeConverter.class.php

Converts BBCode markup to XHTML, using HTML_BBCodeParser.

The params defined in mime_converters.yml are passed directly to BBCodeParser constructor.

Changelog

2007-06-29 | 0.2.1 beta

• fixed bug related to text to image transformer

2007-06-27 | 0.2.0 beta

• added HTML_BBCodeParser as an optional dependency in package.xml
• added Morgan Bertin as package "developer"
• removed Eclipse's .project from scm
• removed unused pfcAbstractConverter::getDestinationMimeType()
• removed unneeded model classes from scm
• fixed some bugs in package.xml
• BC BREAK : changed image maps filenames for pfc-rebuild-image-map
• BC BREAK : renamed pfcCensorshipTransformer to pfcWordReplaceTransformer
• documentation update

2007-03-14 | 0.1.0 beta

Initial public release.

Active tickets

---

see also : SymfonyPlugins