# custombutton: Custom Buttons

The `custombutton` utility is used to create custom buttons and manage their properties (interface location, button names, URLs, context help messages, and other parameters) through CLI.

Custom buttons of the following types can be created and managed by using this utility:

- custom buttons pointing to a URL
- custom buttons linked to site applications or Plesk extensions

## Usage

    custombutton <command> [
    <option_1> [<param>]
    [<option_2> [<param>]]
    ... [<option_N> [<param>]]
    ]

## Example 1

The following command creates the custom button Statistics that opens URL http://example.com/site-statistics, places the custom button on domain administration pages, includes domain ID#, domain name, and client ID# in browser requests generated by clicking on the button, sets the context help message for the button as Click to go to site-statistics, and makes the button available in control panels of all domain users.

    plesk bin custombutton --create -text Statistics -url http://example.com/site-statistics -place domain -url_comp dom_id,dom_name,cl_id -conhelp "Click to go site-statistics" -public true

## Example 2

The following command creates custom button named osCom linked to site application osCommerce installed on domain example.com, and accessible at URL http://example.com/osCommerce, and sets the context help message for the button as Click to open osCommerce.

    plesk bin custombutton --create -text osCom -url http://example.com/osCommerce -siteapp-link -siteapp-domain example.com -siteapp-name osCommerce -conhelp "Click to open osCommerce"

## Commands

Command | Parameter | Description | Example
--- | --- | --- | ---
`--create` or `-c` |  | Creates a new custom button. Requires the `-text` and `-url` options. | To create the new custom button Statistics (pointing to URL http://example.com/site-statistics) and print its Plesk database ID:
    plesk bin custombutton --create -text Statistics -url http://example.com/site-statistics -print-id
or
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics -print-id
`--info` or `-i` | `<id#>` | Displays properties of a custom button with the specified ID number. | To view properties of a custom button which Plesk database ID is 14:
    plesk bin custombutton --info 14
or
    plesk bin custombutton -i 14
`--remove` or `-r` | `<id#,id#,...>` | Deletes one or more custom buttons with the specified ID numbers. | To delete the custom buttons whose ID numbers are 4 and 5:
    .. code-block:: guess
plesk bin custombutton –remove 4,5 or
    plesk bin custombutton -r 4,5
`--list` or `-l` |  | Displays a list of all custom buttons. | To view the list of all custom buttons:
    plesk bin custombutton --list
or
    plesk bin custombutton -l
`--help` or `-h` |  | Displays help on the use of the utility | To view help on the use of the utility:
    plesk bin custombutton --help
or
    plesk bin custombutton -h
`--man` or `-m` |  | Displays detailed help on the use of the utility with examples | To view detailed help with examples on the use of the utility:
    plesk bin custombutton --man
or
    plesk bin custombutton -m

## Options

Option | Parameter | Description | Example
--- | --- | --- | ---
`-owner` | `admin|<user_login_name>|<domain_name>` | Assigns ownership of a custom button to a Plesk client. Is `admin` by default. | To set the client with login name JDoe the owner of custom button Statistics to be created:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics -owner JDoe
`-sort_key` | `<int>` | Sets the custom button appearance priority. (The lower is the number - the higher is priority.) Is `100` by default. | To set the Statistics appearance priority on a Plesk page to 3:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics -sort_key 3
`-place` | `client|domain|domain-properties|navigation|admin|admin-settings|reseller|reseller-settings` | Sets a custom button location. The following locations are available: The Home tab in the Control Panel, visible to the hosting service customers and their users who are allowed to log in to the Control Panel This can be done using the `client` option. The Websites & Domains tab in the Control Panel, visible to the hosting service customers and their users who are allowed to log in to the Control Panel. This can be done using the `domain` option. The Home page in the Server Administration Panel, visible only to the administrator and to the users logged in under additional administrator accounts. This can be done using the `admin` option. The Home page in the Server Administration Panel, visible only to resellers. This can be done using the `reseller` option. The Tools & Settings page in the Server Administration Panel, visible only to the administrator and to the users logged in under additional administrator accounts. This can be done using the `admin-settings` option. The Tools & Utilities page in the Server Administration Panel, visible only to resellers. This can be done using the `reseller-settings` option. The `client` option is selected by default. | To set the custom button Statistics location to administrator’s Home page:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics -place admin
`-text` | `<button_label>` | Specifies the text accompanying a custom button. Required with the `--create`. | To set text accompanying the custom button to Statistics:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics
`-url` | `<URL>` | Specifies the URL to which a custom button to be created will point. Required with the `--create` when custom buttons pointing to URLs are created. Requires `-text` option. | To set the URL to which a custom button Statistics will point to example.com/site-statistics:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics
`-url_comp` | `dom_id|` `dom_name|` `ftp_user|` `ftp_pass|` `cl_id|` `cname|` `pname|` `email` | Specifies various parameters to be included with the custom button’s URL in browser requests. The following parameters can be included: `dom_id` - domain ID `dom_name` - domain name `ftp_user` - FTP user name `ftp_pass` - FTP user password `cl_id` - client ID `cname` -client’s company name `pname` - client’s contact name `email` - client’s email | To include domain ID, domain name, and client ID in the browser requests generated by using custom button Statistics:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics -url_comp dom_id,dom_name,cl_id
`-conhelp` | `<text>` | Specifies text of a contextual help message associated with a custom button. | To set the context help tip for the custom button Statistics to “Click to go to site-statistics”:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics -conhelp "Click to go to example.com/site-statistics"
`-file` | `<path>` | Specifies path to the image file that will be used as a custom button icon. | To set file Stat.gif as the custom button Statistics icon:
    plesk bin custombutton -c -text CustomButton -url http://example.com -file /usr/local/psa/Images/PleskInterface/ButtonImage.gif
`-public` | `true|false` | Specifies whether a custom button appears in control panel interfaces of users subordinate to the custom button’s owner. Is `false` by default. | To display custom button Statistics that has domain administrator home page location in control panel interfaces of all users on this domain:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics -place domain -public true
`-internal` | `true|false` | Specifies whether a custom button’s URL is opened in Plesk own frame or in the new window. Is `false` by default. | To enable opening the custom button Statistics URL in Plesk own frame:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics -place domain -internal true
`-noframe` | `true|false` | If a custom button leads to a Plesk extension or web app, this option specifies how the extension/app should be displayed on the Plesk page: in a frame (false) or as a part of the Plesk GUI (true). | To create the custom button My_App to a website app which should be opened as a part of the Plesk GUI:
    plesk bin custombutton -c -text My_App -url http://example.com/my_app -place domain -internal true -noframe true
`-print-id` |  | Prints the Plesk database ID of a created custom button. | To create the custom button Statistics to open example.com/site-statistics and print its Plesk database ID:
    plesk bin custombutton -c -text Statistics -url http://example.com/site-statistics -print-id