cPanel API 2 - Deprecated cPanel Tag Usage

Warning:

The cPanel API 2 system is deprecated. We strongly recommend that you use UAPI instead of cPanel API 2.

Introduction

Warning:

cPanel tags are deprecated. We provide this example to help developers move from the old cPanel tag system to our LiveAPI system. We strongly recommend that you only use the LiveAPI system to call the cPanel APIs.

The deprecated cPanel tag system used <?cp ?> HTML tags to call cPanel API 2.

Basic usage

To call cPanel API 2 with the cPanel tag system, use the following format:

<?cp Module::function (
     template,
     returns,
     returns
     )
          parameter="value",
          parameter="value",
          parameter="value",
?>

Note:

Line breaks are optional.

This example uses the following variables:

Variable	Description	Possible values	Example
`Module`	The module.	The name of a cPanel API 2 module.	`Email`
`function`	The function name.	A cPanel API 2 function in the module.	`addpop`
`template`	Markup language that defines how the function's output displays.	For more information, read the Templates section below.	`%[br /]`
`returns`	A comma-separated list of return parameters, to limit the function's output. To filter returns to only include the output parameters that you need, list the desired output parameters.	Any of the function's return parameters. See the function's documentation for a list of possible return parameters.	`reason,result`
`parameter`	The input parameters to pass to the function.	Any of the function's input parameters.	`domain`
`value`	The input parameter's value.	See the function's documentation.	`example.com`

Templates

You may receive output that is similar to the following example of the Email::listlists function's lists parameter:

mailinglist1@example.commailinglist2@example.commailinglist3@example.com

To add HTML code to this output for display purposes, supply a template when you call the function.

cPanel tag templates use HTML code, but replace the HTML tags' angled brackets ( <> ) with square brackets ( [] ).
To represent output data, use a percent character ( % ). If you return multiple output parameters, data from each parameter displays in the same order as the return parameters in your function call. (For example, the first % represents the first parameter that you list as a return.)

For example, to insert a line break (<br />) between each item, supply the following template:

%[br /]

This template code displays each list on a separate line:

mailinglist1@example.com
mailinglist2@example.com
mailinglist3@example.com

Special characters in templates

Replace special characters with the appropriate replacement tags:

Character	Replacement tag
`:`	`\{colon}`
`,`	`\{comma}`
`[`	`\{leftbracket}`
`]`	`\{rightbracket}`
`(`	`\{leftparenthesis}`
`)`	`\{rightparenthesis}`
`%`	`\{percent}`

Hash and array values in templates

To represent output data that is in the second layer of a hash, use the following format, where dblist is the hash name and db is the parameter within that hash:

<?cp MysqlFE::listusers(
     % has access to the following databases:[br/] %,
     user,
     dblist:: &nbsp;&nbsp;&nbsp; ${db} :,
     )
?>

This code returns the following output:

cpuser_dbuser has access to the following databases:
   cpuser_dbname
   cpuser_db2name

Example

The following code calls the Email::listpopswithdisk function, returns the email and humandiskquota parameters, and displays that output with parentheses around the humandiskquota value:

<?cp Email::listpopswithdisk (
     % \{leftparenthesis} % \{rightparenthesis}[br /],
     reason,
     result
     )
          domain="example.com",
          email="user",
          password="12345luggage",
          quota="100",
?>

This function returns data in the following format:

user@example.com (250MB)
user2@example.com (125MB)
user3@example.com (100MB)

The $FORM variable: Pass POST and GET data

To pass POST and GET data in cPanel tags, use the $FORM variable. This variable is a hash that the cpsrvd daemon parses. It contains all of the FORM and GET data that the system passes to a cPanel interface.

For example, you might call a page with the following POST and GET parameters:

addpop.html?username=test&pass=testing123&domain=testdomain.com&quota=10

Pass this information to cPanel API 2 in the following manner:

<?cp Email::addpop(
     %,
     reason
     )
    domain=$FORM{'domain'},
    email=$FORM{'username'},
    password=$FORM{'pass'},
    quota=$FORM{'quota'},
?>