ChatZilla:Message Filter:Implementation Details

From MozillaWiki
Jump to navigation Jump to search

Notes about this file.

This file is preliminary. Don't flame me too badly, but please do criticize before I implement something you don't like.


Files used

  • xul/content/filter-manager.js
    • Should contain FilterManager object implementation. See below.
    • Will depend on:
      • js/lib/text-serializer.js
      • js/lib/utils.js, maybe.
      • 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
      • js/lib/filter-manager.js (see above)
  • xul/lib/filters.txt
    • Text dump of the Filters in used. Loaded and saved by the FilterManager.
    • Default filters to give the same behaviour that's been hacked into display() and various other places at the moment.
    • Should be saved to a profile place when changing filters. See below.
    • 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.
      Will be changed only by methods on the manager - we might want to be able to listen for changes or do other stuff when this changes, and allowing everyone and their dog to access the object would make that problematic and/or slightly less organized.
  • filterMessage(message, msgType, parentObj, sourceObj, destObj)
    • ParentObj == this in display
      Filters a message. Basically the most important bit. This calls the raw display functions that actually display things, and it manages any other bells and whistles that the filters ask for. Shouldn't throw. Will log errors to dd() (Do we want a new debugMode option for this? Probably do.)
  • _ruleMatchesMessage(rule, message, msgType, parentObj, sourceObj, destObj)
    • Does a filter rule match a given message.
  • _actOnMessage(action, message, msgType, parentObj, sourceObj, destObj)
    • Do the action given this message.
  • 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.
  • insertFilterAt(filter, position)
    • Inserts a filter at the given position.
  • removeFilterAt(position)
    • Removes the filter at the given position.

Filter

  • enabled = true
    • Speaks for itself, I think...
  • allRules = true
    • Whether or not all rules are required to match. (AND vs. OR)
  • stopProcessing = false
    • Whether or not processing should be stopped when this filter matches (after doing actions).
  • isImportant = false
    • Whether to mark all messages displayed by the actions of this filter as Important.
  • 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_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.


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

  • matchType = MATCHTYPE_EXACT
    • The match type of this rule.
  • ruleType
    • The type of this rule.
  • negate = false
    • Whether or not the result of the match should be negated.
  • matchText
    • Text representation of what to match with.

FilterAction

  • forceTabCreation = true
    • Whether or not to force a tab into existence for displaying messages (or showing activity).
  • actionType
    • What type of action is this.
  • 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?)
Retrieved from "https://wiki.allizom.org/index.php?title=ChatZilla:Message_Filter:Implementation_Details&oldid=16853"