Alfred 3 Explained—Part 2

In the last tutorial, I showed you many of the changes to Alfred 3, except the changes to workflows. This tutorial is to bring you up to speed on Alfred 3 workflows. I will also show you an example of what you can do with it.

In this tutorial, I will assume that you are familiar with Alfred 2 and it’s workflow creation process. If not, please check out my other tutorials on Alfred 2:

Alfred Workflows for Beginners
Alfred Worflow for Intermediates
Alfred Workflows for Advanced Users, and
Alfred Debugging

Workflow Changes

The first new addition to the workflow area of Alfred 3 is that elements can be placed anywhere. You can now connect an element on the right to an element on the left side.

They've done a great job in detecting and avoiding infinite loop scenarios, though it is still possible with an External Trigger calling the front of a chain of elements that lead to the calling element.

As always, you connect elements by clicking and dragging on the right side middle of an element and dragging to the left side of another element. If a bubble doesn’t appear, it isn’t a legal connection area.

Notice in the above gif animation, the JSON element is the only element that doesn’t get a green bubble on the left side while dragging the second connection. You cannot connect to that element because it would create an infinite loop.

Not only can the elements be placed anywhere, they can also be color coded and have a text description under them to describe what they do. There are four icons in the upper right corner, while the workflow name, short description, and icon are to the left.

The icons from left to right are Export, Preferences, Remote, and Debugger buttons. There are eleven new elements in Alfred 3: Dictionary Filter, List Filter, Args and Variables, Filter, Transform, Delay, Replace, JSON Config, Junction, Debug, and Write Text File.

Export Button

The Export button allows you to save the workflow anywhere in the file system. It will open up a file dialog that allows you to select the directory and file name to save the workflow.

When you export a workflow, it will save it with the .alfred3workflow extension. This is to differentiate them from Alfred 2 workflows.

Preferences Button

The Preferences button brings up the Preferences dialog shown above. In the About this Workflow text area, you can add a text description of the workflow, information on using the workflow, and just any other information that would benefit the user of the workflow. If the workflow uses other applications, this is where I'd put links to the application’s website.

In the Workflow Environment Variables section, you can create environment variables for use in the workflow's scripts. If the variable name is already in use in the system environment, then this will override it’s value for all scripts executed in this workflow.

Remote Button

The Remote button gives you a layout of Alfred Remote to populate screens. You name the screen and add buttons to do anything that is in Alfred 3.

If the workflow has Remote commands, they can be placed in this screen. When you open Alfred Remote on an iOS device, the screen layout here will be usable.

Debug Button

The Debug button brings up the debugger at the bottom of the workflow area. This gives a place to show what each element sends to the next element.

If you have a Debug element connected in your workflow, it will display the requested information here. This makes debugging workflow scripts simple.

Dictionary Filter

The Dictionary Filter allows you to create a workflow that will look up words in a specified dictionary. Therefore, if you have a dictionary that translates from one language to another, this will create an easy translate feature.

List Filter

The List Filter allows you to easily create a predefined list of options from which the user can select. A List Filter is a specialized form of the Script Filter. But, instead of building the possible replies in a script, you can create them in this dialog. The Keyword is the text typed in the Alfred Browser to launch this workflow. The Placeholder Title is the top text shown in the list of possible actions to take while typing in the Alfred Browser. The Placeholder Subtitle is the text just under the Placeholder Title. I often put the workflow name here.

To the right of the Keyword is a dropdown with different options for getting information from the user. This dropdown can either Argument Required, Argument Optional, or No Argument. With Argument Required, you can not activate the workflow until you type an argument after the Keyword. The Argument Optional option will go ahead and display the options in the list before the user starts typing. The No Argument will action the first item without adding an argument.

When you add a new item by pressing the + symbol at the bottom right of the options list, you can specify the Title, Subtitle, and Arg. The Title will be the top string showed in the Alfred Browser for that item, while the Subtitle will be under it. The Arg is the text passed on to the next element when selected.

At the bottom right side of the dialog, there is a dropdown menu with two possibilities: Alfred learns result order based on usage, or keep results in order defined in the table. This sets the two possible ways that Alfred could display the table items in the Alfred Browser.

You can also input the list items with a CSV file containing the items. Therefore, if you create a file containing the following:

