Using Custom Attributes

In Hazel, you can create your own custom text and date attributes while building patterns. These behave much like the built-in attributes, such as “Name” or “Date Added,” except that you can give them whatever name you want and fill them in with values from different places.

Custom Text Attributes

You can use add “Custom Text” (●) token to a pattern to create your own custom text attribute, which then becomes a token available for any patterns in any subsequent conditions or actions in this rule. In addition, it’s available as an attribute (that is, an entry in the leftmost pop-up menu) in any conditions (in this rule only) after the one in which you define it.

Note:  You can also create custom text attributes by exporting attributes from an  AppleScript or JavaScript .

Custom text tokens are useful in cases where you want to save some matched text and insert it somewhere else. For example, let’s say you have a bunch of files whose name start with a 5-digit ZIP code. You can define a token that matches that portion of the name and call your custom token “ZIP code.” This new token can then be dropped into a “Sort into Subfolders” pattern to sort the files into folders based on ZIP code.

To create a custom text token, click the ● token or drag it into the field at the top of the popover. When you do so, a secondary popover appears, in which you can edit your custom token:

As in the main match pattern editor, you can specify a pattern here. You must also enter a name to identify your custom token; that name then appears in the first pop-up menu for later conditions in this rule, as well as in the list of tokens you can use to create patterns for the rule’s conditions or actions. Here, the token is named “ZIP code” and it matches five consecutive digits. (To help you distinguish custom text attributes, Hazel prefixes their names with ● when they appear in tokens or menus.) Click “Done” when you’re finished creating your custom text token.

When you’re done editing, your custom text token appears, with the name you specified (prefixed with ●) in the other pattern popovers for the current rule (1), which you can then drag into your patterns (2). (It also appears as an attribute at the bottom of the leftmost pop-up menu for later conditions in this rule.) When Hazel runs the rule, it keeps track of what text matched it, and when your custom token is used in the pattern for an action (see  Using Patterns in Actions ), Hazel inserts the text that was matched.

Using the “ZIP code” example above, if a file has the name  10101-Survey , Hazel assigns the “● ZIP code” attribute the value  10101  (the “● ZIP code” token matches five digits in a row). When sorting into subfolders, the file is moved to a folder called  10101 .

Custom Date Attributes

In addition to custom text tokens, you can create custom  date  tokens, which let you match dates in various formats. When a custom date attribute is then used in a pattern as part of an action, Hazel treats it as a date rather than text, which means you can transform it into a different date format if needed.

Note:  You can also create custom date attributes by exporting attributes from an  AppleScript or JavaScript .

For example, we can match any date in the form “2016-09-21” by using a date token. You can do this by dragging the “custom date ( )” token into the pattern.

By default, Hazel will try and detect the date format for you. This is indicated by the “Automatically detect date format” checkbox. When checked, Hazel will try to determine dates in various formats as defined by your system.

If automatic detection fails to detect a date or if you need more control, you can uncheck the option and specify a pattern yourself. From there, customize the pattern by clicking/dragging in the date-related tokens below, combining them with any desired text (such as hyphens or slashes).

Once you’ve added a date token, you can click the tiny arrow on its right side to display a pop-up menu with options that let you customize it. For example, the pop-up menu for “Year” (“99”) tokens lets you specify two-digit (“99”) or four-digit (“1999”) years; “Month” tokens can be formatted as “12” (no leading zeroes for single-digit numbers), “12” (single-digit numbers padded with a leading zero), “Dec” (abbreviated names), or “December” (full names); and “Day” tokens can be formatted as “31” (no leading zeroes for single-digit numbers) or “31” (single-digit numbers padded with a leading zero). Like custom text attributes, custom date attributes must have a name. (To help you distinguish custom date attributes, Hazel prefixes their names with   when they appear in tokens or menus.) Click “Done” when you’re finished creating your custom date token.

You can reuse custom date attributes in other conditions in the same rule. For details, see “Reusing Custom Attributes in Condition Patterns,” just below.

In addition, you can reuse custom date attributes in actions within the same rule. When a custom date token is used as part of a pattern in an action, it acts like any other date attribute, in that you can reformat the date or adjust it as needed. One case where this is useful is when the original month is given as a number, such as “01.” When you reformat it, you can have it output in textual form, such as “Jan” or “January.” (And, of course, you can do the reverse, too). To learn how to formatting dates, see  Editing Date Patterns .

Reusing Custom Attributes in Condition Patterns

If you define a custom attribute in a condition, that attribute is available to subsequent conditions. The attribute is effectively shared between all the conditions that use it. You can even specify different patterns for each case.

The first time the custom attribute successfully matches, it retains that value for the rest of the rule. That means subsequent uses of that attribute in the same rule must match the same value for any given file or folder.

For a text attribute, the exact text must match in subsequent usage. (The pattern for that token is ignored.) For a date attribute, a pattern can still be used to transform the text into a date, but the resulting date must match the previously matched date.

Example 1: Using Two Different Date formats in a Custom Date Attribute

Take, for example, the following:

Although you can’t see it in the main rule interface, each use of the custom attribute has a different date format. The top one is formatted as  1999-12-31  (below, left), and the bottom one is formatted as  December 31, 1999  (below, right).

Using a custom attribute like this enables you to match dates that may appear in different formats. In this example, you can match dates like  August 31, 2015  or  2015-08-31  in the same rule. Since the pop-up menu above the conditions is set to “Any,” only one of the conditions needs to match. If you use the same custom attribute in an action for this rule, it will have the value of the first condition that matched.

Example 2: Matching a Filename with the Name of Its Parent Folder

Now let’s look at another example:

Again, it’s not shown in the main rule interface, but the custom attribute “parent folder name” here is defined as matching anything (…). The first instance matches the name of the file’s parent folder, as indicated by the pop-up menu (“its enclosing folder”) in the nested condition. The second instance matches the name of the file itself. The first time it matches, the name of the parent folder is captured into the custom attribute. When the custom attribute is used again in the second case, it must match the text that was captured before (note that the rule is set to match “All”). So, this example essentially matches a file if its name is the same as its parent folder’s name.

Using custom attributes in this way opens up new possibilities for correlating a file withs its parents or siblings, or correlating a folder with the files inside it.


Using Match Patterns in Conditions

Using AppleScript or JavaScript