FMBBCodeBundle
PHP-Decoda integration in Symfony2
A lightweight lexical string parser for BBCode styled markup.
Gitter chat
Code Quality Assurance
SensioLabs Insight | Travis CI | Scrutinizer CI |
---|---|---|
Installation
To install this bundle, you'll need both the Decoda library and this bundle. Installation depends on how your project is setup:
Step 1: Installation
Using Composer, just add the following configuration to your composer.json
:
Or you can use composer to install this bundle: Add FMBbcodeBundle in your composer.json:
composer require helios-ag/fm-bbcode-bundle
Now tell composer to download the bundle by running the command:
composer update helios-ag/fm-bbcode-bundle
Step 2: Enable the bundle
Finally, enable the bundle in the kernel:
<?php
// app/AppKernel.php
public function registerBundles()
{
$bundles = array(
// ...
new FM\BbcodeBundle\FMBbcodeBundle(),
);
}
Step 3: Dump emoticons (optional)
To enable emoticons via emoticon hook, use the following command to copy emoticons images to public folder (web/emoticons)
./app/console bbcode:dump
Basic configuration
Make the Twig extensions available by updating your configuration:
By default only "default" filter enabled, which provide support
for [b], [i], [u], [s], [sub], [sup], [abbr], [br], [hr], [time]
BBCodes
Examples to use the extension in your Twig template
Define BBCode filter in your config.yml:
fm_bbcode:
filter_sets:
my_default_filter:
strict: false # if you want to parse attr values without quotes
locale: ru
xhtml: true
filters: [ default ]
And you can do the following:
{{'[b]Bold text[/b]'|bbcode_filter('my_default_filter')}}
{{'[u]Underlined text[/u]'|bbcode_filter('my_default_filter')}}
{{'[i]Italic text[/i]'|bbcode_filter('my_default_filter')}}
fm_bbcode:
filter_sets:
my_default_filter:
locale: ru
xhtml: true
filters: [ default, quote ]
whitelist: [ b, quote ]
After enabling "quote" filter, you can do such things:
{{'[quote="helios"]My quote[/quote]'|bbcode_filter('my_default_filter')}}
Also you can define multiple filter sets under filter_sets parameter like this:
fm_bbcode:
filter_sets:
my_forum_filter:
locale: ru
xhtml: true
filters: [ default, quote ]
whitelist: [ b, quote ]
my_comment_filter:
locale: ru
xhtml: true
filters: [ default, block, code, email, image, list, quote, text, url, video ]
{{'[quote="helios"]My quote[/quote]'|bbcode_filter('my_forum_filter')}}
{{'[code]My source code[/code]'|bbcode_filter('my_comment_filter')}}
Please keep in mind, that whitelist tags suppress tags, that applied by filters configuration.
Strip filter
To clear text from any bbcodes use bbcode_clean filter: example:
{{'[b]some text[/b]'|bbcode_clean}}
This filter will eliminate any known to decoda tags
Escaping and line breaks
Escaping and line breaks can be controlled via "escaping" and "line_breaks" parameters under filter configuration. Default configuration for them is 'true'. If you wish to pipeline filters, set escaping to false.
Advanced configuration
Overriding messages
Some templates and hooks, use text strings, that can be translated into different languages, the original file located under decoda/config directory, but content of this file can be overriden with messages option, under messages: node. File should be json formatted.
fm_bbcode:
config:
messages: @SomeBundle/Resources/config/messages.json
Adding own templates
Your own templates can be defined at templates node, the example below shows how:
fm_bbcode:
config:
templates:
- path: @SomeBundle/Resources/views/templates
Template examples can be found inside decoda library
Adding own filter
To enable a custom filter, add it as a regular service in one of your configuration, and tag it with fm_bbcode.decoda.filter
:
services:
acme_demo.decoda.filter.your_filter_name:
class: Fully\Qualified\Filter\Class\Name
tags:
- { name: fm_bbcode.decoda.filter, id: your_filter_name }
Your service must implement the Decoda\Filter
interface.
If your service is created by a factory, you MUST correctly set the class parameter for this tag to work correctly.
Adding own hook
To enable a custom hook, add it as a regular service in one of your configuration, and tag it with fm_bbcode.decoda.hook
:
services:
acme_demo.decoda.hook.your_hook_name:
class: Fully\Qualified\Hook\Class\Name
tags:
- { name: fm_bbcode.decoda.hook, id: your_hook_name }
Your service must implement the Decoda\Hook
interface.
If your service is created by a factory, you MUST correctly set the class parameter for this tag to work correctly.
Customize your own emoticons
Your own emoticons can be defined at emoticon
node, the example below shows how:
fm_bbcode:
emoticon:
resource: path/to/emoticons.yml
# path/to/emoticons.yml
imports:
- { resource: path/to/another/emoticons.yml }
emoticons:
my_emoticon:
url: # Default: %fm_bbcode.emoticon.path%/my_emoticon.png
html: # Default: <img src="%fm_bbcode.emoticon.path%/my_emoticon.png" alt="" >
xHtml: # Default: <img src="%fm_bbcode.emoticon.path%/my_emoticon.png" alt="" />
smilies:
- ":my_emoticon:"
How to automatically dump emoticons on each deploy
Add the following commands to you projects composer.json:
# composer.json
"scripts": {
"post-install-cmd": [
"FM\\BbcodeBundle\\Composer\\ScriptHandler::installEmoticons"
],
"post-update-cmd": [
"FM\\BbcodeBundle\\Composer\\ScriptHandler::installEmoticons"
]
}
To custumize emoticons assets folders, use path
and folder
node configuration:
# app/config.yml
fm_bbcode:
emoticon:
path: # Default: /emoticons
folder: # Default: %kernel.root_dir%/../vendor/mjohnson/decoda/emoticons%
Contributors
- Gaiffe Antoine toinouu
- Luis Íñiguez idetia
- Sebastian slider
- olleyyy
- Dirk Olbertz dolbertz
- Florian Krauthan fkrauthan
- predakanga
- Dan piratadelfuturo
- Alexandre Quercia alquerci