Each webspace has buttons available from the Plesk’s UI. For example, Mail settings, File manager, etc. To get the list of all such buttons, send the cform_buttons_list request packet to Plesk.

Request Packet Structure

A request XML packet getting the list of subscription buttons includes the cform_buttons_list operation node:

<packet version="1.6.3.0">
<webspace>
   <cform_buttons_list>
   ...
   </cform_buttons_list>
</webspace>
</packet>

The cform_buttons_list node does not have a separate data type, it is nested within the complex type (domain_input.xsd). The cform_buttons_list node has the following graphics representation:

image 33922

Note: The interactive schema navigator for all request packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_input.svg.

  • filter, required

    It indicates subscriptions whose buttons are requested. Data type: DomainFilterType (domain_input.xsd). To see the structure of this node, proceed to topic Available Filters.

Response Packet Structure

The cform_buttons_list node of the response packet is structured as follows:

image 33925

Note: The interactive schema navigator for all response packets is available here: http://plesk.github.io/api-schemas/1.6.8.0/agent_output.svg.

  • result, optional

    It wraps the result of the requested cform_buttons_list operation. It can be missing if some error occurs before the validation starts. Data type: resultFilterType (common.xsd).

  • status, required

    It returns the execution status of the cform_buttons_list operation. Data type: string. Allowed values: ok | error.

  • errcode, optional

    It is used to return an error code if the cform_buttons_list operation fails. Data type: unsignedInt.

  • errtext, optional

    Can be used to return an error message if the cform_buttons_list operation fails. Data type: string.

  • filter-id, optional

    If supported, it is always present and used to return the parameter by which the subscription was filtered by in the request packet. Data type: anySimple.

  • id, optional

    Returns the identifier of the subscription whose buttons are requested. It is missing if the request packet fails before the validation on the server side. Data type: integer.

  • button, optional

    It returns a collection of parameters that describe the button (see the details below). It is missing if the request packet fails before the validation on the server side. Data type: buttonDataType (plesk_common.xsd).

Buttons are described by complex type buttonDataType (plesk_common.xsd) as follows:

image 33926

  • The code, required

    It returns the identifier of the button. Data type: string.

  • The type, required

    It specifies the button type. Data type: string. Allowed values: link_button (a typical link that references some URL) | comm_button (a typical button whose click event calls a related event handler).

  • The name, required

    It contains the localized button name displayed in a home page. Data type: string.

  • The name_id, required

    It specifies the localization key associated with the button. Data type: string.

  • The group_name, required

    It returns the localized name of the group containing the button. Data type: string.

  • The group_name_id, required

    It specifies the localization key of the group name. Data type: string.

  • The href, required

    It returns the URL referenced by the button. Data type: string.

  • The js_onclick, optional

    It returns the JavaScript code executed at the button click. Data type: text (string, white spaces are allowed ).

  • The enabled, required

    It indicates whether the button in enabled. If true, the button is active and can be used. Data type: Boolean.

  • The new_window, optional

    It indicates whether a new window should be opened in the browser when the button is clicked. Data type: Boolean.

  • The tabindex, optional

    It returns the button’s tabulation index. Data type: integer. Default value: 0.

  • The conhelp_id, optional

    It specifies the localization key of the context help message associated with the button. Data type: string.

  • The conhelp, optional

    It returns a context help message displayed in the Help section of the Plesk navigation pane when pointing at the button with a mouse. Data type: text (string, white spaces are allowed ).

  • The icon_url, optional

    It specifies the location of the button’s icon. Data type: string.

Samples

Getting buttons under Plesk Administrator

A sample request packet looks as follows:

<packet>
<webspace>
<cform_buttons_list>
   <filter>
      <id>1324</id>
   </filter>
</cform_buttons_list>
</webspace>
</packet>

Response:

<packet version="1.6.3.0">
<webspace>
<cform_buttons_list>
   <result>
      <status>ok</status>
      <filter-id>1324</filter-id>
      <id>1324</id>
        <button>
          <code>MAIL_DOMAIN_SETTINGS_BUTTON</code>
          <type>link_button</type>
          <name>Mail settings</name>
          <name_id>mail_domain_settings</name_id>
          <group_name>Mail</group_name>
          <group_name_id>mail</group_name_id>
          <href>/plesk/client@1/domain@13/mail/properties/?context=dashboard</href>
          <enabled>true</enabled>
          <new_window>false</new_window>
          <conhelp>Configure mail services on your domain.</conhelp>
          <icon_url/>
        </button>
   </result>
</cform_buttons_list>
</webspace>
</packet>

To filter some subscriptions by id and others by name, use different operation nodes:

<packet>
<webspace>
<cform_buttons_list>
   <filter>
      <id>124</id>
   </filter>
</cform_buttons_list>
<cform_buttons_list>
   <filter>
      <name>techservice.co.uk</name>
   </filter>
</cform_buttons_list>
</webspace>
</packet>

To get buttons of all subscriptions registered in Plesk, the following packet can be used:

<packet>
<webspace>
<cform_buttons_list>
   <filter/>
</cform_buttons_list>
</webspace>
</packet>