Add filter example

This is a first version. I still have 2 fatal errors in my local, but wanted to be sure I'm on the right track.

Initial patch without test case. Will update new patch with tests soon.

Final patch with tests & documentation.

Please review and let me know if any changes required.

Gave a quick review on the patch.

1. +++ b/filter_example/filter_example.info.yml
   @@ -0,0 +1,7 @@
   +  - filter
   

   drupal:filter

2. +++ b/filter_example/filter_example.info.yml
   @@ -0,0 +1,7 @@
   \ No newline at end of file
   
   +++ b/filter_example/filter_example.links.menu.yml
   @@ -0,0 +1,4 @@
   \ No newline at end of file
   
   +++ b/filter_example/filter_example.module
   @@ -0,0 +1,34 @@
   \ No newline at end of file
   
   +++ b/filter_example/src/Plugin/Filter/FilterFoo.php
   @@ -0,0 +1,83 @@
   \ No newline at end of file
   

   News line at end :-)

3. +++ b/filter_example/src/Controller/FilterExampleController.php
   @@ -0,0 +1,29 @@
   +      '#markup' => '<p>' . $this->t('This example provides two filters.') . '</p><p>' . $this->t('Foo Filter replaces "foo" with a configurable replacement.') . '</p><p>' . $this->t('Time Tag replaces the string
   

   you can use DescriptionTemplateTrait for long inline description.

4. +++ b/filter_example/src/Plugin/Filter/FilterFoo.php
   @@ -0,0 +1,83 @@
   +      return $this->t('<em>foo</em> replaced with %replacement.', array('%replacement' => $replacement));
   

   You can use %foo instead of tags and replace it just like we did for replacement.

5. +++ b/filter_example/tests/src/Functional/FilterExampleTest.php
   @@ -0,0 +1,104 @@
   +  public static $modules = ['node', 'filter', 'filter_test', 'filter_example'];
   

   Do we really need to enable filter_test and filter_example module for testing ?

@navneet0693

Thanks for the review. I have re-rolled the patch. Please let me know if any changes required.

Added changes in tests, removed depreciated function. Added few changes in module. Ouch please ignore wrong file name :(

I think I need to add 'filter_test' for enabling filtered html and full html filter formats.

@Vj thank you for pointing me out!

I have added a sub-module 'filter_example_test' in tests so as to import the configurations.

This is great. I learned a bunch about how to write a filter by reviewing this code. Thank you. Here's a couple of things I found in the process that I think we can improve before committing this.

1. +++ b/filter_example/filter_example.module
   @@ -0,0 +1,35 @@
   + * Drupal has several content formats (they are not filters), and in our example
   + * the foo replacement can be configured for each one of them, allowing an html
   + * or php replacement, so the module includes a settings callback, with options
   + * to configure that replacements. Also, a Tips callback will help showing the
   + * current replacement for the content type being edited.
   

   I find this paragraph to be kind of confusing. I believe what it is trying to say is that each filter can be configured differently for each of the text formats where it is enabled. This example filter provides configuration that will allow an administrator to determine what string should be replaced with the text "foo".

2. +++ b/filter_example/filter_example.module
   @@ -0,0 +1,35 @@
   + * This filter is a little trickier to implement than the previous one.
   + * Since the input involves special HTML characters (< and >) we have to
   + * run the filter before HTML is escaped/stripped by other filters. But
   + * we want to use HTML in our result as well, and so if we run this filter
   + * first our replacement string could be escaped or stripped. The solution
   + * is to use the "prepare" operation to escape the special characters, and
   + * to later replace our escaped version in the "process" step.
   + */
   

   I think it might be worth adding an @see to \Drupal\filter\Plugin\FilterInterface which has some pretty good high level documentation on the Filter system and how it works.

   As well as an @link for https://www.drupal.org/docs/8/api/filter-api

3. +++ b/filter_example/src/Plugin/Filter/FilterFoo.php
   @@ -0,0 +1,84 @@
   + * Drupal has several text formats (they are not filters), and in our example
   + * the foo replacement can be configured for each one of them, so the module
   + * includes a settingsForm method, with options to configure those replacements.
   + * Also, a Tips method will help showing the current replacement
   + * for the content type being edited.
   

   This comment needs to be wrapped to 80 characters.

4. +++ b/filter_example/src/Plugin/Filter/FilterFoo.php
   @@ -0,0 +1,84 @@
   + * @Filter(
   

   I think we should add an @see to \Drupal\filter\Annotation\Filter which documents the Annotation used here.

   And maybe also \Drupal\filter\Plugin\FilterInterface

5. +++ b/filter_example/src/Plugin/Filter/FilterFoo.php
   @@ -0,0 +1,84 @@
   + *   id = "filter_foo",
   

   This is maybe nit-picky, but the standard here appears to be {MODULE_NAME}_{FILTER}. So this might be better as "filter_example_foo" so as to not possibly conflict with something in the filer module's namespace.

6. +++ b/filter_example/src/Plugin/Filter/FilterFoo.php
   @@ -0,0 +1,84 @@
   +   * The settings defined in this form are stored in database by the filter
   +   * module, and they will be available in the $this->settings.
   

   "stored in the database" ... sentence is missing a "the".

7. +++ b/filter_example/src/Plugin/Filter/FilterFoo.php
   @@ -0,0 +1,84 @@
   +   * The actual filtering is performed here. The supplied text should be
   +   * returned once any necessary substitutions have taken place.
   +   * The example just replaces foo with our custom defined string in
   +   * the settings page.
   

   This comment should be wrapped to 80 characters.

8. +++ b/filter_example/src/Plugin/Filter/FilterTime.php
   @@ -0,0 +1,56 @@
   +/**
   + * Provides a filter to replace "foo".
   + *
   + * When used in combination with the filter_align filter, this must run last.
   + *
   + * @Filter(
   + *   id = "filter_time",
   + *   title = @Translation("Time Tag (example)"),
   + *   description = @Translation("Every instance of the special <time /> tag will be replaced with the current date and time in the user's specified time zone."),
   + *   type = Drupal\filter\Plugin\FilterInterface::TYPE_MARKUP_LANGUAGE,
   + * )
   + */
   

   This should also get an @see for \Drupal\filter\Annotation\Filter and \Drupal\filter\Plugin\FilterInterface

   And the id in the annotation should probably be filter_example_time.

9. +++ b/filter_example/src/Plugin/Filter/FilterTime.php
   @@ -0,0 +1,56 @@
   +  /**
   +   * Time filter prepare callback.
   +   *
   +   * We'll use [filter-example-time] as a replacement for the time tag.
   +   * Note that in a more complicated filter a closing tag may also be
   +   * required.
   +   */
   +  public function prepare($text, $langcode) {
   +    return preg_replace('!<time ?/>!', '[filter-example-time]', $text);
   +  }
   

   This is a cool, and also kind of edge-case technique. I think it's probably worth expanding this comment a little to explain what is going on here, and when this code is going to be called.

Needs re-roll !

Also addressing issues from #18

@eojthebrave thank you for review :-)

I'm attaching a new patch including the comments from #22.

Additionally I've checked the example in a live site and I could get the time filter running. The issue was that the WYSIWYG is encoding and therefore the replacement doesn't work. If you include the tag without directly, it works. It would explain why you couldn't reproduce it and the tests passed.

I'm attaching screenshots with my local example.

I'm attaching a new patch that hopefully will solve Tests errors.

Adding tags.

I wanted to use the fiter_example.module during some training and saw that it had not been ported. I have limited bandwidth but I wanted to nudge this patch forward.

Attached is the patch from #25 updated to work with Drupal 9.x and Examples 3.x. Because of the moving for filter_example.module to the modules directory, an interdiff is not very useful. Moving forward we should continue to include interdiffs.

Changes

• Moved 'filter_example' to 'modules/filter_example'
• Fixed examples_toolbar()
• Change core_version_requirement: ^9 in examples.info. @see #3211322: Loose requirements of examples module for Drupal 9.1.x
• Added core_version_requirement: ^9 to filter_example.info.yml and filter_example_test.info.yml
• Add $defaultTheme to FilterExampleTest.php
• Change format_date() to use DateFormatter in \Drupal\filter_example\Plugin\Filter\FilterTime::process

Testing

• Confirmed automated tests are passing
• Manually tested both filters

Todo

• Run the filter_example.module thru Drupal's coding standards
• Determine if there are any blockers for this being committed

Thanks for working on this, it's close. 4.0.x is the latest dev branch for ^9.4 || ^10

+++ b/modules/filter_example/filter_example.info.yml
@@ -0,0 +1,9 @@
+core_version_requirement: ^9

Rerolled and updated core_version_requirement to ^9.4 || ^10

Fix the test

D8 is EOL. The title is not applicable.

patch does not apply to either 4.0.2 or latest 4.0-dev

In this example, would the config setting for filter_example_foo be translatable?

Rerolled patch #34, please review it.

Thanks!