Page tree
Skip to end of metadata
Go to start of metadata

Introduction


You can use special variables to display UAPI output data in multiple pages (pagination).

 When you use pagination, the function's output's metadata includes the following hash of pagination control information:


paginate":{
"total_pages":1,
"total_results":1,
"current_page":1,
"results_per_page":100,
"start_result":"1"
} 

Note:

You can test UAPI functions with pagination in cPanel's API Shell interface (Home >> Advanced >> API Shell). Click Show paginate/Filter/Paginate Options to display pagination options.

Pagination variables

UAPI pagination uses four basic variables:

VariableTypeDescriptionPossible values
api.paginateBooleanWhether to enable pagination.
  • 1 — Enable pagination.
  • 0 — Disable pagination.
api.paginate_startintegerThe first record to display.

An integer value that represents a number of records.

For example, begin the page's list of records with the fifth record, pass in an api.paginate_start value of 5.

api.paginate_sizeinteger

The number of records to display.

An integer value that represents a number of records.

For example, to display ten records on the page, pass in an api.paginate_size value of 10.

api.paginate_pageintegerThe page of results to display.

An integer value that represents which page of results to display.

For example, to display the second page of records, pass in an api.paginate_page value of 2.

Examples

The following examples display paginated results for the Email::list_lists function.

  • The example for the first page of results begins at the fifth record, and lists through the fourteenth record, to display a total of 10 records.
  • The example for the second page of results begins at the fifteenth record, and lists through the twenty-fourth record, to display a total of 10 records.
/execute/Email/list_lists&api.paginate_start=5&api.paginate_size=10&api.paginate=1
/execute/Email/list_lists&api.paginate_start=5&api.paginate_size=10&api.paginate_page=2&api.paginate=1

Note:

This example calls the UAPI function via a cPanel session. For more information, read our Guide to UAPI documentation. 

$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
 
// Call the first page of mailing lists.
$paginated_visitors = $cpanel->uapi(
    'Email', 'list_lists', 
    array(
        'api.paginate'              => '1',
        'api.paginate_start'        => '5',
        'api.paginate_size'         => '10',
    ) 
);
 
// Call the second page of mailing lists.
$paginated_visitors = $cpanel->uapi(
    'Email', 'list_lists', 
    array(
        'api.paginate'              => '1',
        'api.paginate_start'        => '5',
        'api.paginate_size'         => '10',
        'api.paginate_page'         => '2',
    ) 
);

Note:

For more information, read our Guide to the LiveAPI System.

my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.

# Call the first page of mailing lists.
my $paginated_visitors = $cpliveapi->uapi(
    'Email', 'list_lists',
    { 
        'api.paginate'              => '1',
        'api.paginate_start'        => '5',
        'api.paginate_size'         => '10',
    }
);
 
# Call the second page of mailing lists.
my $paginated_visitors = $cpliveapi->uapi(
    'Email', 'list_lists',
    { 
        'api.paginate'              => '1',
        'api.paginate_start'        => '5',
        'api.paginate_size'         => '10',
        'api.paginate_page'         => '2',
    }
);

Note:

For more information, read our Guide to the LiveAPI System.

<!-- Call the first page of mailing lists. -->
[% execute('Email', 'list_lists', { 'domain' => 'example.com', 'api.paginate' => '1', 'api.paginate_start' => '5', 'api.paginate_size' => '10', }) %]
 
<!-- Call the second page of mailing lists. -->
[% execute('Email', 'list_lists', { 'domain' => 'example.com', 'api.paginate' => '1', 'api.paginate_start' => '5', 'api.paginate_size' => '10', 'api.paginate_page' => '2', }) %]

Note:

For more information, read our Guide to Template Toolkit documentation. 

uapi --user=username Email list_lists api.paginate_start=5 api.paginate_size=10 api.paginate=1
uapi --user=username Email list_lists api.paginate_start=5 api.paginate_size=10 api.paginate_page=2 api.paginate=1