Documentation for Markup

Markup/HtmlPurifier.php

@@ -0,0 +1,38 @@
+<?php
+
+/**
+ * This file is part of the FOSCommentBundle package.
+ *
+ * (c) FriendsOfSymfony <http://friendsofsymfony.github.com/>
+ *
+ * This source file is subject to the MIT license that is bundled
+ * with this source code in the file LICENSE.
+ */
+
+namespace FOS\CommentBundle\Markup;
+
+/**
+ * Uses HTMLPurifier to parse and sanitise html.
+ *
+ * @author Tim Nagel <tim@nagel.com.au>
+ */
+class HtmlPurifier implements ParserInterface
+{
+    private $purifier;
+
+    public function __construct(\HTMLPurifier $purifier)
+    {
+        $this->purifier = $purifier;
+    }
+
+    /**
+     * Takes a markup string and returns raw html.
+     *
+     * @param string $raw
+     * @return string
+     */
+    public function parse($raw)
+    {
+        return $this->purifier->purify($raw);
+    }
+}

Resources/doc/5-style_it.md

@@ -12,5 +12,5 @@ To use the basic CSS in your templates with Assetic, place the following in your
 {% endstylesheets %}
 ```
 
-## That was it!
+## That is it!
 [Return to the index.](index.md)

Resources/doc/6-integration_with_fosuserbundle.md

@@ -61,5 +61,5 @@ class Comment extends BaseComment implements SignedCommentInterface
 }
 ```
 
-## That was it!
+## That is it!
 [Return to the index.](index.md)

Resources/doc/7-adding_role_based_acl_security.md

@@ -48,5 +48,5 @@ fos_comment:
             delete: ROLE_ADMIN
 ```
 
-## That was it!
+## That is it!
 [Return to the index.](index.md)

Resources/doc/8-adding_symfony2s_builtin_acl_security.md

@@ -49,5 +49,5 @@ must be run whenever any configuration for security changes in FOSCommentBundle,
 including enabling the security features or changing the FQCN of your extended
 FOSCommentBundle objects.
 
-## That was it!
+## That is it!
 [Return to the index.](index.md)

Resources/doc/9-using_a_markup_parser.md

@@ -0,0 +1,27 @@
+Step 9: Using a markup parser
+======================================
+
+FOSComment bundle allows a developer to implement RawCommentInterface, which
+will tell the bundle that your comments are to be parsed for a markup language.
+
+Any markup language is supported, all you need is a bridging class that
+implements `Markup\ParserInterface` and returns the parsed result of a comment
+in raw html to be displayed on the page.
+
+To set up your own custom markup parser, you are required to define a service
+that implements the above interface, and to tell FOSCommentBundle about it,
+adjust the configuration accordingly
+
+``` yaml
+# app/config/config.yml
+
+fos_comment:
+    service:
+        markup: your_markup_service
+```
+
+FOSCommentBundle ships with support for Exercise\HTMLPurifierBundle and the
+set up procedure for using HTMLPurifier can be found [at the following page](9a-markup_htmlpurifier.md)
+
+## That is it!
+[Return to the index.](index.md)

Resources/doc/9a-markup_htmlpurifier.md

@@ -0,0 +1,40 @@
+Step 9: Using ExerciseHTMLPurifierBundle
+======================================
+
+FOSCommentBundle allows you to use [ExerciseHTMLPurifierBundle](https://github.com/Exercise/HTMLPurifierBundle)
+to sanitise HTML entered into comments.
+
+** Note: **
+
+> Letting users post HTML directly without appropriate safety measures can lead
+> to XSS attacks. Be careful with your HTMLPurifier configuration!
+
+FOSCommentBundle does not automatically define the parsing bridge service for
+HTMLPurifier. You will need to do this in your application configuration.
+
+Additionally, you are required to tell FOSCommentBundle about this markup class
+so that it knows to use it. Both requirements are listed in the code block below
+
+``` yaml
+# app/config/config.yml
+
+services:
+    # ...
+    fos_comment.markup.exercise_html_purifier:
+        class: FOS\CommentBundle\Markup\HtmlPurifier
+        arguments: [ @exercise_html_purifier.default ]
+    # ...
+
+fos_comment:
+    # ...
+    services:
+        markup: fos_comment.markup.exercise_html_purifier
+    # ...
+```
+
+You are able to define different configurations for HTMLPurifierBundle, just change
+the argument given to the parser bridge to reflect the new HTMLPurifier configuration
+you have created. More information on this can be found at [ExerciseHTMLPurifierBundle's documentation](https://github.com/Exercise/HTMLPurifierBundle)
+
+## That is it!
+[Return to the index.](index.md)

Resources/doc/index.md

@@ -18,6 +18,7 @@ The following steps are optional and the order doesn't matter:
 - [Integration with FOSUserBundle](6-integration_with_fosuserbundle.md)
 - [Adding role based ACL security](7-adding_role_based_acl_security.md)
 - [Adding Symfony2's built in ACL security](8-adding_symfony2s_builtin_acl_security.md)
+- [Setting up a parser to allow marked up comments](9-using_a_markup_parser.md)
 
 TODO: