API 2 Template Toolkit

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

You can access the cPanel Template Toolkit system via HTML tags, passing a template file and parameters using the following syntax:

• <?cptt Module::Function(Template File) param=value ?>
  • Module::Function — You will need to replace this value with the module and function you wish to execute.
  • Template File — 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.

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.

When 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 displayed 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 should result in output that resembles the following:

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

Putting it all together

1. Using the example above, you would need to format the <?cptt ?> tag like so:
   • <?cptt Email::listpopswithdisk(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, visiting https://www.example.com:2083/frontend/x3/mail/listpopswithdisk.html should result in the desired output.