AppleScript Rules Documentation.

Rules introduced in 2.1 provides you with a powerful system for deciding what should be done with a notification. In order to use the rules system, the first thing that you will need to do is place an AppleScript named Rules.scpt into the following folder:

 ~/Library/Application Scripts/com.Growl.GrowlHelperApp.
            

Growl can execute scripts from this folder, and know they are there, but we cannot edit it at all. This is Apple's requirement to show that you are giving your consent. Additionally, Growl will warn you the first time it detects that Rules.scpt is used incase someone elseyou placed it there without your knowledge (no App Store approved, Sandboxed app will ever be able to touch this folder). There is also an option to disable it both in the initial warning, and in the General tab of the Growl preferences.

Rules.scpt should be an applescript with at least the following:


using terms from application "Growl"
   on evaluate notification with notification
      --Rules go in here
      --Ultimately return what you want Growl to do with the notification
   end evaluate notification
end using terms from

            

The first and last lines tell it we are using terms from Growl's dictionary in this block The second and next to last lines are the event handler Growl will call to evaluate notification. Note that no return is required, if we receive back no return value, or an unknown return type, we will simply follow the default setup in Growl's UI.

Between the on evaluate notification and it's end is where the logic, and decision making go. This can be anything AppleScript supports, or even anything you can do in a shell/unix script.

A very simple decision, you want any notification coming through with your user name to be displayed using a different style, say, Music Video. Simply put the following inside the on evaluate notification handler. We wrap our if/end if block in ignoring case/end ignoring so that any capitalization of GrowlMac is handled properly.


ignoring case
   if notification's note description contains "GrowlMac" then
      return {display:"Music Video"}
   end if
end ignoring

            

We return a record, with one key/value pair, display:"Music Video" where display is the key, and "Music Video" is the value. Music Video is the name of a configuration that is in the Displays tab of Growl. display may be any of the following without quotes none, default, global default, or a display configuration name in quotes.

Here are some sample returns, and what they mean:



return {enabled:no} --Disables the notification entirely, can also be used to enable a notification that is disabled in the UI.

return {display:none, actions:"Speech"} --No visual display, and use the speech action.

return {network forwarding:no} --Do not forward to any network hosts.

return {notification return:notification} --Return a modified notification, only certain values modifiable.

            

Returning a modified notification can be quite powerful. It lets you modify the following: title, description, icon, sticky, and priority. An example of modifying a notification:


on replace_chars(this_text, search_string, replacement_string)
   set AppleScript's text item delimiters to the search_string
   set the item_list to every text item of this_text
   set AppleScript's text item delimiters to the replacement_string
   set this_text to the item_list as string
   set AppleScript's text item delimiters to ""
   return this_text
end replace_chars

using terms from application "Growl"
   on evaluate notification with notification
      ignoring case
         set description to notification's note description
         if description contains "@Growl" then
            set notification's note description to replace_chars(description, "@Growl", "@GrowlMac")
            return {notification return:notification}
         end if
      end ignoring
   end evaluate notification
end using terms from


            

Now, this script, if the description contains "@Growl" (ignoring case), it proceeds to replace that with "@GrowlMac", and set the description to the new string. We then return the modified notification, and Growl will display the note using the defaults for displays/actions/network/etc, but with the modified text. Note that we moved the text replacement code out into its own applescript function, to make it easier to reuse.

Why are certain fields not editable? It is because those fields are important to the backend of Growl, and how the notification is handled internally.


On to some more samples of applescript rules, and logic
on is_between_times(startDate, endDate)
   set now to (current date)'s time
   set startTime to date startDate's time
   set endTime to date endDate's time
   if now is greater than startTime and now is less than endTime then
      return true
   else
      return false
   end if
end is_between_times

using terms from application "Growl"
   on evaluate notification with notification
      set startTime to "8:00 AM"
      set endTime to "9:50 PM"
		
      if (current date)'s weekday is Saturday and is_between_times(startTime, endTime) and notification's priority is high or emergency then
         return {actions:"Prowl"}
      end if
   end evaluate notification
end using terms from

            

This Rules.scpt shows evaluation based on time and notification priority, to determine what we are going to do. First, we check if the weekday is saturday, then we check if we are between 8:00 AM and 9:50 PM, again, using a separated out function. The function for doing time evaluation relies on getting the time (in seconds) from the start of the day (midnight) and comparing our current time to those we provide. We then also only care about notification's that have priority of high or emergency. If we do, then we say we want to use "Prowl" as our action, and whatever else is there, leave as default.

Finally, a simple example of using shell scripting from within applescript.

using terms from application "Growl"
   on evaluate notification with notification
      set shell_result to do shell script "echo " & notification's note description & " | grep -i -c Growl"
      if shell_result is greater than 0 then
         return {display:"Music Video"}
      end if
   end evaluate notification
end using terms from

            

To use shell scripting, you use the do shell script command followed by a string with the command, in order to evaluate the result of that command, set a variable to it

               
set shell_result to do shell script "echo Hello World"
            

To stuff variables in the middle, close your current quotes, put in an &, then the variable, then if more fixed stuff is needed after, another &, and reopen quotes. This simple shell script simply greps for Growl within the string, and returns a count of occurrences. If there is greater than 0, use music video, else we will use all defaults.

Rules scripting if not told otherwise, will do as set in the UI for a particular portion (display, actions, networking, etc). To disable a note entirely is a simple return. Also note that what you return in rules will not affect your settings in the UI.

Applescript is quite powerful, and we could go on and on with examples. We will add more as good examples are brought up by users, so if you have something cool you figured out how to do, let us know.