UAPI Functions - Branding::file

Description

This function retrieves a branding file's path. 

The function searches the /usr/local/cpanel/base/$appname/$theme/branding/ directory, where:

  • $appname is frontend if you use a cPanel session, or webmail if you use a Webmail session.
  • $theme is x3, x3mail, or paper_lantern.

Examples 

 cPanel or Webmail Session URL

https://hostname.example.com:2083/cpsess##########/execute/Branding/file?file=local.css&needfile=0&skipdefault=0&checkmain1=&nomagic=1

 LiveAPI PHP Class
$cpanel = new CPANEL(); // Connect to cPanel - only do this once.
  
// Get the path to the local.css file.
$file_path = $cpanel->uapi(
    'Branding', 'file',
    array(
      'file'          => 'local.css',
      'needfile'      => '0',
      'skipdefault'   => '0',
      'checkmain'     => '1',
      'nomagic'       => '1',
    )
);

 LiveAPI Perl Module
my $cpliveapi = Cpanel::LiveAPI->new(); # Connect to cPanel - only do this once.
  
# Get the path to the local.css file.
my $file_path = $cpliveapi->uapi(
    'Branding', 'file',
    {
      'file'          => 'local.css',
      'needfile'      => '0',
      'skipdefault'   => '0',
      'checkmain'     => '1',
      'nomagic'       => '1',
    }
);

 cPanel Template Toolkit
<!-- Get a hash of all the data, then display the path value. -->
[% data = execute( 'Branding', 'file', { 'file' => 'local.css', 'needfile' => '0', 'skipdefault' => '0', 'checkmain' => '1', 'nomagic' => '1' } ); %]
[% FOREACH q = data.path %]
     <p>
         [% q %]
     </p>
[% END %]
  
 
<!-- Get only the file path. -->
[% execute('Branding', 'file', { 'file' => 'local.css', 'needfile' => '0', 'skipdefault' => '0', 'checkmain' => '1', 'nomagic' => '1' } ).data.path %]

 Command Line
uapi --user=username Branding file file=local.css needfile=0 skipdefault=0 checkmain=1 nomagic=1

 

Notes:

  • You must URI-encode values.
  • username represents your account-level username.

 Output (JSON)
{ 
   "messages":null,
   "errors":null,
   "status":1,
   "metadata":{ 
 
   },
   "data":{ 
      "type":"cphtml",
      "path":"/usr/local/cpanel/base/frontend/x3/branding/local.css",
      "uri":"/cPanel_magic_revision_1327526145/frontend/x3/branding/local.css"
   }
}

 

Note:

Use cPanel's API Shell interface (Home >> Advanced >> API Shell) to directly test cPanel API calls.

 

Parameters

 Parameter 

Type

Description

Possible values

 Example 

file

string

The file name.

If you do not specify a value, the function returns the path to the branding directory.

Any valid filename.

local.css

needfile

 Boolean 

 Whether to return the /unprotected/broken.gif image () with a failure message when the requested file does not exist. 

This parameter defaults to 0.
  • 1 — Return nothing.
  • 0 — Return the image and a failure message. 

0

skipdefault

Boolean

Whether to ignore the default theme.

This parameter defaults to 0. 
  • 1 — Ignore the theme default.
  • 0 — Do not ignore the theme default.

0

checkmain

Boolean

Whether the function should search the account's /cpanelbranding directory.

This parameter defaults to 0. 
  • 1 — Search the directory.
  • 0 — Do not search the directory.

1

nomagic

Boolean

Whether to include the

cPanel_magic_revision_########## prefix in the uri file path.

This parameter defaults to 0. 
  • 1 — Do not include the prefix.
  • 0 — Include the prefix.

0

a

Returns

Return
Type
Description
Possible values
Example
type string The file type. cphtml
path string The path to the file.
  • The absolute path to the branding directory, if you did not specify a filevalue.
  • A valid absolute path and filename, if the file parameter's file exists.
  • An empty value, if the file does not exist and the needfile value is 1.
  • /unprotected/broken.gif, if the file does not exist and the needfilevalue is 0.

Note:

If you use the x3 theme, the file exists in theusr/local/cpanel/base/frontend/x3 directory.
 Click to view...
uri string The relative path to the file. A valid path and filename, relative to the base directory.
 Click to view...
  • 0 Users Found This Useful
Was this answer helpful?

Related Articles

The cPanel Interface

For  cPanel  &  WHM  version  58 Overview The cPanel interface is...

User Preferences

For cPanel & WHM version 58 Overview This document outlines how to access your cPanel...

Manage External Authentications

For cPanel & WHM version 58 Overview Manage credentials Additional documentation...

What is cPanelID?

In This Article:  Overview ServicesHow to get a cPanelID cPanelID External...

Guide to cPanel Interface Customization - cPanel Style Development

Introduction You can develop custom styles that modify the appearance of the cPanel interface....