Jump to content
jdfwarrior

Workflows Best Practices

Recommended Posts

This thread will serve as reference for a list overall "best practices" when creating workflows for Alfred 2.

This will be an evolving document, so check back occasionally for updates.

Data Storage
In order to clean workflow directories clean and prevent syncing issues, we recommend using the following paths for storing volatile (non-persistent) and non-volatile (persistent) information.

Volatile:~/Library/Caches/com.runningwithcrayons.Alfred-2/Workflow Data/[bundle id]
Non-Volatile:~/Library/Application Support/Alfred 2/Workflow Data/[bundle id]

When writing data to these folders, remember to create a folder for your workflow. Name the folder to match the bundle id of your workflow. This helps keep things clean and organized and make sure that you don't accidentally delete or overwrite someone else's settings.

 

Synced Settings

While it is recommended that settings be written and stored within the two locations provided above, sometimes it is found to be more useful to sync settings along with installed workflows. If this option better fits the needs of your workflow, create a new folder inside of your workflow folder named config and write all settings that need to be synced there. We recommend keeping this folder minimal. Only store settings there that have been deemed necessary. Continue to store all other settings in the previously suggested paths.

 

When exporting workflows, remember to remove the config folder from the workflow path before exporting so that you do not distribute potentially confidential information to the masses. 


Requesting Remote Data
When creating workflows that request data from remote resources, be sure to set your "Please Wait" subtext to inform the end user that data is being requested from remote locations and therefore, may take a moment to populate the list of feedback results. See example image below.

bestpractices1.png

If possible, set timeouts for remote data requests appropriately and provide the the end user with an error (or other such) message to inform them that the request took longer than normal and that script execution has halted. This prevents the user from waiting an unnecessarily long amount of time thinking that feedback is coming.

post-10-0-86427900-1358813671_thumb.png

Share this post


Link to post

Okay, good to know. I've just been using the workflow folder itself for storage, so I'll update that for future releases.

 

Also, what's the deal with the BundleID? I would have thought that that was what Alfred used to recognize workflows as unique. However, currently, when you install a new version of a workflow that you already have, Alfred creates a 2nd duplicate version of it, even when the BundleID is identical. I take it that this will be sorted out in a future beta release?

Share this post


Link to post

Carlos - I haven't made Alfred use the bundle id yet, but when he does, he will use this to overwrite a currently existing workflow and migrate settings etc. If you use the bundle id in the folders David mentioned above, Alfred will also delete these folders too :)

Share this post


Link to post
Carlos - I haven't made Alfred use the bundle id yet, but when he does, he will use this to overwrite a currently existing workflow and migrate settings etc. If you use the bundle id in the folders David mentioned above, Alfred will also delete these folders too :)

Okay, so I can just get my workflow to create a subfolder in those working directories called "myworkflow.bundleID" and that's all Alfred needs to associate the workflow with the appropriate storage folder?

Share this post


Link to post
Okay, so I can just get my workflow to create a subfolder in those working directories called "myworkflow.bundleID" and that's all Alfred needs to associate the workflow with the appropriate storage folder?

 

Yep, just make sure the bundle id you set for your workflow exactly matches [case sensitive] the folder name you create.

Share this post


Link to post

2 Questions:

Is it possible for helper variables for [volatile] and [non-volatile] to be added to Alfred that get expanded to the path of the relevant directory including the bundleID before the scripts are run?

I've submitted a request for this: http://www.alfredforum.com/index.php?/topic/389-alfred-helper-variables-the-get-expanded-before-scripts-are-run/
 

