### Site Tools

user-defined-tools

# Differences

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

 user-defined-tools [2017/07/26 00:22]admin user-defined-tools [2017/07/26 02:04] (current)admin Both sides previous 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 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 Line 1: Line 1: ====== User-Defined Tools ====== ====== User-Defined Tools ====== - 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"​. + To extend its functionality ToDoList lets you configure tools to perform action and operations that are outside the scope of ToDoList as a generalised task manager. + + A User-Defined Tool (UDT) is a template which specifies ​a tool (application,​ script or batch file) together with additional ​command-line ​parameters ​and information ​on how to display ​the tool in ToDoList'​s ​user interface. ====What can be done with a UDT?==== ====What can be done with a UDT?==== * Reports can be generated, emailed, or faxed. * Reports can be generated, emailed, or faxed. Line 7: Line 10: * ERP systems can incorporate the data into schedules. * ERP systems can incorporate the data into schedules. * Data can be sent via web service to remote systems. * Data can be sent via web service to remote systems. + * Task values can be copied from one attribute to another within ToDoList. + * Task values can be modified within ToDoList. - In the above screenshot, ​a few of the functions seen in the grid include: + ====Creating ​a UDT==== - * 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. + Note: For detailed information on configuring a UDT see ([[user-defined-tools-prefs|Menu Bar > Tools Menu > Preferences > User Defined Tools]]. - 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: 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"​ + c:​\path\to\program\name.exe -switch1 -switch2 "​data1"​ -switch3 ​"​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 switches and data are whatever is required for the 'name.exe' ​program to work. These are the tool's '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: + **Arguments**\\ - + A set switches and/or data that will be passed ​to the tool via its 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: - **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) /​taskid=$(selTID) Line 53: Line 36: 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. 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):​ + **User ​Placeholders**\\ - + - + - + - ^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: 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: Line 95: Line 56: * Note the quote before the dollar sign and at the end. This results in the following: * Note the quote before the dollar sign and at the end. This results in the following: * -clientname **"​**Unknown**"​** * -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==== ====Tool Examples====