File:  [mozdev] / quickfilters / www / filtaquilla.html
Revision 1.34: download - view: text, annotated - select for diffs - revision graph
Fri Apr 3 12:18:28 2020 UTC (7 weeks, 2 days ago) by axel.grude
Branches: MAIN
CVS tags: HEAD
*** empty log message ***



<link rel="stylesheet" href="/css/myProjects.css?v=13" type="text/css">
<link rel="stylesheet" href="/css/survey.css?v=2" type="text/css">
<link rel="stylesheet" href="/css/xmas.css?v=1" type="text/css">


<style>
  h2.page-header.fq:before {
    content: url(http://quickfilters.mozdev.org/img/filtaquilla-32.png) !important;
  }
  h3:before {
    content: url(http://quickfilters.mozdev.org/img/filtaQuilla.png) !important;
  }

  td.navigation-list a[href$="filtaquilla.html"] {
    background-color: rgb(203,96,179);
    background-image: linear-gradient(to bottom, rgba(203,96,179,1) 0%,rgba(173,18,131,1) 50%,rgba(222,71,172,1) 100%);
    border-bottom-color: #93105A !important;
    color: #FFF !important;
  } 
  
  pre.code {
    max-width: 800px;
  }
  
  pre.code, 
  p.code {
    font-size: small;
    background: white;
    padding: 0.3em;
    margin: 0.3em;
    border: 1px solid rgb(180,180,180);
  }

  *.callout {
    background: rgba(20,20,20,0.9);
    color: yellow;
  }

  h5.callout {
    font-size: 1.5em;
    font-weight: bold;
    padding: 8px;
  }
  span.callout {
    padding: 3px;
  }
  </style>

<h2 class="page-header fq">FiltaQuilla</h2><br>


<a name="about"> </a>

<div id="infoTabs">
  <div class="infoTab" id="whats-new">
    <h5 class="infoHeader">FiltaQuilla Adoption</h5>
    <p>12/Dec/2019</p>
    <p> This Add-on was adopted from its previous author and creator R. Kent James who 
      had to retire from Add-on development. It has been largely rewritten for 
      Thunderbird 68 in December 2019, with substantial help from 
      <a href="https://github.com/ptomulik" target="_blank">Paweł Tomulik</a>.
    </p>  
    <h5 class="callout">Support My Work</h5>
    <p>As I am often asked about added features 
      for filter conditions and actions for my Add-on 
      <a href="https://addons.thunderbird.net/addon/quickfilters/">quickFilters</a> this is a good 
      location for extending Filter behavior. 
      If you want to <b>support the FiltaQuilla project</b>, please install quickFilters and 
      <br>
      <span class="callout">
      purchase a 
      <a href="http://quickfilters.mozdev.org/donate.html">quickFilters Pro</a> license.</span>
    </p>
    <p>
      I am keeping the license for FiltaQuilla as GPL 3.0 for the time being.
    </p>
  </div>
</div>

<div class="entry-content">
  <p><a href="https://addons.thunderbird.net/thunderbird/addon/filtaquilla/"><strong><em>Download on addons.thunderbird.net</em></strong></a></p>
  <p>FiltaQuilla is now compatible with Thunderbird 60!</p>
  <p>FiltaQuilla provides a variety of additional message filter actions 
		and search terms. This description applies to version 1.1.0.</p>
  <p>By default, only a few of the new actions and terms enabled. You can 
		selectively enable and disable the various filter actions and search 
		terms in the Addons Options dialog (Tools/Addons, select Extensions 
		section, then select the Options box on the FiltaQuilla addon).</p>
  
  <h3>Bug Tracker</h3>
  <p>Please go to the github 
    <a href="https://github.com/RealRaven2000/FiltaQuilla/issues">FiltaQuilla Issue Tracker</a> on github
    for reporting bugs!
  </p>
  
  <h3>Configuration</h3>
  <p> Thunderbird 60 and later: 
      Once you have installed FiltaQuilla, you can use the <i>Add-ons</i> menu on the "Main / Hamburger" menu
      to configure the additional filtering options:<br>
      <img src="img/filtaQuilla-configmenu.png" alt="filtaquilla menu" class="screenshot"><br>
      In the main menu on top of the Thunderbird window, you will find it in 
      Tools > Addon Options.
  </p>
  <p> In older versions of Thunderbird, open the Add-ons manager, select the extensions tab on the left and 
      find the Options button on the FiltaQuilla row.
  </p>
  <p> You can then activate the additional actions / filter conditions for availability in the filter
      editor.<br>
      <img src="img/filtaquilla-actions.png" alt="filtaquilla actions" class="screenshot"><br>
      <img src="img/filtaquilla-searchterms.png" alt="filtaquilla search terms" class="screenshot">
  </p>
  <p> The selected features will then be available as additional options 
      on the <i>Search</i> / <i>Actions</i> drop downs.<br>
      <img src="img/filtaquilla-rules.png" alt="additional filter rules" class="screenshot">
  </p>
  
  <h3>Filter Actions</h3>
  
  <p>Here are the additional filter actions on offer:</p>
  <a name="prepend_subject"> </a>
  <p><strong>Prepend/Suffix to Subject</strong>: add some text to the 
    beginning/end of the subject line. WARNING: this sets the value of the 
    subject in the message database, not in the message itself. Under a 
    variety of circumstances, such as requesting “reindexing” of a folder, 
    the subject will be rewritten from the message, and the changes added by
    the filter will be lost.</p>
		
  <a name="remove_tag"> </a>
  <p><strong>Remove Tag</strong>: Remove a specified tag from the message.</p>
	
  <a name="remove_star"> </a>
  <p><strong>Remove Star</strong>: Remove the star (sometimes called “flagged”) from the email.</p>
	
  <a name="do_not_notify"> </a>
  <p><strong>Do Not Notify</strong>: Disable notifications for this message.</p>
	
  <a name="copy_as_read"> </a>
  <p><strong>Copy as Read</strong>: Copy the message, leaving the original
    Read status unchanged, but marking the copy as Read. This action relies
    on features that are only available when the filter is applied 
    manually. The item will only appear when “Apply filter when” is set to 
    “Manually Run” in the message filter editor.</p>
		
  <a name="mark_as_unread"> </a>
  <p><strong>Mark as Unread</strong>: Mark the message as Unread.</p>
	
  <a name="mark_as_replied"> </a>
  <p><strong>Mark Replied</strong>: Mark the message as Replied.</p>
	
  <a name="launch_file"> </a>
  <p><strong>Launch File</strong>: Using the operating system, launch a 
    particular file. This method has the same effect as if you 
    double-clicked the file, so for executable files—it will just run the 
    file without any parameters. It may not be implemented on some 
    platforms. This action includes two icons, as well as a text field 
    pointing to the file. The folder icon <a href="http://www.mesquilla.com/wp-content/uploads/2008/12/folder.png"><img class="size-full wp-image-132" style="border: 0pt none;" title="browse for a file" src="FiltaQuilla%20%E2%80%93%20MesQuilla_files/folder.png" alt="Browse for a file to launch." width="16" height="16"></a> will allow you to browse for the file to launch. The folder-go icon <a href="http://www.mesquilla.com/wp-content/uploads/2008/12/folder_go.png"><img class="size-full wp-image-132" style="border: 0pt none;" title="Launch the file as a test." src="FiltaQuilla%20%E2%80%93%20MesQuilla_files/folder_go.png" alt="" width="16" height="16"></a> 
		will launch the file to allow you to test the results.</p>
		
  <a name="run_file"> </a>
  <p><strong>Run Program:</strong> This action takes the file name of an 
    executable, and runs a new process with that file. It differs from 
    Launch File in that “Launch” will use a file’s type to decide what 
    program to run, while in Run File the program to run is explicitly 
    given.</p>
  <p>In addition, Run Program can accept parameters. The text that is 
    generated when you select a file to run in the filter editor may be 
    modified by you to include a set of parameters to run, separated by 
    commas. The whole line is a little difficult to see and edit because of 
    the limited space available, but if you select the text and move your 
    cursor to the right, you can edit the parameters that are sent to the 
    process when it is run.</p>
  <p>The parameters that are used to run the file can include information 
    from the message header. Special character values beginning and ending 
    with “@” are used to denote replaceable parameters that are sent to the 
    process to run. For example, a file line like this:</p>
  <p>C:\PROGRAMS\runme.exe,@SUBJECT@,@MESSAGEID@</p>
  <p>will run the program “runme” with two parameters, the first being the
    subject and the second the message id. This is, in fact, the default 
    parameters that are used when a file is selected. The full list of 
    available substitutable parameters is:</p>
  <pre class="code">  // @SUBJECT@ subject
  // @MESSAGEID@ message Id
  // @AUTHOR@ author
  // @RECIPIENTS@ recipients
  // @DATE@ date (local string)
  // @CCLIST@ cc list
  // @DATEINSECONDS@ date in seconds
  // @MESSAGEURI@ URI for the message
  // @PROPERTY@somedbproperty@ uses .getStringProperty(“somedbproperty”)</pre>
  <p>The last item actually has a second internal substitutable 
    parameters. It is intended to be used with a custom DB header, such as 
    “X-SPAM”. You must first define the custom db header by adding that 
    header to the preference mailnews.customDBHeaders, then you can use that
    header in this parameter list.</p>
  <a name="train_as_junk"> </a>
  <p><strong>Train As Junk / Train As Good</strong></p>
  <p>Standard filter actions can mark emails as junk or good, but this 
    does not train the bayesian filter with the tokens in that email. These 
    actions not only mark the emails, but also use them as training for the 
    bayesian filter.</p>
  <p>The issue described in&nbsp; “Combining Moves with Complex Actions” below applies to this action.</p>
	
  <a name="print"> </a>
  <p><strong>Print</strong></p>
  <p>This action prints the email on the default printer.</p>
  <p>The action has a side effect,which was required because of limitation
    of the core code. By default, when you request to print an email, the 
    software presents you a dialog to select the printer to use. We 
    obviously don’t want that in a filter action, but the only available 
    choice is to always print immediately to the default printer. So the 
    first time that the Print action occurs in a filter, we set the global 
    setting that will cause all printing (including those not done by a 
    filter action) to immediately print to the default printer. This is set 
    back to the default value on startup.</p>
  <p>The issue described in&nbsp; “Combining Moves with Complex Actions” below applies to this action.</p>
	
  <a name="add_sender_to_list"> </a>
  <p><strong>Add Sender to Address List</strong></p>
  <p>This action shows a list of all address books and associated email 
    lists, and you may add the sender to either an address book or email 
    list with this action. If the email already exists in the list, it is 
    not added.</p>
		
  <a name="save_attachment"> </a>
  <p><strong>Save Attachments To</strong></p>
  <p>This action saves all email attachments for the matched email (if it 
    has any) to the selected folder, using the name provided by the 
    attachment. If the file already exists, a unique variant of the file 
    name will be used, typically by adding a number to the end of the name.</p>
  <p>The issue described in&nbsp; “Combining Moves with Complex Actions” below applies to this action.</p>
	
  <a name="detach_attachment"> </a>
  <p><strong>Detach Attachments To</strong></p>
  <p>This action detaches all email attachments for the matched email (if 
    it has any) to the selected folder, using the name provided by the 
    attachment. If the file already exists, a unique variant of the file 
    name will be used, typically by adding a number to the end of the name. A
     “detach” differs from a “save” in that, after detach, the message is 
    rewritten to remove the attachment, which can reduce the disk space 
    required to store the message.</p>
  <p>The issue described in&nbsp; “Combining Moves with Complex Actions” below applies to this action.</p>
	
  <a name="javascript_action"> </a>
  <p><strong>Javascript Action / Javascript Action (with body)</strong></p>
  <p>These actions allow execution of arbitrary javascript as the action. 
    The javascript receives the variables defined in the “apply” method of 
    nsIMsgFilterCustomAction.idl, using the same names. The most important 
    of these is the array of message headers that represent the list of 
    messages to apply the action to.</p>
  <p>As a trivial example, to prepend the text “[Hello world]” to the front of each messages’s subject, use the following javascript:</p>
  <pre class="code">for (let index = 0; index &lt; msgHdrs.length; index++)
  {
    let hdr = msgHdrs.queryElementAt(index, Ci.nsIMsgDBHdr);
    hdr.subject = "[Hello, world] " + hdr.subject;
  }
  </pre>
  <p>The “Javascript Action with Body” delays the application of the 
    filter until the body has been downloaded. In theory you could then 
    access the body, and do operations dependent on it. In practice this is 
    difficult to do, so this action might be best considered experimental.</p>
		
  <a name="save_message"> </a>
  <p><strong>Save Message as File</strong></p>
  <p>The location of the file is selectable in the filter definition. The 
    file is given an automatic name based on the subject. If a file of that 
    name already exists in the folder, then a unique name is generated by 
    adding a number to the end of the file name.</p>
  <p>(Beginning in Filtaquilla version 1.3.0): By default, the message is 
    saved with the default Thunderbird extension .eml The filter will use a 
    different extension if you append to the file spec a | followed by the 
    extension. So for example if the filespec is C:\temp\saveas\ for the 
    default extension type, change this to C:\temp\saveas\|txt and the 
    extension will be “txt”.
  </p>
  <p>The issue described in&nbsp; “Combining Moves with Complex Actions” below applies to this action.</p>
	
  <a name="move_later"> </a>
  <p><strong>Move Later</strong></p>
  <p>Filter actions that require the message body do not work correctly 
    when a move is also requested for the message. Move Later is one 
    solution to this problem, though it currently only works reliable with 
    the Save Message as File action. So if you use that action combined with
     a move, try Move Later instead of the normal move, and the combination 
    should work reliably.
  </p>
  
  <h3>Search Terms</h3>
  
  <p>The custom search terms added in FiltaQuilla can be used not only in 
    filters, but also in other search contexts that use Thunderbird’s 
    traditional search. That includes the advanced search dialog, as well as
     definitions of virtual folders. Most of these new search terms are 
    really targeted toward virtual folder definitions. (TB 3.0 also has a 
    newer SQL-based search technology called gloda. FiltaQuilla does not use
     that technology).
   </p>
   
  <a name="bcc"> </a>
  <p><strong>BCC</strong></p>
  <p>This is simply the BCC address field. This value is really only stored in Send folders.</p>
  <a name="tag_thread_head"> </a>
  <p><strong>Tag of Thread Head</strong></p>
  <p>This search responds to the tag that is on the parent message of the thread, rather than the message itself.</p>
	
  <a name="tag_thread_msg"> </a>
  <p><strong>Tag of Thread Message</strong></p>
  <p>This search looks for any messages near the current message, and 
    searches their tags. “Near” always includes the tag parent, but also 
    includes a number of messages on either side of the message in the 
    thread. By default, the code examines +/- 10 messages near the current 
    message, but that number can be changed by setting the value of the 
    preference “extensions.filtaquilla.maxthreadscan”. The default value for
    maxthreadscan is 20, and the code will examine nearby messages within 
    +/- (maxthreadscan/2) of the target message for the search.</p>
  <p>This search may be slow, so you may find a considerable delay when this search term is used.</p>
  <p>Warning: the next three search terms are targeted toward geeks only.</p>
	
  <a name="subject_regex"> </a>
  <p><strong>Subject Regex Match</strong></p>
  <p>This matches the subject with a regular expression that is entered in
    the search field. (If you don’t know what a regular expression is, then
    this search term is not for you.)
  </p>
  <p>If your regular expression has no flags, it can be entered without 
    slashes, for example “findme”. But if you want to add a flag (for 
    example case insensitivity), then surround the term with slashes and 
    append the appropriate flags (for example “/findME/i”).</p>
  <p>Since this code is done using Mozilla javascript, regular expressions should use the Mozilla regex syntax, 
     described 
    <a href="https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp" 
       onclick="__gaTracker('send', 'event', 'outbound-article', 
       'https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RegExp', 'here');" 
       title="Mozilla RegEx syntax documentation" target="_blank">here</a>. 
    You can also test your search expressions at this
    <a href="https://regex101.com/" target="_blank">Online Regex Tester</a> - just make sure you select
    the  <i>javascript</i> option on the left.     
  </p>
	
  <a name="header_regex"> </a>
  <p><strong>Header Regex Match</strong></p>
  <p>This matches any available property of the message header database 
    with a regular expression. (Once again, if you don’t know what a regular
    expression is, this is not for you.) The format of the text in the 
    search is PROPERTY:REGEX (that is, delimited with a ‘:’ character). The 
    property is one of the available properties that are set on the 
    nsIMsgDBHdr object associated with the message. OK, you probably don’t 
    know what those are, but some common values are:</p>
  
  <p style="padding-left: 30px;" class="code"><tt>“subject”,&nbsp; “sender”,&nbsp; “message-id”,&nbsp; “references”, “recipients”, “date”,&nbsp; “size”, “flags”, “priority”,<br>
    “label” (obsolete TB 1.5 term),&nbsp; “statusOfset” (yes it is really spelled that way),&nbsp; “ccList”, “bccList”,<br>
    “msgThreadId”,&nbsp; “threadFlags”,&nbsp; “threadId”, “threadSubject”, “msgCharSet”,&nbsp; “threadParent”,<br>
    “junkscore” (either null, 0, or 100), “junkpercent”, “junkscoreorigin”,&nbsp; “threadNewestMsgDate”,<br>
    “msgOffset”,&nbsp; “offlineMsgSize”.</tt></p>
  <p>It’s really beyond the scope of this page to describe what each of these is.</p>
  <p>You can also request that any existing header in a message (for 
    example X-SPAM-STATUS) be added to the database automatically, by 
    setting the value of the desired header in the mailnews.customDBHeaders 
    preference.</p>
  <p>So as an example, I’ve added x-spam-status as a custom db header, and
    now I can do a regex looking for “SUBJ_ALL_CAPS” in that by creating a 
    “header regex” search with the value:</p>
  <pre class="code">x-spam-status:SUBJ_ALL_CAPS</pre>
  <p>and then I will search for all x-spam-status headers that contain 
    “SUBJ_ALL_CAPS”. This example is a little contrived, because you could 
    do the same thing with the older custom header search in TB, but the 
    difference is that you could use something more complex than simply a 
    string if you wanted as your regex.</p>
  <p>If your regular expression has no flags, it can be entered without 
    slashes, for example “findme”. But if you want to add a flag (for 
    example case insensitivity), then surround the term with slashes and 
    append the appropriate flags (for example “/findME/i”).</p>
		
  <a name="match_folder_name"> </a>
  <p><strong>Folder Name</strong></p>
  <p>Matches message based on the folder name. This can be useful in at least two cases:</p>
  <ul>
  <li>Filter are applied manually, but certain actions should not be executed in all folders</li>
  <li>For IMAP only with incoming filters, it is possible to allow filters
    to be executed on particular folders other than the inbox. In those 
    cases, the Folder Name search can be useful to restrict the application 
    of certain actions to messages that were moved to a particular folder, 
    possibly by another filter.</li>
  </ul>
	
  <a name="match_javascript"> </a>
  <p><strong>Javascript</strong></p>
  <p>This search term allows evaluation of a javascript expression (that 
    could be many lines long) that you could use to setup a search term. You
    can input the javascript in a multiline textbox by clicking on the 
    script edit icon <img class="alignnone size-full wp-image-494" title="script_edit" src="FiltaQuilla%20%E2%80%93%20MesQuilla_files/script_edit.htm" alt="script_edit" width="16" height="16">.
    The javascript will have as input the variable “message” that is an 
    nsIMsgDBHdr XPCOM object that contains the header database record for 
    the message. The value of the expression (or the last expression line 
    executed) will be evaluated to be true or false, and if “true” the 
    message matches.</p>
  <p>One good use for this is to setup boolean expressions that are beyond
    the power of the standard search editor. As an example, suppose you 
    wanted to setup a virtual folder that shows&nbsp; ((tag CONTAINS 
    critical) (OR) (tag contains duesoon)) AND (tag doesntContain DONE). You
    could setup a simple javascript search term with the following:</p>
    <pre class="code">let tags = message.getStringProperty('keywords');
    (/critical/.test(tags) || /duesoon/.test(tags)) &amp;&amp; !(/done/.test(tags));</pre>
  <p>With tags, be careful with the 5 predefined tags (Important, Work, 
    Personal, To do, Later) because their internal values are not the text, 
    but “$label1” – “$label5” respectively. Also, if you rename a tag, the 
    string in keywords does not change.</p>
  <p>Here’s a more complex example. I am testing to see if the number of 
    trained good messages is less than the number of trained junk messages 
    (which I use prior to doing an auto train):</p>
  <pre class="code">// match if junk training exceeds good
    let junkService = Cc["@mozilla.org/messenger/filter-plugin;1?name=bayesianfilter"]
                       .getService(Ci.nsIJunkMailPlugin);
    junkService instanceof Ci.nsIMsgCorpus;
    let kJunkTrait = junkService.JUNK_TRAIT;
    let kGoodTrait = junkService.GOOD_TRAIT;
    let msgCount = {};
    junkService.corpusCounts(kJunkTrait, msgCount);
    let junkCount = msgCount.value;
    junkService.corpusCounts(kGoodTrait, msgCount);
    let goodCount = msgCount.value;
    Cc["@mozilla.org/consoleservice;1"]
     .getService(Ci.nsIConsoleService)
     .logStringMessage('junkCount: ' + junkCount + ' goodCount: ' + goodCount);
   (goodCount &lt; junkCount)</pre>
	 
  <h3>Inherited Properties</h3>
  <p>By default, message filters in IMAP are only applied to the INBOX. If
		you have some server-side filters, there could be times when you also 
		want to apply filters to other folders. FiltaQuilla includes an 
		inherited folder property “Apply Incoming Filters” that you may use to 
		specify additional folders that will have filters applied. See the post “<a href="http://www.mesquilla.com/2009/11/06/inherited-folder-properties-revisited/index.html">Inherited Folder Properties – revisited</a>” for more information about using inherited folder properties.</p>
  <h3><strong>Combining Moves with Complex Actions</strong></h3>
  <p>Certain filter actions that require access to the message body do not
		work well when combined with a filter that also moves the message. In 
		that case, a race occurs to see if the complex action can be applied 
		before the move deletes the message from the folder.</p>
  <p>You have two choices available to workaround this issue:</p>
  <ol>
		<li><strong>Move Later action</strong>. The Move Later action will work 
			well with the Save Message as File action, and may work with other 
			actions. Use this in place of the normal message move action.</li>
		<li><strong>Folder-specific actions</strong>. This is a little more 
			complex to setup, and only works on IMAP, but should work reliably once 
			setup. The idea is that you apply the move first, and then when the 
			message arrives in the destination folder, then you apply the complex 
			action. You need to do all of the following for this to work:</li>
  </ol>
	
  <blockquote>
		<ul>
			<li>Enable “Apply Incoming Filters” for all folders that are 
				destinations of a message with a complex action. See “Inherited 
				Properties”&nbsp; above for how this is done.</li>
			<li>Define a normal filter that moves the message. It may be necessary 
				to restrict application of this filter to the inbox using the “Folder 
				Name” search term.</li>
			<li>Define a second filter that will be used to execute the complex 
				action. Restrict that application of that filter using a Folder Name 
				search term. So, for example, you could add a search term for the 
				complex action “Folder Name Isn’t Inbox”.</li>
		</ul>
  </blockquote>
	
  <blockquote>
		<p>This setup will attempt to run your filters twice, so it 
			may necessary to restrict other filters as well using the “Folder Name” 
			search term to prevent having them apply more than once.</p>
	</blockquote>
  <blockquote>
		<p>Sorry this is so complex, but at least now there is some available method to be used to setup complex filters with actions.
		</p>
	</blockquote>
  
  <h3><strong>Future Functions</strong></h3>
	
  <a name="match_attachmentname"> </a>
  <p><strong>Check Attachment names with regular expressions</strong></p>
	<p>
		Unfortunately this function cannot be currently implemented.
		As long as the filter mechanims in Thunderbird is synchronous, we cannot read attachment 
		info during filtering - since we need this as a condition for further actions in the filter
		queue. Thunderbird wants to eventually make the filtering mechanism asynchronous but at the 
		moment there is no concrete plan for this.
	</p>
    
</div>

FreeBSD-CVSweb <freebsd-cvsweb@FreeBSD.org>