I'd like to show subtitle only when I'm downloading or updating the api list (which happens monthly, and can't run search while this is happening), is there any way to do this?

Share this post


Link to post

Brian,

 

I've posted an initial PHP library on Github that provides a lot of helper functions to get you going when creating a PHP based workflow. When the class object is created, it automatically reads the bundle ID of the workflow, and then provides functions for easily grabbing: users home path, path to workflow, path to workflow data, path to workflow cache data and provides many other functions as well. It's just an initial push. I hope to get a lot more done and make this a REALLY helpful utility for all.

 

Find it here: https://github.com/jdfwarrior/Workflows

Share this post


Link to post

Is there a recommended size for workflow icons? I noticed Alfred's resources use 128x128 pngs

 

128px is a good size as it falls within the maximum 64px size Alfred shows, so will be sharp on a retina display. Also, it's worth optimising your pngs through http://tinypng.org to make them nice and small :)

Share this post


Link to post

I've just tried out the syncing feature, and find it inconvenient that persistent workflow settings are not being synced as well.  E.g. for the tz workflow it would be nice if any changes to the list of configured cities would sync.  Or for the WolframAlpha workflow it would be useful if the API key would sync.

 

I understand and agree that volatile/cached data should be kept on the local machine, but I wonder why it is recommended to keep user configuration out of the workflow directory?

 

I can see that it may be desirable to keep personal configuration data out of exported workflows. But that could be achieved by using a convention to put all such data into a Config subdirectory of the workflow folder, and the Export function could just ignore the content of that subdirectory.

Share this post


Link to post

I understand and agree that volatile/cached data should be kept on the local machine, but I wonder why it is recommended to keep user configuration out of the workflow directory?

 

This is very similar to how OS X works in that you have apps which don't change and a storage area for preferences and support files. When the app (or in Alfred's case, workflow) is upgraded or updated, the source app or workflow can cleanly be replaced without changing settings.

 

Having said that, I appreciate that syncing workflow settings is desirable and have added a note to have a good think about this after Alfred has been released :)

Share this post


Link to post

I've just tried out the syncing feature, and find it inconvenient that persistent workflow settings are not being synced as well.  E.g. for the tz workflow it would be nice if any changes to the list of configured cities would sync.

Actually, for my timezone workflow, it should be fairly simple to add the option to move the tz city file to Dropbox (or another specified location). I've done this for a couple of my other workflows, so I should be able to add this functionality to the timezone workflow. If I haven't posted an update to it in a few days, feel free to remind me. ^_^

Share this post


Link to post

Actually, for my timezone workflow, it should be fairly simple to add the option to move the tz city file to Dropbox (or another specified location). I've done this for a couple of my other workflows, so I should be able to add this functionality to the timezone workflow. If I haven't posted an update to it in a few days, feel free to remind me. ^_^

 

Well remember, you CAN still write data into the workflow folder. It's just not considered best practice. Also have to be careful when installing a new workflow to make sure that it doesn't get overwritten.

Share this post


Link to post

This is very similar to how OS X works in that you have apps which don't change and a storage area for preferences and support files. When the app (or in Alfred's case, workflow) is upgraded or updated, the source app or workflow can cleanly be replaced without changing settings.

 

Having said that, I appreciate that syncing workflow settings is desirable and have added a note to have a good think about this after Alfred has been released :)

 

Yes, that is a good point.

 

I think one possible solution would be for Alfred to provide 2 environment variables to all scripts it executes: $ALFRED_CACHE and $ALFRED_CONFIG. They would be set up to point to the volatile and non-volatile app data directories (including the bundle id). By default $ALFRED_CONFIG would point to the regular ~/Library/Application Support/... folder, but if the user sets a Sync Folder, then these config directories will be moved to a subdirectory of the sync folder.  The $ALFRED_CACHE setting however would continue to point to ~/Library/Caches/...

 

It should be the responsibility of the workflow to create the actual cache and/or config directories because not every workflow needs them; Alfred would just provide the paths, but the workflow has to execute `mkdir -p "$ALFRED_CONFIG"` before creating any files in them.

 

I don't have an opinion (yet) what should happen if the workflow doesn't have a bundle id. Maybe the $ALFRED_* variables should then not be set at all?

 

A side benefit of this scheme is that workflow code doesn't need to embed the bundle id to create these directory paths themselves; changing the bundle id via the Alfred GUI would be enough to change them.

Share this post


Link to post

Brian,

 

I've posted an initial PHP library on Github that provides a lot of helper functions to get you going when creating a PHP based workflow. When the class object is created, it automatically reads the bundle ID of the workflow, and then provides functions for easily grabbing: users home path, path to workflow, path to workflow data, path to workflow cache data and provides many other functions as well. It's just an initial push. I hope to get a lot more done and make this a REALLY helpful utility for all.

 

