### Site Tools

user-defined-tools

# Differences

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

 user-defined-tools [2016/09/01 10:53]127.0.0.1 external edit user-defined-tools [2017/07/26 00:22]admin 2017/07/26 02:04 admin 2017/07/26 00:22 admin 2017/07/26 00:19 admin [What can be done with a UDT?] 2016/09/07 12:15 admin 2016/09/02 10:46 admin 2016/09/01 10:53 external edit Next revision Previous revision 2017/07/26 02:04 admin 2017/07/26 00:22 admin 2017/07/26 00:19 admin [What can be done with a UDT?] 2016/09/07 12:15 admin 2016/09/02 10:46 admin 2016/09/01 10:53 external edit Last revision Both sides next revision Line 1: Line 1: - A User-Defined ​Tool, or UDT, is described under menu > Tools > Preferences [[user-defined-tools-prefs|User Defined Tools]]. + ====== ​User-Defined Tools ====== - // Work in Progress. // _Pull some of the general description material from the preference page to separate ​the prefs details from general ​UDT concepts._ + 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"​. + ====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: + * 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. + + 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:​ + {{images:​screenshots:​tools_udts.png}} + + + ====Creating a UDT==== + 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. + + 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: + + **Tool Name** + 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. + + **New Tool (button)** + This is the first step to create a new UDT. Enter the name that you want to appear on the Tools Menu. + {{images:​screenshots:​new_tool.png}} + + **File Path** + Click the folder icon to browse to the application,​ batch file, or script that you wish to run. + {{images:​screenshots:​udt_edit.png}} + + **Arguments** + 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) + + 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):​ + + + + ^Menu Item^Placeholder^Comments^ + |ToDoList Pathname|$(todolist)|Full path to the ToDoList executable| + |Tasklist Pathname|$(pathname)|Full path to the active tasklist| + |Tasklist Folder|$(folder)|Full path to the folder containing the active task list| + |Tasklist File Title|$(filetitle)|The filename of the active tasklist without the extension| + |Tasklist Filename|$(filename)|The full filename of the active tasklist| + |Selected Task ID|$(selTID)|ID 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 Comment|$(selTComments)|Comments of the current selected task| + |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 Folder|$(userfolder,​ var_folder1,​ "​Folder Prompt",​ default_folder)|(see 'User placeholders'​ below)| + |User Text|$(usertext,​ var_text1, "Text Prompt",​ default_text)|(see 'User placeholders'​ below)| + |Today'​s Date|$(todaysdate)|Date in ISO format| + + + + **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 prompt string (eg. "Enter your username"​) This should be in quotes it is not required. + * an optional default string to display (eg. "​anonymous"​) This should be in quotes it is not required. + + 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:​ + * The first argument prompts the user to browse to msxsl.exe, which is the rendering engine we will be using. + * 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 + * // Work in Progress. // Details about his example can be found .... ?? + + * Explanation:​ This allows you to open Bugzilla with the task's External ID as bug number.