1	A title, A subtitle, an argument
2	Another title, another subtitle, another augument

When you drag the file on to the dialog, two new items will be added. The first item will have the title of A title, subtitle of A subtitle, and the argument will be an argument. Therefore, you can import a large number of items in a file by dragging the CSV file on to the list items and it will add each one.

The use of a List Filter and a Script Filter looks the exact same to the user of the workflow. It’s just another way to create a list of things to action in a workflow. The only drawback to the List Filter is that if what the user types doesn’t match anything in the list, then Alfred will show the default search items. With a Script Filter, you can detect if nothing would be selected and add one item to tell the user that the input did not match anything.

Args and Variables

The Args and Variables Element allows you to modify the information passing through the element and environment variables. The next element receives whatever is in the Argument text box. Any item in the Variables area will change the environment variable to the value set.

Both areas take the standard Alfred macro variables of {query} as the input to the element, and {var:varname} as the value of the environment variable named varname.

Filter

The Filter element allows you to filter what gets actioned next. The element after this element will run only if the results of the conditional is true. The text box after Only continue if defines what to check.

The next dropdown menu has three options: is equal to, is not equal to, and matches regex. The next text box contains the value to compare with or a regular expression for the matches regex. The is equal to and is not equal to are self explanatory.

The matches regex allows you to specify a regular expression to match the string. If there is a match anywhere in the string, then execution proceeds to the next element. You can read the ICU Specifications on their website. It is a standard based on Pearl regular expressions. When the matches regex is true, the next element receives the full input string.

You do not have to match just the input. You can use the {var:varname} macro and match against an environment variable. The input is still passed on, not the matched string. Therefore, you can use this element as a switch based on an environment variable or on the input.

Delay

The delay element will pause the execution of the workflow to the next element in the flow by the specified number of seconds. This will not effect any other lines of flow in the workflow.

This delay can come from the input by using {query}, or from an environment variable using the {var:varname} macro. This is handy when you have two or more lines of flow and you want one to wait for the other to have time to complete.

For example, you can have a Keyword element that launches a local web server and opens the browser to it. The Keyword element can have one line connected to the script to launch the server, while another line goes to a delay for 30-seconds and then to a Open URL element. As long as the server doesn’t take more than 30-seconds to launch, that will work fine.

If your workflow has several lines of flow actioning from one element, the topmost on the page actions first, then the second, and so on. Therefore, a one-second delay on a line will cause it to be skipped until all the other parallel lines are executed.

Transform

The Transform element does simple text transformations on the input string. The available transforms are: Trim Whitespace, Upper Case, Lower Case, Camel Case, Reverse String, Strip Diacritics, and Strip Non-Alphanumeric.

Each of these transforms are self explanatory.

Junction

The Junction element simply connects all the inputs to all the outputs. This is great for feeding many inputs to many outputs with minimal lines. Connect all the inputs to the left side of a Junction, and then connect the output to each input element next in order.

This helps keep down clutter and make for easy expansions.

Replace

The Replace element will compare the input to string, regex, or empty input as selected in the dropdown menu. The first text box contains the comparison string, while the second text box contains the substitution string.

Therefore, if the comparison string is box and the replacement string is kite, the phrase I have a box changes to I have a kite. If a regex is ^a(..)ple, the replacement string is $1, and the input is apple, then the output will be pp (the two letters matched by the two . in the match string). The $1 is a shorthand for the first capture group designated by the ().

The Tuts+ course Regular Expressions: Up and Running will help you understand and use regular expressions.

JSON

The JSON element is similar to the Args and Variables element in that it allows you to change the output parameters and environment variables. In the config section, you are able to change the configuration of the next element.

For example, connect an Keyword element to a JSON element and then to a Post Notification. Place the following inside the JSON element configuration:

{
  "alfredworkflow" : {
    "arg" : "{query}",
    "config" : {
      "title" : "Some test text",
      "text" : "This is the test text"
    },
    "variables" : {
    }
  }
}

When you activate the keyword with text afterwards, no matter what text you send, the Post Notification will always have the Title of Some test text, and the Text area (just under the title) will say This is the test text.

Debug

With the Debug element, you can post any of the macros in Alfred to the debug console. The {allvars} macros will show the value of every variable defined for this workflow.

