### Site Tools

user-defined-tools-prefs

# Differences

This shows you the differences between two versions of the page.

 user-defined-tools-prefs [2016/09/01 10:53]127.0.0.1 external edit user-defined-tools-prefs [2017/07/26 02:03] (current)admin 2017/07/26 02:03 admin 2017/07/26 01:58 admin 2017/07/26 01:55 admin 2017/07/26 01:53 admin 2017/07/26 01:22 admin 2017/07/26 01:00 admin 2016/10/13 06:59 admin 2016/10/13 06:58 admin 2016/10/09 02:58 admin 2016/10/02 05:28 admin 2016/10/02 04:08 admin 2016/10/02 04:05 admin 2016/10/02 04:03 admin 2016/09/07 12:21 admin 2016/09/07 12:11 admin 2016/09/01 10:53 external edit Next revision Previous revision 2017/07/26 02:03 admin 2017/07/26 01:58 admin 2017/07/26 01:55 admin 2017/07/26 01:53 admin 2017/07/26 01:22 admin 2017/07/26 01:00 admin 2016/10/13 06:59 admin 2016/10/13 06:58 admin 2016/10/09 02:58 admin 2016/10/02 05:28 admin 2016/10/02 04:08 admin 2016/10/02 04:05 admin 2016/10/02 04:03 admin 2016/09/07 12:21 admin 2016/09/07 12:11 admin 2016/09/01 10:53 external edit Line 1: Line 1: - {{images:​screenshots:​udt_config.png}} + ====== User Defined Tool (UDT) Preferences ====== - A User-Defined ​Tool (UDT) is a definition of a command-line,​ where ToDoList fills in live data, and then executes the command on request. With the data, the program that's called makes use of the data to "do something"​. + ([[tools-menu|Menu Bar > Tools Menu]] > Preferences > User Defined ​Tools) - ====What can be done with a UDT?==== + - * Reports can be generated, emailed, or faxed. + - * Data can be passed to other project management systems. + - * ERP systems can incorporate the data into schedules. + - * Data can be sent via web service to remote systems. + - In the above screenshot, a few of the functions seen in the grid include: + {{images:​screenshots:​udt-prefs.png}} - * A utility which counts words in the comments area. The user clicks a toolbar icon (see image below), the comments for the current task are sent to the UDT definiion. The UDT calls a program which counts the words and simply displays a little form with the word count. ​{{images:​screenshots:​udt_toolbar.png}} + - * A command which sends task status data to the Microsoft Outlook Journal. + - * A command that renames files created by ToDoList (exports and reports). + - * The GoToTask command that allows the user to jump to another task identified by its ID. Quite commonly the program that gets executed is the ToDoList.exe program itself. In this case the UDT requests ToDoList to open a small text entry window. At the command-line,​ ToDoList.exe is executed with a "​switch"​ to specify a task ID that will receive focus - and the ID entered in the box is provided to the command-line. The result is that the user simply sees the focus jump to the desired task. + - Note: None of the above UDTs are in your instance of ToDoList. These are all "​user-defined"​ and added by individuals to enhance their own environment. However, people who use ToDoList are eager to share their UDTs and a home will soon be provided for user contributions. // Work in Progress. // + **(Grid)** - The screen above (Preferences > User Defined Tools) lets you configure 3rd party tools to extend ToDoList'​s functionality. Tools set up there are accessible via the Tools Menu and hotkeys [[keyboard-shortcut-prefs|shortcuts]]. Here are the menu items created from the above UDT configuration:​ + * **Tool Name**\\ Displays the names of the UDTs. To change ​the name of a tool, //single-click// on the currently selected tool name or press F2. **Note:** This name will also be used to identify ​the tool on the '​Tools' ​menu as well as acting as the tool's tooltip on the application toolbar. - {{images:​screenshots:​tools_udts.png}} + - + - ====Creating a UDT==== + * **Arguments**\\ Displays the additional information ​that will be passed to the tool via its command-line. For more information see '​Arguments'​ below. - The goal is to create a command template ​that can be populated with data at run-time, and then executed from the DOS prompt. It would look something like this: + - c:​\path\to\program\name.exe ​-switch1 ​-switch2 "​data1" ​-switch "​data2"​ + ----- - The switches ​and data are whatever is required for the name.exe program ​to work. As seen below, ​the data can be provided by ToDoList in Arguments. + **New Tool**\\ + Creates a new entry and prompts you to enter a name to identify your tool on the '​Tools'​ Menu and application toolbar. - The following details describe ​the configuration screen as seen above. The column headers of the grid are profiled. Each of the columns has a corresponding entry field under the grid: + **Delete Tool **\\ + Deletes ​the selected tool. - **Tool ​Name** + **Test Tool **\\ - This lists the currently ​configured tools. The names are assigned by you / the user. Tools not having ​a name or path will not appear in the Tools Menu. To change the name of a tool, **single**-click on the tool name, or if you click on the name and it doesn't open for editing, press F2. + This allows you to run the selected tool using the currently ​selected task for data if the arguments require it. On clicking the button, ​a "Test Tool" window displays to tell you "Tool 'path\name.ext' ​will be run using the following commandline arguments: '-your args'. It will prompt "Do you want to continue?"​ with a '​Yes' ​or 'No' button. The arguments will be filled in with currently available data - you will be prompted if required ​for user data. - **New Tool (button)** + **Import...**\\ - This is the first step to create a new UDT. Enter the name that you want to appear on the Tools Menu. + Allows you to import existing UDTs that are stored elsewhere in another Preferences file. This can be helpful if you work in a team or have backed up your Preferences and want to restore just the UDTs. - {{images:​screenshots:​new_tool.png}} + - **File Path** + ----- + + **Path**\\ Click the folder icon to browse to the application,​ batch file, or script that you wish to run. Click the folder icon to browse to the application,​ batch file, or script that you wish to run. - {{images:​screenshots:​udt_edit.png}} - **Arguments** + **Note:** If you are wanting to create ​a UDT that runs ToDoList itself you need only type in '​todolist.exe' without any path information and this will be understood to mean the path to the currently running instance. - Construct ​a set of data that will be passed ​in the command-line. The down-arrow button attached to this field will display a list of "​placeholder"​ variables for data that ToDoList will substitute when you run the tool. For example an argument might be set as follows: + - /​taskid=$(selTID) + **Arguments**\\ - + This field allows ​you to pass additional information ​to your chosen tool via its command-line. - The$(selTID) is inserted by ToDoList after clicking the down-arrow button to show a list of available data. + - {{images:​screenshots:​udt_args.png}} + - In that list is "​Selected Task ID". When clicked, the placeholder "​$(selTID)"​ is inserted into the arguments field. So with the above argument set, at runtime, the value of the current selected task will be substituted,​ maybe #217, and the final command will look something like this. + - + - c:\path\my_script.bat /taskid=217 + - + - Whatever happens in that command is outside the scope of ToDoList and this documentation. It's up to you to find or create scripts or programs which do things that you want, and then to get ToDoList to provide those programs with required data to provide the results you seek. + - + - The following table contains all currently supported placeholders (which should be considered case-Sensitive):​ + + To allow you to pass information about the active tasklist and/or the currently selected task, the '​down-arrow'​ button to the right of the field will display a list of "​placeholder"​ variables for data that ToDoList will substitute when you run the tool.\\ {{images:​screenshots:​udt_args.png}} + The following table contains all currently supported placeholders (which should always be in **lower-case**):​ ^Menu Item^Placeholder^Comments^ ^Menu Item^Placeholder^Comments^ Line 66: Line 47: |Tasklist File Title|$(filetitle)|The filename of the active tasklist without the extension| |Tasklist File Title|$(filetitle)|The filename of the active tasklist without the extension| |Tasklist Filename|$(filename)|The full filename of the active tasklist| |Tasklist Filename|$(filename)|The full filename of the active tasklist| - |Selected Task ID|$(selTID)|ID of the current selected task| + |Selected Task ID|$(seltid)|ID of the current selected task| - |Selected Task Title|$(selTTitle)|Title of the current selected task| + |Selected Task Title|$(selttitle)|Title of the current selected task| - |Selected Task External ID|$(selTExtID)|External ID of the current selected task| + |Selected Task External ID|$(seltextid)|External ID of the current selected task| - |Selected Task Comment|$(selTComments)|Comments of the current selected task| + |Selected Task Comment|$(seltcomments)|Comments of the current selected task| + |Selected Task File Link|$(seltfile)|File Link of the current selected task| + |Selected Task Alloc By|$(seltallocby)|Name of the person who allocated the current selected task| + |Selected Task Alloc To|$(seltallocto)|Name of the person to whom the current selected task is allocated| + |Selected Task Custom Attribute|$(seltcustom,​ var_cust1)|Value of the custom attribute with an ID of '​var_cust1'​ for the current selected task| |User Date|$(userdate,​ var_date1, "Date Prompt",​ default_date)|(see 'User placeholders'​ below)| |User Date|$(userdate,​ var_date1, "Date Prompt",​ default_date)|(see 'User placeholders'​ below)| |User Filepath|$(userfile,​ var_file1, "File Prompt",​ default_path)|(see 'User placeholders'​ below)| |User Filepath|$(userfile,​ var_file1, "File Prompt",​ default_path)|(see 'User placeholders'​ below)| Line 76: Line 61: |Today'​s Date|$(todaysdate)|Date in ISO format| |Today'​s Date|$(todaysdate)|Date in ISO format| - + **User placeholders**\\ - + These placeholders (prefixed by '​user'​) will cause the user (you) to be prompted to enter information when the UDT is executed. This is useful where the information is not known in advance or it frequently changes. User placeholders typically take 3 additional arguments: - **User placeholders** + - Placeholders ​prefixed by '​user'​ will result in the user (you) being prompted to enter information when the UDT is executed. This is useful where the information is not known in advance or it frequently changes. User placeholders typically take 3 additional arguments: + * a unique variable name (eg. var_text1) * a unique variable name (eg. var_text1) - * a prompt string (eg. "Enter your username"​) ​This should be in quotes it is not required. + * an optional ​prompt string (eg. "Enter your username"​) ​which should be quoted - * an optional default ​string ​to display (eg. "​anonymous"​) ​This should be in quotes it is not required. + * an optional default ​value to display (eg. "​anonymous"​) ​which should be quoted - + - Example of a User Placeholder:​ + - + - * -clientname$(usertext, vt1, "Name of client","​Unknown"​) + - * The user selects the UDT from the menu or toolbar. A small prompt window is shown with the title set to the name of the UDT. A textbox is shown with the label "Name of client",​ and a default value of "​Unknown"​. + - * The variable name is completely unimportant. It just needs to be unique of the names used in your UDTs. In this case vt1 is used for variable text, and it's assumed that other fields might get names like vt2, vt3, etc. + - * Note that the placeholder name and the variable name are Not in quotes, but the text data is. + - * The command line will get _-clientname Some name_ with whatever name was entered, or _-clientname Unknown_ if no name is entered. + - + - There are no quotes around the user data for the command-line. That could cause a problem with the program that processes the data. The next example adds quotes: + - + - * -clientname **"​**$(usertext,​ vt1, "Name of client","​Unknown"​)**"​** + - * Note the quote before the dollar sign and at the end. This results in the following:​ + - * -clientname **"​**Unknown**"​** + - + - More examples will be provided in the future, here and/or in a related page. + - + - **Icon Path** + - Each UDT can have its own icon image. The icon can come from a file of any of these types: .ico, .bmp, .png, .jpg. If the path is set to an executable program, the primary icon from that program will be used, as seen for all of the icons in the above examples. Some icon file types were not usable prior to v7.0.10.1, but the types here should be usable in all current releases. + - + - **Run Minimized (checkbox)** + - Runs the tool as a minimized task. Useful for running batch files. + - + - **Delete Tool (button)** + - Deletes the selected tool. + - + - There is no UnDo for this. The only way to recover from an accident here is to click Cancel, which will undo everything for the current preference change session. + - + - **Test Tool (button)** + - This allows you to run the selected tool using the currently selected task for data if the arguments require it. On clicking the button, a "Test Tool" window displays to tell you "Tool '​path\name.ext'​ will be run using the following commandline arguments: '-your args'. It will prompt "Do you want to continue?"​ with a Yes or No button. The arguments will be filled in with currently available data - you will be prompted if required to get user data. + - + - While this is a "​test",​ the UDT will actually be executed, so be sure that's OK before continuing. + - + - *** + - + - + - **Tooltips for UDT toolbar buttons** + - On mouseover of a toolbar icon for a UDT, the tooltip will display the name of the UDT, and if assigned, the [[keyboard-shortcut-prefs|shortcut]] assigned to the UDT. So you don't even need to click the toolbar, you can just use a hotkey to execute your UDT. + - + - The following image shows the tooltip over the fourth icon of the UDT toolbar shown above. Note this icon has a shortcut of Ctrl+T: + - {{images:​screenshots:​udt_tooltip.png}} + - The following image shows the shortcut configuration,​ where under the Tools menu there is a User Defined Tool 4 which has been assigned Ctrl+T. + - {{images:​screenshots:​udt_shortcuts.png}} + - + - *** + - + - ====Tool Examples==== + - The following (rough) examples illustrate possible uses of the tools system and one possible way of solving each challenge. + - + - * Challenge 1 : Display the raw active tasklist in your browser + - - Set the tool path to point to your default browser .exe file. + - - Enter$(pathname) in the arguments field. + - * Explanation:​ All this does is call your browser, passing it the full pathname to the active tasklist. + - + - * Challenge 2 : Render the active tasklist to HTML using an XSL transform + - - Create a batch file containing %1 %2 %3 -o %4 on line 1 and %4 on line 2, and set the tool path to point to this file. + - - Use the following Argument. This is all one line! : + - + - + - "​$(userfile,​ var_msxsl, "Path to Msxsl.exe"​)"​ "​$(pathname)"​ "​$(userfile,​ var_xslfile,​ "Path to Xsl file"​)"​ "​$(folder) \$(filetitle).html"​ + - + - Note that there are two *userfile* placeholders,​ and that fields are surrounded by quotes as described above. + - ​* Explanation:​ + **Icon**\\ - * The first argument prompts ​the user to browse ​to msxsl.exe, which is the rendering engine we will be using. + Click the folder icon to specify a unique image to identify each UDT. The icon can be an image file of these types: ​.ico, .bmp, .png, .jpg. If the path is set to an executable program, ​the primary icon from that program will be used. - * The second argument is just the full pathname ​of the active tasklist which we are going to render. + - * The third parameter prompts the user for the XSL file with which to carry out the transform. + - * The last argument is the output file (just the tasklist pathname with a .html extension). + - * The second line in the batch file acts to display ​the resulting html file in your default browser. + - ​* Challenge 3 : Connect to Bugzilla via the External ID task field + **Run Minimised **\\ - * // Work in Progress. // Details about his example can be found .... ?? + Runs the tool as a minimised ​task. Useful for running batch files. + ----- - * Explanation: This allows you to open Bugzilla with the task's External ID as bug number. + See also: [[user-defined-tools|User Defined Tools]], [[preferences-dialog|Preferences Dialog]], [[tools-menu|Tools Menu]], [[ui-toolbar|Application Toolbar]]