Differences
This shows you the differences between the selected revisions of the page.
| 2016-04-01 | 2016-05-24 | ||
| local side is default (martin) | 5.8.3 Extensions are configurable. (martin) | ||
| Line 30: | Line 30: | ||
| | ''@homepage'' | A ''%%http://%%'' or ''%%https://%%'' URL to the web page of the extension. Not used. | | | ''@homepage'' | A ''%%http://%%'' or ''%%https://%%'' URL to the web page of the extension. Not used. | | ||
| | ''@source'' | A ''%%http://%%'' or ''%%https://%%'' URL to the extension file itself. Not used. In future versions, it can be used to check for extension updates (with use of the ''@version'' key). | | | ''@source'' | A ''%%http://%%'' or ''%%https://%%'' URL to the extension file itself. Not used. In future versions, it can be used to check for extension updates (with use of the ''@version'' key). | | ||
| + | | ''@option'' | Defines a user-configurable [[#option|option of the extension]]. \\ To define multiple options, use multiple ''@option'' entries on separate lines. | | ||
| + | | ''@optionspage'' | URL of a help page for the options dialog. If missing, the ''@homepage'' is used instead. | | ||
| ===== Example ===== | ===== Example ===== | ||
| Line 44: | Line 46: | ||
| For full examples, see the official and optional extensions below. | For full examples, see the official and optional extensions below. | ||
| + | |||
| + | ===== Options ==== | ||
| + | |||
| + | The extension can have user-configurable options, which are defined using ''@option'' metadata. | ||
| + | |||
| + | The ''@option'' entry has the following parameters: | ||
| + | |||
| + | <code> | ||
| + | @option <name> <type> "<caption>" <default> <additional ...> | ||
| + | </code> | ||
| + | |||
| + | ^ Parameters ^ Description ^ | ||
| + | | ''name'' | Unique name of the option. In the custom command, any ''%name%'' string will get replaced with configured value of the option. \\ For options dialog control types ''label'' and ''link'' use ''-'' (dash), as these have no value. | | ||
| + | | ''type'' | Type of the option or options dialog control. \\ Supported types are: ''textbox'', ''file'', ''dropdownlist'', ''combobox'', ''checkbox'', ''label'', ''link'' | | ||
| + | | ''caption'' | Caption of the options dialog control representing the option. | | ||
| + | | ''default'' | Default value of the option. | | ||
| + | | ''additional'' | Additional parameters specific to the option type. See below. | | ||
| + | |||
| + | Details about individual option types: | ||
| + | |||
| + | ^ Type ^ Description ^ | ||
| + | | ''textbox'' | Plain text edit box. The ''default'' defines the default text value. The value of the option equals the value entered into the edit box. | | ||
| + | | ''file'' | File selector. The ''default'' defines the default path. Environment variables in the default value are resolved. The value of the option equals the path selected. | | ||
| + | | ''dropdownlist'' | Dropdown menu. The ''additional'' parameters define a list of possible values with syntax ''[value=]text''. The ''text'' will be displayed in the dropdown menu. The value of the option equals the ''value'' of the selected item. If the ''value='' part is missing, the ''text'' is used as a value. The item with ''value'' equal to the ''default'' will be selected by default. | | ||
| + | | ''combobox'' | Combo box. The ''additional'' parameters define a list of possible values with syntax ''[value=]text''. The ''text'' will be displayed in the dropdown menu. The value of the option equals the ''value'' of the selected item. If the ''value='' part is missing, the ''text'' is used as a value. If a custom text is entered, the value equals to the text. The item with ''value'' equal to the ''default'' will be selected by default. If no such item exists, the ''default'' is used as the default custom text. | | ||
| + | | ''checkbox'' | Checkbox. Two optional ''additional'' parameters define values of the option, when the checkbox is checked and not checked, respectively. If the ''default'' equals to the first additional parameter, the checkbox is checked by default. | | ||
| + | | ''label'' | Text label. Just a plain text label displayed on the options dialog. \\ This "option" has no value. Use ''-'' for the ''name'' parameter. | | ||
| + | | ''link'' | Hyperlink. Either use URL for ''caption'', or use link text for the ''caption'' and URL for the ''default'' parameter. \\ This "option" has no value. Use ''-'' for the ''name'' parameter. | | ||
| + | |||
| + | For example the following entries: | ||
| + | |||
| + | <code powershell> | ||
| + | # @option - label "Example extension options" | ||
| + | # @option - link https://winscp.net/eng/docs/extension#options | ||
| + | # @option Mask textbox "&File mask" "*.txt; *.html" | ||
| + | # @option SearchType dropdownlist "Search for:" -files -files="Files" -dirs="Directories" -both="Files and Directories" | ||
| + | # @option LogFile file "&Log File:" "%APPDATA%\mylog.log" | ||
| + | # @option Pause checkbox "&Pause at the end" -pause -pause | ||
| + | </code> | ||
| + | |||
| + | Produce this options dialog: | ||
| + | |||
| + | &screenshotpict(extension_options) | ||
| + | |||
| + | When the option names are used in a command like: | ||
| + | |||
| + | <code> | ||
| + | example.exe -Mask="%Mask%" %SearchType% -Log="%LogFile%" %Pause% | ||
| + | </code> | ||
| + | |||
| + | The resulting command (with the options configured as shown on the screenshot, i.e. with the default options) will be: | ||
| + | |||
| + | <code> | ||
| + | example.exe -Mask="*.txt; *.html" -files -Log="C:\Users\username\AppData\Roaming\mylog.log" -pause | ||
| + | </code> | ||
| ===== [[official]] Official Extensions ===== | ===== [[official]] Official Extensions ===== | ||