ChatZilla:Message Filter:Implementation Details

Notes about this file.

This file is preliminary.

Usage Scenarios

Please refer to ChatZilla:Message Filter instead.

Files used

• xul/content/filter-manager.js
  • Should contain FilterManager, Filter, FilterRule and FilterAction objects implementations. See below.
  • Will depend on:
    • js/lib/text-serializer.js
    • js/lib/utils.js
    • js/lib/file-utils.js
    • xul/content/static.js
    • xul/lib/munger.js

• xul/content/filters.xul
  • Should provide UI for the user to manage filters.
  • Should hopefully not use more XUL files - apparently the UI my calculator used was alright, according to Silver. So I'm looking forward to using something like that (but with trees, since listboxes crash...)
  • Should be opened from one of the menus.
  • Will depend on:
    • xul/locale/filters.dtd
    • xul/content/filter-manager.js (see above)
    • xul/content/filters.js (see below)

• xul/content/filters.js
  • Provides the code for the filter managing UI.
  • Will depend on:
    • xul/content/filter-manager.js
    • Probably some other stuff (js/lib/utils.js) as necessary.

• xul/content/filters.txt
  • The default Filters which are loaded by the FilterManager, if there is no filters.txt file available in the user's profile. A filters.txt file is created as soon as the user changes any of the filters. This new file, in the profile, will be loaded instead of this one.
  • The default filters are supposed to give the same behaviour that's been hacked into display() and various other places at the moment.
  • Depends on nothing what-so-ever.

• xul/locale/chatzilla.properties
  • Hope we don't need more messages, but who knows.

• xul/locale/filters.dtd
  • Localizes filter dialog (see above)
  • Shouldn't have dependencies. Straightforward.

Objects used

FilterManager

• constructor
  • Sets filters to an empty array.
• filters
  • Array of Filter-s (see below). Note that order matters!
    Will be empty initially, loaded from loadFilters, saved with saveFilters.
• filterMsg(message, msgType, parentObj, sourceObj, destObj)
  • ParentObj == this in display
    Filters a message. Basically the most important bit. This calls .filter on all filters in this.filters, until it reaches the end of the array or one of the filters tells it to stop processing. Shouldn't throw. Will log errors to dd() (Do we want a new debugMode option for this? Probably do.)
• loadFilters(file)
  • Load filters from file. Removes any existing filters.
• saveFilters(file)
  • Save filters to file. Can throw (file not writable, etc.) Consumer needs to catch any errors.

Filter

• filterMsg(msgObject)
  • Filters the message described by msgObject, by first going through all the necessary rules, and, if enough of them matched, going through all the actions.
• name
  • Human readable identifier. Not necessarily unique. Used for display in the UI, so the user can get an idea what the filters in the list do.
• enabled
  • Speaks for itself, I think...
• allRules
  • Whether or not all rules are required to match. (AND vs. OR)
• stopProcessing
  • Whether or not processing should be stopped when this filter matches (after doing actions).
• rules
  • Order-matters kind of array of FilterRule-s (see below)
• actions
  • Order-matters kind of array of FilterAction-s (see below)

Constants for FilterRule and FilterAction

Match types:

• MATCHTYPE_EXACT
  • Match the actual text exactly. (==)
• MATCHTYPE_START
  • Match the start of the actual text.
• MATCHTYPE_END
  • Match the end of the actual text.
• MATCHTYPE_CONTAINS
  • The matching text should occur anywhere in the actual text.
• MATCHTYPE_REGEX
  • The actual text should match the RegEx given.

Kinds of filtering:

• RULE_MESSAGETYPE
  • Message type ("NICK", "JOIN", end-of-list, etc.)
• RULE_MESSAGE
  • Message contents
• RULE_FUNCTION
  • Function matching on all the data available.
• RULE_AWAYMSG
  • Away msg contents
• RULE_TARGET_USER
  • Target nickname. .matchText can also be hostmask.
• RULE_TARGET_CHANNEL
  • Channel name, if applicable. Will always fail without a channel present.
• RULE_SOURCE_USER
  • Source nickname. .matchText can also be hostmask.
• RULE_SOURCE_NETWORK
  • Source network name.

Different Action types:

• ACTION_REPLACE_IN_MSG
  • Replaces string or RegExp .match with .replaceText
• ACTION_DISPLAY
  • Uses the .tabs to determine on what Tab. (different field in the UI)
    If the first tab in the list doesn't succeed, try the next, the one after, etc.
• ACTION_GET_ATTENTION
  • window.getAttention()
• ACTION_SET_TABSTATE
  • Sets the tabstate of the tabs in .tabs
• ACTION_PLAY_SOUND
  • Plays sound, accepts file:/// url or 'beep' as parameter in UI (.soundFile).
• ACTION_DISPATCH
  • Dispatches a command. (.toDispatch). Leading / should be acceptable and removed when executing the action (not when storing, because it'd confuse users the next time they open the dialog).
• ACTION_FUNCTION
  • Runs function (.func). Straightforward.
• ACTION_MARK_IMPORTANT
  • Marks the message important (or not) depending on the .important property of the action's data property.

Different tabs Actions can apply to:

• ACTION_TAB_CURRENT
  • Current tab
• ACTION_TAB_SOURCE
  • Display on source tab
• ACTION_TAB_TARGET
  • Use on target tab
• ACTION_TAB_PARENT
  • Use the handling tab
• ACTION_TAB_PARENT_PARENT
  • Parent of handling tab. Do we want to use network here, always?
• ACTION_TAB_CLIENT
  • Use the client tab

FilterRule

• matchesMsg(msgObject)
  • Returns a boolean indicating whether or not this rule matches the given message.
• matchType
  • The match type of this rule.
• ruleType
  • The type of this rule.
• negate
  • Whether or not the result of the match should be negated.
• matchText
  • Text representation of what to match with.
• matchFlags
  • Flags for a regular expression, if needed

FilterAction

• actionType
  • What type of action is this.
• actOnMsg(msgObject)
  • Do the action given this message.
• data
  • Data object containing the necessary data required by various types of actions.
  • forceTabCreation
    • Whether or not to force a tab into existence for displaying messages (or showing activity).
  • tabs
    • What tabs should we try to display on, or try to set the tabstate on. Only one tab will be changed, processing stops after the first time a tab exists.
  • soundFile
    • What sound are we playing.
  • toDispatch
    • What are we dispatching.
  • func
    • Function to run. Should still be a string. (eval works wonders?)
  • match
    • What to match in the message
  • matchFlags
    • RegExp flags if applicable.
  • replaceText
    • What to replace the match in the message with.
  • newState
    • New state for a tab we set the state on.
  • important
    • Whether or not the message should be marked as important.