Introduction
Warning:
In cPanel & WHM version 11.30 and later, cPanel tags are deprecated. This example is present in order to help developers move from the old cPanel tag system to our LiveAPI.
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. |
|
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 theTemplates 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:: ${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"a=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'}, ?>