cPanel API2 Tags

This article documents the usage of cPanel API2 tags in relation to the cPanel interface. These tags can be used in files in the /usr/local/cpanel/base/frontend/ docroot.

Synopsis

<?cp Module::function(%, def) output=output_list || 'message' ?>

Description

API2 tags allow you to access functions within cPanel's core code. Using these functions, you can output information. API2 tags provide a way to access raw variables. An API2 tag will search for all instances of a variable and output all of them. For example, if you have 10 different branding packages, you would only need one API2 tag to output the information requested from every package.

• Module
  
  • Name of the specific Module to access.
• function
  
  • Name of the specific function to access.
• %
  
  • The % symbol is used to retrieve a variable from the function. It must have a matching definition.
• def
  
  • The definition will tell the API2 tag which variable it should output. See the specific function's documentation for a list of variable that can be outputted.
• output
  
  • Contains a desired output indicator, i.e. display
• outputlist
  
  • Pipe delimited list of input variables. See the specific function's documentation for a list of variables that can be inputted.

• num (integer)
  
  • The *num variable can always be added to the output list to ouput the parity of the number of the location in the array where each group of values for an item exists. (even or odd)
• ^
  
  • Using a ^ before a variable will URI encode the value of that variable.
• ||
  
  • Using || will output whatever trails || if the function fails or no data is outputted.
• +
  
  • Using + before a variable will return checked if the variable is defined or equal to 1 or nothing if the variable is undefined or equal to 0.

• message
  
  • If the tag returns null, message will be returned instead.

Examples

<?cp Branding::showpkgs( % % ,pkg,previewimg ) ?>

The above API2 tag would output the name of all branding packages, and the URLs of their preview images.

<?cp Branding::showpkgs(i [tr] [td align=``center'']%[/td] [td align=``center''][a href=``%''][img src=``previewicon.jpg'' /][/a][/td] [/tr] ,pkg,previewimg) || '[tr][td colspan=``2'']$LANG{'NoPackages'}[/td][/tr]' ?>

The above API2 tag would output a table row containing 2 columns. The first column would hold the name of a branding package, the second would contain an imag which links to the location of the preview image for that package. If no branding packages were present, the tag would output a table row and column containing the NoPackages language tag.

Notes

When using API2 tags, other <cpanel> tags function different inside the API2 tag. Those tags and their modified usage are listed below:

• <cpanel langprint=``''>
  
  • The <cpanel langprint=``''> tag must be used as $LANG{''} inside an API2 tag.
• ?
  
  • The ? tag must be used as $CPDATA{''} inside an API2 tag.
• Usage of other characters
  
  • Usage in API 2 / Character [[ = ( ]] = ) [ = < ] = > \{colon} = : \{comma} = , \{leftbracket} = ( \{rightbracket} = )

Copyright