API 2 Template Toolkit

The cPanel Template Toolkit is a template-driven parser for API2 calls. The toolkit uses the Template Toolkit Perl library to format a response from an API2 function. The cPanel Template Toolkit provides an even simpler interface for accessing cPanel's API2 functions, resulting in code that is easier to write.

Syntax

There are two ways you can access the cPanel Template Toolkit system through HTML tags: with an API function or without an API function.

Accessing the Template Toolkit system using an API function

You can pass a template file and your parameters to an API function using the following syntax:

<?cptt Module::Function(TemplateFile) param=value ?>

• Module::Function — You will need to replace this value with the module and function you wish to execute.
• TemplateFile — You will need to replace this value with the Template Toolkit file you wish to process.
• param=value — You will need to replace this value with any parameters you wish to pass to the API2 call.

Accessing the Template Toolkit system without using an API function

You can use a template file without using an API function or parameters:

<?cptt TemplateFile ?>

• TemplateFile — You will need to replace this value with the Template Toolkit file you wish to process.

The Template File

The template file needs to reside in the same directory as the HTML file that contains the <?cptt ?> tags. By default, when a <?cptt ?> tag is executed, the tag assumes the document root is /usr/local/cpanel/base/frontend/x3. For example, if you place a template file at /usr/local/cpanel/base/frontend/x3/cron/cron.tmpl, you will need to pass cron/cron.tmpl in the <?cptt ?> tag.

Writing Your Template File

The template file is formatted like a normal Template Toolkit file. The Template Toolkit manual contains all of the information you will require to understand the cPanel Template Toolkit's syntax.

If you pass data to the Template Toolkit, the toolkit will return a hash with a return_ key. This key contains all of the data returned by the API function, contained within XML nodes.

For example, the Email::listpopswithdisk API2 call would return something similar to the following response:

<data>
	<_diskquota>1048576000</_diskquota>
	<_diskused>438382314</_diskused>
	<diskquota>1000</diskquota>
	<diskused>418.07</diskused>
	<diskusedpercent>41</diskusedpercent>
	<diskusedpercent20>40</diskusedpercent20>
	<domain>example.com</domain>
	<email>user1@example.com</email>
	<humandiskquota>1000 MB</humandiskquota>
	<humandiskused>418.07 MB</humandiskused>
	<login>user1@example.com</login>
	<txtdiskquota>1000</txtdiskquota>
	<user>user1</user>
</data>
<data>
	<_diskquota/>
	<_diskused>0</_diskused>
	<diskquota>unlimited</diskquota>
	<diskused>0</diskused>
	<diskusedpercent>0</diskusedpercent>
	<diskusedpercent20>0</diskusedpercent20>
	<domain>example.com</domain>
	<email>user2@example.com</email>
	<humandiskquota>None</humandiskquota>
	<humandiskused>None</humandiskused>
	<login>user2@example.com</login>
	<txtdiskquota>unlimited</txtdiskquota>
	<user>user2</user>
</data>

As you can see from the example, return_ is an array of hashes that contain data within each node in the XML container. You may also view this information by using an API call tracer. The call tracer will return the literal data structure passed to the <?cptt ?> tag in the return_ key.

In the example above, if you wished to create an interface that displays email addresses and their corresponding disk space usage information, you would use the following in your template file:

[% FOREACH account = return_ %]
<strong>[% account.email %]</strong> - [% account.humandiskused %]<br />
[% END %]

The example above will result in output that resembles the following:

user1@example.com - 418.07 MB
user2@example.com - None

Putting it all together

1. Using the examples above, you would need to format the <?cptt ?> tag as follows:
   • With an API function and parameters — <?cptt Email::listpopswithdisk(mail/listpopswithdisk.tmpl ) ?>
   • Without an API function and parameters — <?cptt mail/listpopswithdisk.tmpl ?>
2. Place the <?cptt ?> tag in the following file:
   • /usr/local/cpanel/base/frontend/x3/mail/listpopswithdisk.html
3. Take the template from the example above and place it in the following directory, with the appropriate file name:
   • /usr/local/cpanel/base/frontend/x3/mail/listpopswithdisk.tmpl

In this scenario, you will see the desired output when you visit https://www.example.com:2083/frontend/x3/mail/listpopswithdisk.html