ChatZilla:Message Filter:Usecases

References

ChatZilla:Message Filter ChatZilla:Message Filter:Implementation Details

Usecase 1: Censoring some text

Suppose someone wants to filter out some bad words. They go to ChatZilla > Filters and a dialog opens. They click a button to create a new filter.

The user is now faced with a form with an input field, some checkboxes and two lists. One of the lists contains rules that have to match for a filter to apply (no rules means a filter always matches). The other list contains actions, which will be executed if the filter matches.

One of the checkboxes controls whether all or at least one rule has to match in order for the filter to match.

To start, the user doesn't need to create any rules. They want their replacement to apply to every message anyway.

The user does want ChatZilla to do something with all those messages, so he/she creates an action. The action needs a type, which basically represents what kind of thing the action is supposed to do (this is the .actionType property of the FilterAction object). The user picks "Replace text in the message". Now the user can create a regular expression that specifies what to replace. He can do so by modifying the contents of two input boxes, one of which has the text in the regular expression, the other has the flags (matchText and matchFlags on the FilterAction object, respectively). Then the user specifies the text that should replace everything that matches the regular expression in another input box (this is .replaceText on the FilterAction object).

Now the user specifies some more actions with the same type, but with different regular expressions to match other swear words. Then they make sure that ChatZilla doesn't stop processing after this filter (after all, they do want the message to be displayed eventually) by making sure another field is unchecked (this represents the stopProcessing property of a Filter object).

Now they click OK a bunch of times, and the filterlist gets updated.

So a couple of minutes later, someone drops by in an IRC channel the user is in, and they start spamming links with the word 'porn' in it. As soon as the message arrives, it goes through the usual event processing and finally something decides "We want do display this.". When that code calls the display function, the display function itself doesn't display it anymore (this is confusing, but it can't be avoided as the API can't change as drastically as renaming probably the most used function in the application). Instead, the display function calls the FilterManager instance that's stored on client, and asks it to filter the message. To do this, it passes the message itself and everything else it knows about it.

The FilterManager then looks at its list of Filters and goes through them from top to bottom. For every Filter, it checks whether a sufficient number of the rules match (all rules if the .allRules property on the Filter is true, at least one in all other cases). If this is the case, it executes the list of actions associated with the filter. Afterwards, it continues down the list of filters, unless the current Filter had a .stopProcessing property equal to true in which case the filtering stops immediately.

In the case of this user, the FilterManager finds the filter without any rules that the user defined a few minutes ago. It then proceeds to execute the related actions. It will then replace all the swear and/or vulgar words with the .replaceText the user specified. The FilterManager then proceeds to continue filtering with the changed message. Some other filter might stop it later, after actually displaying the changed message. If nothing stops the processing, it will arrive at the last Filter in the end, which is not editable by the user in the UI, and always matches. The action on this filter tells ChatZilla to display the changed message on the handling tab (part of the current default behaviour).