Introduction
UAPI modules use the Cpanel::Result object to return messages and data. When you write a custom UAPI module, you must use this object for your functions to operate correctly.
Required $result declaration
Before you can use Cpanel::Result methods, you must declare the $result variable, as in the following example:
|
1
2
3
|
sub custom_function { my ( $args, $result ) = @_;} |
This example declares the $args and $result variables, and assigns values from the input parameters that the function received.
Important:
We strongly recommend that you begin all custom functions with the my ( $args, $result ) = @_; declaration. Functions that do not perform this action will experience errors.
Note:
If your return data contains any strings with Unicode characters that are binary encoded, and that display on a cPanel interface, you will receive a Wide Character warning. To resolve this, use the following code to encode your strings:
|
1
2
|
use Encode qw(encode);$result->data( encode( 'utf-8', $successful_data ) ); |
For more information about the Cpanel::Args object, read our Cpanel::Args Object documentation.
Methods
The Cpanel::Result object includes methods that you can use to return messages and data through UAPI.
$result->data()
This method stores data to include in the function's return data. Use this method to return the data hash for custom functions.
You can use the data() method to store individual values. However, we recommend that you instead use this method to store hashes of named parameters.
$result->data(@array_of_data); |
In this example, the data method stores an array of function data. This data will appear in the data hash in the function's metadata.
Important:
Do not use this method more than once in each function. If a function uses the data() method a second time, it will overwrite all of the data that it previously stored.
$result->error()
This method stores an error message to include in the function's return data. Use this method to return error messages in custom functions.
If you call this method multiple times in the same function, it appends the new error messages to the list that it previously stored.
$result->error('This is an error message about the function.'); |
In this example, the error method stores an error message. This message will appear in the errors hash in the function's metadata.
Warning:
This method attempts to localize any message that a function passes to it.
- For this reason, do not attempt to interpolate data into a string that you pass to this method.
- The strings that you use with this method must be exact string literals.
To include interpolated data in an error message, use the raw_error() method.
$result->raw_error()
This method stores an error message to include in the function's return data. Use this method to return error messages in custom functions.
If you call this method multiple times in the same function, it appends the new error messages to the list that it previously stored.
$result->raw_error('This is an error message about the [_1].', '$function'); |
In this example, the raw_error method stores an error message. This message will appear in the errors hash in the function's metadata.
Note:
This method does not attempt to localize strings, and therefore is safe to use with interpolated data.
$result->message()
This method stores a message to include in the function's return data. Use this method to return messages of success, or additional function information.
If you call this method multiple times in the same function, it appends the new messages to the list that it previously stored.
$result->message('This is a message of success about the function.'); |
In this example, the message method stores a success message. This message will appear in the messages hash in the function's metadata .
Warning:
This method attempts to localize any message that a function passes to it.
- For this reason, do not attempt to interpolate data into a string that you pass to this method.
- The strings that you use with this method must be exact string literals.
To include interpolated data in an error message, use the raw_message() method.
$result->raw_message()
This method stores a message to include in the function's return data. Use this method to return messages of success, or additional function information.
If you call this method multiple times in the same function, it appends the new messages to the list that it previously stored.
$result->raw_message('This is a message of success about the function.'); |
In this example, the raw_message method stores a success message. This message will appear in the messages hash in the function's metadata.
Note:
This method does not attempt to localize strings, and therefore is safe to use with interpolated data.
$result->metadata()
This method stores metadata to include in the function's return data.
$result->metadata('metadata_var', '1'); |
This example adds the metadata_var parameter to the hash of metadata, with a value of 1. This message will appear in the metadata hash in the function's metadata .
Note:
In most instances, custom modules will not need to use this method.