Find it here: https://github.com/jdfwarrior/Workflows

 

Hey,

 

I just wanted to ask you if it's OK if I write the equivalent Workflow library using AppleScript with the help of your code.. of course I will include in my source code the link to the original source, and the library will be shared for free on github. I'm just trying to help out all my fellow AppleScript gurus :)

 

Please let me know if it's fine :)

Share this post


Link to post

Hey,

 

I just wanted to ask you if it's OK if I write the equivalent Workflow library using AppleScript with the help of your code.. of course I will include in my source code the link to the original source, and the library will be shared for free on github. I'm just trying to help out all my fellow AppleScript gurus :)

 

Please let me know if it's fine :)

 

Of course man, go ahead. Having libraries available makes it easier for everyone to create workflows.

Share this post


Link to post

Hey,

 

I just wanted to ask you if it's OK if I write the equivalent Workflow library using AppleScript with the help of your code.. of course I will include in my source code the link to the original source, and the library will be shared for free on github. I'm just trying to help out all my fellow AppleScript gurus :)

 

Please let me know if it's fine :)

Hi Woofy,

I would really like to have an AppleScript "library". Please post here once you did it !

Share this post


Link to post

Of course man, go ahead. Having libraries available makes it easier for everyone to create workflows.

 

Awesome, thanks so much man!

 

P.S. the only problem I see so far with the library is that AS doesn't have json support, and using third-party libraries is out of the question for multiple reasons.. so I will probably improvise and see what other format I can use for reading/writing cache files and such things..

Share this post


Link to post

Hi Woofy,

I would really like to have an AppleScript "library". Please post here once you did it !

 

Of course I'll do that. Thanks for the support! :D

Share this post


Link to post

Of course man, go ahead. Having libraries available makes it easier for everyone to create workflows.

 

Hey David,

 

Just like I've promised, I already finished a fully working Applescript version of your Workflow class (slightly enhanced here and there). You can get it here: https://github.com/qlassiqa/qWorkflow (it contains heavily commented code, and I also made a very detailed documentation on all methods with examples).

 

As you will see I had to change the name of the methods to avoid language conflicts. Also, right now it has no JSON support since Applescript doesn't know what that is, but I'm already planning a JSON parser for Applescript ;)

 

P.S. I've also included an example AlfredWorkflow that uses my AS Workflow to show iTunes rating for the current song and also give options to rate it differently (make sure you look at the screenshot, it's funny :D)

Edited by ursanrazvan

Share this post


Link to post

Hey David,

 

Just like I've promised, I already finished a fully working Applescript version of your Workflow class (slightly enhanced here and there). You can get it here: https://github.com/qlassiqa/alfred-workflow (it contains heavily commented code, and I also made a very detailed documentation on all methods with examples).

 

As you will see I had to change the name of the methods to avoid language conflicts. Also, right now it has no JSON support since Applescript doesn't know what that is, but I'm already planning a JSON parser for Applescript ;)

 

P.S. I've also included an example AlfredWorkflow that uses my AS Workflow to show iTunes rating for the current song and also give options to rate it differently (make sure you look at the screenshot, it's funny :D)

 

Awesome, post it in the Share Your Workflows area with an appropriate heading so everyone else can find it. I'm sure people are going to love this. Great work.

Share this post


Link to post

E.g. for the tz workflow it would be nice if any changes to the list of configured cities would sync.

 

Actually, for my timezone workflow, it should be fairly simple to add the option to move the tz city file to Dropbox (or another specified location). I've done this for a couple of my other workflows, so I should be able to add this functionality to the timezone workflow. If I haven't posted an update to it in a few days, feel free to remind me. ^_^

Okay, I've done this now: http://www.alfredforum.com/topic/491-timezones-a-world-clock-script-filter-updated-to-v14/ :)

Share this post


Link to post

Join the conversation

You can post now and register later. If you have an account, sign in now to post with your account.

Guest
Reply to this topic...

×   Pasted as rich text.   Paste as plain text instead

  Only 75 emoji are allowed.

×   Your link has been automatically embedded.   Display as a link instead

×   Your previous content has been restored.   Clear editor

×   You cannot paste images directly. Upload or insert images from URL.

×
×
  • Create New...