Desklets comes with a variety of built-in scripts (desklets) that you can use right out of the box.

2) In the Desklets tab choose a pre-built desklet like Date and Time and press the + button. Note that if the desklet has any favorites you can select a preset design or press the Default button.

3) After you add a new desklet editing mode has been enabled so you can now hover the mouse over the desklet to see to the toolbar appear or click and drag to move the desktlet. You can enabled or disable editing mode by choosing Start Editing in the Desklets menu in the menu bar.

4) Desklets can be customized by either editing parameters or the general style. The style is universal to all desklets and contains a preset list of options but parameters are unique to each individual desklet so you may need to experiement with each desklet to learn how its parameters work.

5) Disable editing mode (see #3) and the new desklet will move over the deskop but behind other windows.

After you've learned the basics of adding, configuring and arranging desklets you can try some of the built-in deskspaces that come packed with Desklets.

A deskspace is a file which represents a saved desktop that can contain any number of configured desklets.

To open a deskspace see the Deskspaces tab in the browser window and double-click on one of the thumbnails.

You can create a new empty deskspaces by using the New... > Deskspace menu item (or with the browser window action button). New deskspaces will appear in the Deskspaces tab of the browser window or you can drag and drop deskpace files onto the browser to add them.

Deskspaces can also be exported and shared as files by using the Export... menu item. Please note for a deskspace to work on another Mac they must have installed all desklet bundles which the deskspace uses.

Under the hood desklets are just bundles (folders) that contain resources, settings and shell scripts which produce either plain text or HTML output. That output is then rendered to the desktop in a window which you can arrange and configure using parameters.

Most desklets will contain parameters which provide a list of settings which you can use to configure the output (i.e. a graphical interface for command line arguments). When you add a new desklet to the desktop you can then change these values via the parameters popup window.

If you are able to write or read scriping languages such as: Bash, PHP, Python Ruby etc... then you may want to open a desklets bundle to see how it works and perhaps edit the script or settings (you may want to duplicate the bundle first to preserve the original copy).

Even if you don't know how to write shell scripts you can use Desklets to display the contents of text files, URLs (web pages) and images on your desktop.

To add a new file (plain text, rich text, images and HTML are all accepted) or URL choose the Add File or Add URL item in the Desklets > New... menu located in the menu bar. After that a window will open and allow you to choose the location of the file you want to display or for URLs open the parameter popup and enter the desired URL (this can be a local file system URL prefixed with file://).

Files and URLs still behave the same way as other desklets so they can be dragged around and the style modified (plain text files only). If the files contents change on disk the file will be automatically refrehsed to reflect the changes.

From the New... menu in the Desklets menu choose a template for the scripting language you are using. After you choose a location a new desklet bundle will be created and a window opened.

Depending on the template you selected the script is the file that will be executed (using the shell specified by the template) when the desklet is refreshed. Because desklets are bundled as directories you can break your script up into multiple files which can be inlcuded from the main script file (see Resources for adding other files).

The editor view lets you edit the script in Desklets but for longer scripts you may prefer to use an external editor of your choice. To open the script in an external editor you can use the Action button in the lower bottom of the window and choose the Edit Script In ... item or double-click on the script file in the Resources tab (see below).

Desklets may be simple single line BASH scripts or complex projects including mutliple scripts and resources.

The resources view shows a list of files that are packaged in the bundle (by default info.plist which contains various settings and a script file based on the template).

To add files to the bundle you can drag and drop them onto the list or use the Add Resources... item in the action menu (lower left-hand corner of the window).

To remove items open the desklets bundle (using the Show Bundle button or title bar) and drag to the trash or the select a file from the list and press delete (the file will be moved to the trash).

Name	Description
Output	If your scripts output needs to render anything besides plain text you can choose HTML which requires the output to be properly formatted HTML which will then be rendered like a normal web page.
Style	The default style of the script when created. This value can be modified by the user in each desklet.
Refresh	Desklets can be automatically refreshed using 3 methods: Time: The script is updated every x seconds. Please note that setting this value too low can impact the system depending on how much processing or rendering the script does (plain text is more efficient for short refresh times). Path Changes: When the file or directory at the path is modified the script will be refreshed. You can use this option to update desklets when files have been modified by the user or when files in a directory have changed. System Notifications: Upon recieving a system wide notification the script will be updated. For example iTunes will broadcast a com.apple.iTunes.playerInfo notification to the system when songs change.

Desklets provides a graphical interface for adding command line arguments to your scripts that users without unix experience can use easily configure. After you provide the template for parameters the user will be able to set values for each desklet they add to the desktop and those values will be passed to your script like command line arguments from the terminal.

In the Parameters tab select the editor view and press return to add a new parameter. When the window opens select a parameter kind from the list.

Kind	Description
Text	Text field which can accept plain text or numbers within a certain value.
Check Box	Checkbox control with a 0 or 1 value for on/off.
Slider	Similar to a text field constrained to number values but easier to use for smaller ranges.
Popup	Variable list of key/value items displayed as a popup menu (the items that appear in the list are edited by double-clicking on the parameters value column in the list).
Color	Color picker which returns the value to the script as a CSS rgba(x,x,x,x) value.
Font	Font picker which returns the value to the script as CSS font-family/font-size property pair.
Path	The path parameter will open a navigation window and allow the user to select a path on their system (this is required to be sandbox compatible).
Section	Sections are used to divide the list of parameters so they are easier to nagivate but do not send any value to the script.

The paramters: text, slider and popup have additional options which should be set by double-clicking on the Value column to open a popup window.

If you double-double click on the parameter name you can edit the: name, key and help tag. The key defines the format which the parameters value is passed to your script in the form of -key=xxx. You can provide a brief help message which will appear if you hover the mouse over the parameter in the popup window when editing a desklet.

Different types of parameters are better for portraiting values in different ways so you must decide what kind to use based on your scripts needs.

When any script is executed Desklets sets a static list of environment variables which contain information about the system or dynamic values from the desklet.

Kind	Description
DS_TOOLS	The path to built-in command line tools packaged with Desklets (`/Contents/SharedSupport/Tools`).
DS_SCRIPTS	The path to built-in scripts packaged with Desklets (`/Contents/SharedSupport/Scripts`)
DS_TEMP_DIR	The path to the application supplied temporary directory. Important: this location is sandbox compatible and should be used instead of the location provided by other scripting languages.
DS_TIME_ZONE	The current system time zone, such as Asia/Bangkok.
DS_TEXT_COLOR	The user defined desklet text color as a CSS rgba value.
DS_FONT	The user user defined desklet font as a CSS font-family/font-size property pair.
DS_FONT_FAMILY	The user user defined desklet font family name as a CSS font-family property.
DS_FONT_SIZE	The user user defined desklet font size as a CSS font-size property.

If you have made a desklet or deskspace you'd like to share with other users or want to download other users constributions please visit www.thealchemistguild.com/desklets.