Calling API1 Functions

cPanel uses the API1 system to add, modify, or delete data on the server. Since API1 functions ordinarily print data to the cPanel interface, they're particularly useful for creating themes or skins.

Calling API1 Functions

API1 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 )">

• 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 API1 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>