Development Guides Home >> Guide to WHM Plugins

Guide to WHM Plugins - The ACL Metadata Perl Module

Introduction

The ACL metadata Perl module defines necessary functions for the ACL system. Create the ACL metadata Perl module in the /usr/local/cpanel/Cpanel/Config/ConfigObj/Driver/Namespace/ directory, where Namespace is the ACL's namespace.

Warning:
  • This file must be the META.pm file.
  • Do not load your Driver module in your META module.
  • To avoid a significant startup cost, we recommend that you load modules dynamically. Load modules at the top of each subroutine. Do not call modules via the use function directly.

The ACL metadata Perl module

The following example code configures metadata for the ExampleACL ACL:

package Cpanel::Config::ConfigObj::Driver::ExampleACL::META;

use parent qw(Cpanel::Config::ConfigObj::Interface::Config::Version::v1);
our $VERSION = '1.1';
our $REQUIRED_MEM_IN_MIB                          = 512;
our $_RECOMMENDED_MINIMUM_AVAILABLE_MEMORY_IN_MIB = $REQUIRED_MEM_IN_MIB * 2;
use Cpanel::LoadModule ();

use strict;

sub meta_version {
    return 1;
}

sub get_driver_name {
    return 'ExampleACL_driver';
}

sub content {
    my ($locale_handle) = @_;

    my $content = {
        'vendor' => 'WebPros International, LLC',
        'url'    => 'www.cpanel.net',
        'name'   => {
            'short'  => 'ExampleACL Driver',
            'long'   => 'ExampleACL Driver for ExampleACL Plugin test module',
            'driver' => get_driver_name(),
        },
        'since'    => 'cPanel & WHM version 11.32.4',
        'abstract' => "An ExampleACL driver for developers to emulate.",
        'version'  => $Cpanel::Config::ConfigObj::Driver::ExampleACL::VERSION,
    };

    if ($locale_handle) {
        $content->{'abstract'} = $locale_handle->maketext("An ExampleACL driver for developers to emulate.");
    }

    return $content;
}

sub showcase {
    Cpanel::LoadModule::load_perl_module('Cpanel::Sys::Hardware::Memory');
    my $available_mem_in_mib = Cpanel::Sys::Hardware::Memory::get_available();
    my $can_display          = $available_mem_in_mib > $_RECOMMENDED_MINIMUM_AVAILABLE_MEMORY_IN_MIB;
    my $can_spotlight        = $available_mem_in_mib > ( $_RECOMMENDED_MINIMUM_AVAILABLE_MEMORY_IN_MIB * 2 );
    if ($can_display) {
         return { 'is_spotlight_feature' => $can_spotlight ? 1 : 0 };
    }  
    return undef;
}
1;

Package the module

package Cpanel::Config::ConfigObj::Driver::ExampleACL::META;

This declaration instructs Perl to treat all of the file's functions as part of the Cpanel::Config::ConfigObj::Driver::ExampleACL::META namespace.

For more information, read perldoc.perl.org's package documentation.

Set the strict pragma

use strict;

This declaration instructs Perl to return errors if the file contains potentially unsafe code.

For more information, read perldoc.perl.org's strict documentation.

Use the ACL object module

use Cpanel::Config::ConfigObj::Driver::ExampleACL ();

Set the ACL object module as a dependency.

For more information, read perldoc.perl.org's use documentation.

Call modules as needed

Cpanel::LoadModule::load_perl_module('<MODULE NAME>');

To avoid a significant startup cost, you should load modules dynamically. Call modules at the beginning of each subroutine, do not call modules via use.

Set a metadata version

sub meta_version {
    return 1;
}

The meta_version subroutine sets a metadata version number.

Set the ACL's driver's name

sub get_driver_name {
    return 'ExampleACL_driver';
}

The get_driver_name subroutine returns the ACL's driver's name (ExampleACL_driver).

Configure the ACL's metadata

sub content {
    my ($locale_handle) = @_;

    my $content = {
        'vendor' => 'WebPros International, LLC',
        'url'    => 'www.cpanel.net',
        'name'   => {
            'short'  => 'ExampleACL Driver',
            'long'   => 'ExampleACL Driver for ExampleACL Plugin test module',
            'driver' => get_driver_name(),
        },
        'since'    => 'cPanel & WHM version 11.32.4',
        'abstract' => "An ExampleACL driver for developers to emulate.",
        'version'  => $Cpanel::Config::ConfigObj::Driver::ExampleACL::VERSION,
    };

    if ($locale_handle) {
        $content->{'abstract'} = $locale_handle->maketext("An ExampleACL driver for developers to emulate.");
    }

    return $content;
}

The content subroutine configures the ACL's metadata. This subroutine must assign the following values to the $content hash:

Parameter Type Description Possible Values Example
vender string The custom ACL's vendor. A valid string. WebPros International, LLC
url string The vendor's website. A valid URL. www.cpanel.net
name hash A hash of ACL name information. This hash includes the short, long, and driver parameters.
short
string The ACL's driver's short name. Supply this value in the name hash. A valid string. ExampleACL Driver
long
string The ACL's driver's long name. Supply this value in the name hash. A valid string. ExampleACL Driver for ExampleACL Plugin test module
driver
string The ACL's driver's internal name. Supply this value in the name hash. Use the get_driver_name subroutine to supply this value. get_driver_name()
since string The first cPanel & WHM version with which the plugin is compatible. A valid string. cPanel & WHM version 11.32.4
abstract string A short description of the plugin. A valid string. An ExampleACL driver for developers to emulate.
version string The ACL's version. Use the VERSION value from the ACL object module to supply this value $Cpanel::Config::ConfigObj::Driver::ExampleACL::VERSION