This helps debug scripts by supplying information that would not normally show up in the debug console. You can also check the Clear text in debugger option to clear out the text before posting new text.

Write to File

The Write to File element allows you to write information to a file. You can either specify an absolute path or a relative path to the file. If it is a relative path, you can set it to save in the workflow directory or the workflow’s data directory area.

If you check the Add UUID to filename, it will add a unique number to the name for making unique file names. If you check the Create intermediate folders if they don’t exist option, Alfred creates any missing folders in the path.

If the file exists, you can set it to Skip, Overwrite, or Append. The Skip option will not write the file if it already exists. The Overwrite option will clear out the contents of the file and write the new contents. The Append option automatically adds a new line to each write.

In the text box, you can place any of the Alfred macros to put information in to the file. In my example workflow, I have a Write to File element set to:

1	{var:firstName}\|{var:lastName}\|{var:email}

This create a new line each time with the environment variables firstName, lastName, and email separated with a |.

Script Filter

The Script Filter isn’t a new element, but the output formats for it have changed. You can write a script to output the same XML format as used in Alfred 2 or you can create the output as a JSON structure. The JSON structure should be:

{"items": [
    {
        "uid": "A uniquie id for the item",
        "type": "file",
        "title": "Title for the item",
        "subtitle": "Subtitle for the item",
        "arg": "text passed to next element",
        "autocomplete": "autocomplete text",
        "valid": true,
        "icon": {
            "type": "fileicon",
            "path": "~/Desktop"
        }
    }
]}

You need to repeat lines 2–14 for each item given to the user. Just remember to put a comma after each block except for the last block. I think this format is much easier to work with than the XML format, but I prefer to code in Node.js for my workflows.

All Script Related Elements

Every element that takes a script now has two ways to pass the input parameter. The original way is to replace every occurrence of {query} in the script with the input string.

Now, you can specify that the script receives the input string with input as argv. For some scripts, this works better and is faster since Alfred doesn’t have to do a search and replace operation.

Alfred Environment Variables

Alfred will setup some environment variables for your scripts to use. Here is the list of environment variables set by Alfred:

Variable Name	Description
`alfred_preferences`	This gives the location of the preferences file.
`alfred_preferences_localhash`	This is a hash of the preference file.
`alfred_theme`	This is the theme currently used by Alfred.
`alfred_theme_background`	This tells the background color of the current theme.
`alfred_theme_selection_background`	This tells the background color of the current theme with an item selected.
`alfred_theme_subtext`	This gives the current themes subtext.
`alfred_version`	This is the current Alfred version. It will be 3.0 for Alfred 3.
`alfred_version_build`	This gives the version build number.
`alfred_workflow_bundleid`	This is the current workflows bundle id.
`alfred_workflow_cache`	This contains the path to the current workflow's cache directory.
`alfred_workflow_data`	This contains the path to the current workflow's data directory.
`alfred_workflow_name`	This is the name of the current workflow.
`alfred_workflow_uid`	This is the unique id for the current workflow.
`alfred_debug`	This flag tells if debugging is currently on or off.

Using this information will help make your workflows more future proofed. If you want to view your environment variables from Alfred, you should get the Shell Variables workflow. It's very handy for seeing what your scripts will see.

Example Workflow

The download for this tutorial contains the Email Addresses Workflow seen below. You can use it as an example on how to use many of the new elements in Alfred 3.

This workflow allows you to add email addresses to a CSV file (yellow elements), search for an email address to send an email (blue elements), display an email address (green elements), or to delete an address (red elements). The elements used by more than one command is white.

The color-coding helps others understand what is happening in the workflow. The ability to reuse parts makes writing Alfred workflows easier and more maintainable. The Script Filter also makes use of the environment variable alfred_workflow_data to help make the script future proof. By using this variable, you do not need to hardcode the location of the data files.

You will also notice that the only code written was for the Script Filter to search for the email address and the Run Script element for deleting an email address from the CSV list.

I used the emailclient environment variable that is in the Preferences panel to see if I need to use the default calling method using the mailto protocol, or do something specific for a particular email client. It has one special handling condition for the Let.ter email client that I use the most.

Conclusion

Now that you know about all the new things in Alfred 3 workflows, it's time for you to experiment. Let me know what you think and your experiences in the comments below.