You are here

Home » API reference » Custom filter 5

README.txt in Custom filter 5

Same filename and directory in other branches
  1. 8 README.txt
  2. 6.2 README.txt
  3. 6 README.txt
  4. 7.2 README.txt
  5. 7 README.txt
  6. 2.0.x README.txt
Custom Filter module provides an ability to create some filter without writing any module.

When we create a new Input Format, we will be asked to choose the filters we want. Some modules hook into filter module and provide additional filters here, e.g. Textile, GeshiFilter, MathFilter. This module do the same thing, except this module allows user to define their own filter.

How do we define our own filters? First, we need to create a filterset. A filterset is a container containing filters. When we create/configure a new Input Format, every defined filterset will appear in the Filters list.

A filterset is only a container. We need to define some real filters if we want it to work. So, an Input Format contains one/more filtersets, each has its own filters.

The most essential part of each filter is pattern and replacement. A pattern is a regular expression like "/(d)rupal/i", to be matched in text. Once the pattern matched, the module will replace the subtext matched with replacement text provided. If we provide "DDD" as replacement text, then "This drupal module works." becomes "This DDDrupal module works."

Every filter can have subfilters. What actually subfilters are? They are exactly the same as filter, except that they match only the substring, not the whole text.

Filter      : MediaWiki Syntax
Pattern     : /\<mwiki\>(.*?)\<\/mwiki\>/i
Replacement : <p>This is mediawiki section.</p>$1<p>End of mediawiki section.</p>
Description : Match strings surrounded by <mwiki>...</mwiki>

Subfilter   : Heading 1
Matches     : 1
Pattern     : /\=(.*?)\=/
Replacement : <h1>$1</h1>
Description : Converts =...= into <h1>...</h1>

If we have text

  This demonstration demonstrates custom filter.
  <mwiki>=Heading1=</mwiki>
  =Heading1=

the text will be

  This demonstration demonstrates custom filter.
  <p>This is mediawiki section.</p><h1>Heading1</h1><p>End of mediawiki section.</p>
  =Heading1=

The first "=Heading1=" is replaced by "<h1>Heading1</h1>", but the second not. Why? Because the "Heading 1" filter is a subfilter of "Mediawiki Syntax", so "Heading 1" will be used only in the string matched by "Mediawiki Syntax", that is the string surrounded by <mwiki>...</mwiki>.

=INSTALLATION=

1. Just copy the entire Custom Filter directory into the module directory, and enable it at Administer/Site Building/Modules. The module will install 2 tables in Drupal database.
3. There will be a new menu item: Administer/Site Configuration/Custom Filter. This will be the administration page of entire filters. Non-administrator user need to have "administer customfilter" permission to use this.
3. To learn about custom filter, you can import "customfilter_sample.xml" provided.

File

README.txt
View source 
  1. 

  2. Custom Filter module provides an ability to create some filter without writing any module.

  3. 

  4. When we create a new Input Format, we will be asked to choose the filters we want. Some modules hook into filter module and provide additional filters here, e.g. Textile, GeshiFilter, MathFilter. This module do the same thing, except this module allows user to define their own filter.

  5. 

  6. How do we define our own filters? First, we need to create a filterset. A filterset is a container containing filters. When we create/configure a new Input Format, every defined filterset will appear in the Filters list.

  7. 

  8. A filterset is only a container. We need to define some real filters if we want it to work. So, an Input Format contains one/more filtersets, each has its own filters.

  9. 

  10. The most essential part of each filter is pattern and replacement. A pattern is a regular expression like "/(d)rupal/i", to be matched in text. Once the pattern matched, the module will replace the subtext matched with replacement text provided. If we provide "DDD" as replacement text, then "This drupal module works." becomes "This DDDrupal module works."

  11. 

  12. Every filter can have subfilters. What actually subfilters are? They are exactly the same as filter, except that they match only the substring, not the whole text.

  13. 

  14. Filter      : MediaWiki Syntax

  15. Pattern     : /\(.*?)\<\/mwiki\>/i

  16. Replacement : 
    This is mediawiki section.
    $1
    End of mediawiki section.
    

  17. Description : Match strings surrounded by ...

  18. 

  19. Subfilter   : Heading 1

  20. Matches     : 1

  21. Pattern     : /\=(.*?)\=/

  22. Replacement : 
    $1
    

  23. Description : Converts =...= into 
    ...
    

  24. 

  25. If we have text

  26. 

  27.   This demonstration demonstrates custom filter.

  28.   =Heading1=

  29.   =Heading1=

  30. 

  31. the text will be

  32. 

  33.   This demonstration demonstrates custom filter.

  34.   
    This is mediawiki section.
    Heading1
    End of mediawiki section.
    

  35.   =Heading1=

  36. 

  37. The first "=Heading1=" is replaced by "
    Heading1
    ", but the second not. Why? Because the "Heading 1" filter is a subfilter of "Mediawiki Syntax", so "Heading 1" will be used only in the string matched by "Mediawiki Syntax", that is the string surrounded by ....

  38. 

  39. =INSTALLATION=

  40. 

  41. 1. Just copy the entire Custom Filter directory into the module directory, and enable it at Administer/Site Building/Modules. The module will install 2 tables in Drupal database.

  42. 3. There will be a new menu item: Administer/Site Configuration/Custom Filter. This will be the administration page of entire filters. Non-administrator user need to have "administer customfilter" permission to use this.

  43. 3. To learn about custom filter, you can import "customfilter_sample.xml" provided.

  44.