Using API 1 Functions

For cPanel & WHM versions before 11.30

The methods explained in this document are supported; however, cPanel tags will eventually be phased out. If you plan to make your application compatible with all future versions of cPanel & WHM, you should use our LiveAPI system whenever possible.

API 1 allows you to perform cPanel functions from your own integrated or external applications. Unlike our API 2 functions, API 1 functions use ordered parameters. Since API 1 functions ordinarily print data to the cPanel interface, they can be useful for creating themes or skins. However, we strongly recommend using the API 2 modules and functions whenever possible.

Calling API 1 Functions

API 1 functions can be called via a cpanel tag. As noted above, these cpanel tags print data to the cPanel interface. cpanel tags use the following format:

<cpanel Module="function( params )">

In the example above:

• Module — Represents the module that holds the function you wish to use.
  • For example: Mysql::
• function — Represents the API function you wish to use.
  • For example: adddb
• params — Represents any parameters you wish to pass the function.
  • For Example: dbname

Note: We also have documentation that tells you how to write your own custom modules.

The examples above would produce this line of code:

<cpanel Mysql="adddb(dbname)">

Suppressing Data Output

In some cases, you may wish to prevent data returned by a function from being displayed in the interface. Mysql::adddb is a good example of a function whose output you would generally want to prevent from printing to the interface, for security reasons.

In order to prevent data from being printed to the cPanel interface, enclose the function in the tag like so:

<!--Module="function()"-->

Sending Input Data to the API 1 Function

There are 2 variables and a useful tag you should be aware of when passing data from page to page: The $FORM and $CPERROR variables and the cpanelif tag.

$FORM is a variable that is populated with GET or POST data passed from the browser to the page. This variable is used by cPanel to transfer important information from page to page. Accessing the information within the variable is done the same way that one could call a hash in Perl.

($FORM{'element'})

As an example, you could have a page called add_mysql-db that would be passed the following information:

• add_mysql_db.html?db=dbname

The page would then contain the following tag:

• <cpanel Mysql="addb( $FORM{'db'} )">

Conditionals

In addition to the cpanel tag, you can also use the cpanelif tag. This tag allows you to utilize some very basic logic within the system. The cpanelif tag allows you to check basic boolean logic to see whether a variable is set. If the check returns true, then whatever is contained between the <cpanelif> tags to the browser.

Note: You cannot nest <cpanelif> tags however you can use the || and && operators to perform multiple checks.

To use the cpanelif tag:

<cpanelif $VAR{''}>

HTML CODE HERE

</cpanelif>

This can be useful when you want to display an error message in the cPanel interface. Error messages are populated into the $CPERROR variable like so:

$CPERROR{$context}

The $context area of this variable is defined on the back-end of cPanel on a per-module basis. Generally, $context will be whatever module you are using.

If, continuing from the example above, you wanted to check for an error message, you would need to use the a code block similar to the following:

<cpanel Mysql="adddb( $FORM{'db'} )">

    <cpanelif $CPERROR{'mysql'}>

      ERROR: <cpanel print="$CPERROR{'mysql'}">

    </cpanelif>

In the current system, success messages are also populated into the $CPERROR variable. In successful cases, you will want to ignore this variable using the following method:

!$CPERROR{'mysql'}

Using cpanelfeature tags

The cpanelfeature tag is a type of tag that will only display data if a feature is enabled in WHM. One example is the following:

<cpanelfeature mysql>
<a href="sql/index.html">Manage MySQL</a>
</cpanelfeature>

These tags can also be used with an exclamation point to display a message if a feature is not available:

<cpanelfeature !mysql>
We see that you do not have MySQL enabled for your account. Click here to order an upgrade.
</cpanelfeature>

Additional Resources

• The LiveAPI System — The LiveAPI system is the latest and greatest method for accessing and running cPanel's API functions.
• API 1 modules and functions — This is a set of reference documents for API 2 modules and functions.