...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function getServiceName($service) {
$key = "phone_number";
foreach ($service->fields as $field) {
if ($field->key == $key)
return $field->value;
}
return null;
}
...
} |
getPackageServiceName($package, array $vars = null)
Given a particular package and input data for the configuration, this method should return the label used to identify the package name prior to it becoming a service. This is similar to "getServiceName($service)". For example, if the module were representing VOIP services, the value returned by this method might be the phone number associated with the VOIP service.
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function getPackageServiceName($package, array $vars = null) {
$key = "phone_number";
return (isset($vars[$key]) ? $vars[$key] : null);
}
...
} |
moduleRowName()
The moduleRowName() method returns the value used to represent a module row. For example, if the module were representing shared hosting services and each module row were a physical server the value returned by this method might be "Server".
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function moduleRowMetaKey() {
return "host_name";
}
...
}
|
...
Optional Methods
The methods below are optional, but may be required to implement a module of any utility.
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function validateService($package, array $vars=null) {
// Set any input rules to validate against
$rules = array(
'mymodule_field' => array(
'empty' => array(
'rule' => "isEmpty",
'negate' => true,
'message' => Language::_("MyModule.!error.mymodule_field.empty", true)
);
)
);
$this->Input->setRules($rules);
// Determine whether the input validates
return $this->Input->validates($vars);
}
...
} |
addService($package, array $vars=null, $parent_package=null, $parent_service=null, $status="pending")
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function addService($package, array $vars=null, $parent_package=null, $parent_service=null, $status="pending") {
// Get the module row used for this service
$row = $this->getModuleRow();
// Filter the given $vars into an array of key/value pairs that will be passed to the API
$params = $this->getFieldsFromInput((array)$vars, $package);
// Attempt to validate the input and return on failure
$this->validateService($package, $vars);
if ($this->Input->errors())
return;
// Only provision the service remotely if 'use_module' is true
if (isset($vars['use_module']) && $vars['use_module'] == "true") {
// Log the input being sent remotely, careful to mask any sensitive information
$masked_params = $params;
$masked_params['mymodule_field'] = "***";
// Set the URL to where the remote request is being sent (assuming 'host_name' is a valid module row meta field)
$remote_url = $row->meta->host_name;
$this->log($remote_url . "|api_command", serialize($masked_params), "input", true);
// Provision the service remotely (this is dependent on the module's API, omitted here)
$response = $this->makeRequest($params);
// Return on error
if ($this->Input->errors())
return;
}
// Return the service fields
return array(
array(
'key' => "mymodule_field",
'value' => (isset($vars['mymodule_field']) ? $vars['mymodule_field'] : null),
'encrypted' => 0
)
);
}
private function makeRequest($params) {
// Get the module row used for this service
$row = $this->getModuleRow();
// Perform the remote request (this is dependent on the module's API, omitted here)
$response = $this->apiCall($params);
// Retrieve the response from the module and evaluate its result as true/false, setting any input errors
$success = true;
if (isset($response->status) && !$response->status) {
$this->Input->setErrors(array('api' => array('response' => Language::_("MyModule.!error.api.response", true))));
$success = false;
}
// Log the response
$this->log($row->meta->host_name, $response, "output", $success);
// Return the result
if (!$success)
return;
return $response;
}
private function apiCall($params) {
// Make the API call to the module (this is dependent on the module's API, omitted here)
return (object)array('status' => false);
}
...
} |
editService($package, $service, array $vars=array(), $parent_package=null, $parent_service=null)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function cancelService($package, $service, $parent_package=null, $parent_service=null) {
// Get the module row used for this service
if (($row = $this->getModuleRow())) {
// Format the list of service fields as an object
$service_fields = $this->serviceFieldsToObject($service->fields);
// Set the URL to where the remote request is being sent (assuming 'host_name' is a valid module row meta field)
$remote_url = $row->meta->host_name;
$this->log($remote_url . "|api_command", serialize($service_fields), "input", true);
// Provision the service remotely (this is dependent on the module's API, omitted here)
$response = $this->makeRequest($service_fields);
}
return null;
}
private function makeRequest($params) {
// Get the module row used for this service
$row = $this->getModuleRow();
// Perform the remote request (this is dependent on the module's API, omitted here)
$response = $this->apiCall($params);
// Retrieve the response from the module and evaluate its result as true/false, setting any input errors
$success = true;
if (isset($response->status) && !$response->status) {
$this->Input->setErrors(array('api' => array('response' => Language::_("MyModule.!error.api.response", true))));
$success = false;
}
// Log the response
$this->log($row->meta->host_name, $response, "output", $success);
// Return the result
if (!$success)
return;
return $response;
}
private function apiCall($params) {
// Make the API call to the module (this is dependent on the module's API, omitted here)
return (object)array('status' => false);
}
...
} |
suspendService($package, $service, $parent_package=null, $parent_service=null)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function addPackage(array $vars=null) {
// Set any package meta field rules
$rules = array(
'meta[field]' => array(
'empty' => array(
'rule' => "isEmpty",
'negate' => true,
'message' => Language::_("MyModule.!error.meta[field].empty", true)
)
)
);
// Determine whether the input validates
$meta = array();
if ($this->Input->validates($vars)) {
// Set meta fields to save
foreach ($vars['meta'] as $key => $value) {
$meta[] = array(
'key' => $key,
'value' => $value,
'encrypted' => 0
);
}
}
return $meta;
}
...
} |
...
editPackage($package, array $vars=null)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function deletePackage($package) {
// Attempt to delete a package remotely (this is dependent on the module's API, omitted here)
$response = $this->apiCall($package);
if (isset($response->status) && !$response->status)
$this->Input->setErrors(array('api' => array('response' => Language::_("MyModule.!error.api.response", true))));
}
private function apiCall($params) {
// Make the API call to the module (this is dependent on the module's API, omitted here)
return (object)array('status' => false);
}
...
} |
...
manageModule($module, array &$vars)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function manageModule($module, array &$vars) {
// Load the view into this object, so helpers can be automatically added to the view
$this->view = new View("manage", "default");
$this->view->base_uri = $this->base_uri;
$this->view->setDefaultView("components" . DS . "modules" . DS . "my_module" . DS);
// Load the helpers required for this view
Loader::loadHelpers($this, array("Form", "Html", "Widget"));
$this->view->set("module", $module);
return $this->view->fetch();
}
...
} |
...
manageAddRow(array &$vars)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function manageAddRow(array &$vars) {
// Load the view into this object, so helpers can be automatically added to the view
$this->view = new View("add_row", "default");
$this->view->base_uri = $this->base_uri;
$this->view->setDefaultView("components" . DS . "modules" . DS . "my_module" . DS);
// Load the helpers required for this view
Loader::loadHelpers($this, array("Form", "Html", "Widget"));
$this->view->set("vars", (object)$vars);
return $this->view->fetch();
}
...
} |
...
manageEditRow($module_row, array &$vars)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function manageEditRow($module_row, array &$vars) {
// Load the view into this object, so helpers can be automatically added to the view
$this->view = new View("edit_row", "default");
$this->view->base_uri = $this->base_uri;
$this->view->setDefaultView("components" . DS . "modules" . DS . "my_module" . DS);
// Set initial module row meta fields for vars
if (empty($vars))
$vars = $module_row->meta;
// Load the helpers required for this view
Loader::loadHelpers($this, array("Form", "Html", "Widget"));
$this->view->set("vars", (object)$vars);
return $this->view->fetch();
}
...
} |
addModuleRow(array &$vars)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function addModuleRow(array &$vars) {
// Set a white list of fields to add to the module row
$fields = array("field1", "password");
$encrypted_fields = array("password");
// Set any rules for the module row fields
$rules = array(
'field1' => array(
'empty' => array(
'rule' => "isEmpty",
'negate' => true,
'message' => Language::_("MyModule.!error.field1.empty", true)
)
),
'password' => array(
'empty' => array(
'rule' => "isEmpty",
'negate' => true,
'message' => Language::_("MyModule.!error.password.empty", true)
)
)
);
$this->Input->setRules($rules);
// Determine whether the input validates
if ($this->Input->validates($vars)) {
// Add each field
$meta = array();
foreach ($vars as $key => $value) {
if (in_array($key, $fields)) {
$meta[] = array(
'key' => $key,
'value' => $value,
'encrypted' => in_array($key, $encrypted_fields) ? 1 : 0
);
}
}
return $meta;
}
}
...
} |
editModuleRow($module_row, array &$vars)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function deleteModuleRow($module_row) {
// Attempt to delete a module row remotely (this is dependent on the module's API, omitted here)
$response = $this->apiCall($module_row);
if (isset($response->status) && !$response->status)
$this->Input->setErrors(array('api' => array('response' => Language::_("MyModule.!error.api.response", true))));
}
private function apiCall($params) {
// Make the API call to the module (this is dependent on the module's API, omitted here)
return (object)array('status' => false);
}
...
} |
...
getGroupOrderOptions()
This method returns an array of service delegation order methods. For example, if multiple module rows exist for a module, you may want to provide an option to assign new services to the module row with the least number of services already assigned to it.
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function getGroupOrderOptions() {
return array('first' => Language::_("MyModule.order_options.first", true);
}
...
} |
...
selectModuleRow($module_group_id)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function selectModuleRow($module_group_id) {
// Load the ModuleManager
if (!isset($this->ModuleManager))
Loader::loadModels($this, array("ModuleManager"));
// Select the group associated with the given module group ID
if (($group = $this->ModuleManager->getGroup($module_group_id))) {
// Choose the module row to use
switch ($group->add_order) {
default:
case "first":
// Return the first row encountered
foreach ($group->rows as $row)
return $row->id;
break;
}
}
return 0;
}
...
} |
...
getPackageFields($vars=null)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function getPackageFields($vars=null) {
// Load any helpers required to build the fields
Loader::loadHelpers($this, array("Html"));
// Set any module fields
$fields = new ModuleFields();
$fields->setHtml("
<script type=\"text/javascript\">
$(document).ready(function() {
// Re-fetch module options
$('#mymodule_group').change(function() {
fetchModuleOptions();
});
});
</script>
");
// Fetch all packages available for the given server or server group
$module_row = null;
if (isset($vars->module_group) && $vars->module_group == "") {
// Set a module row if one is given
if (isset($vars->module_row) && $vars->module_row > 0)
$module_row = $this->getModuleRow($vars->module_row);
else {
// Set the first module row of any that exist
$rows = $this->getModuleRows();
if (isset($rows[0]))
$module_row = $rows[0];
unset($rows);
}
}
else {
// Set the first module row from the list of servers in the selected group
$rows = $this->getModuleRows($vars->module_group);
if (isset($rows[0]))
$module_row = $rows[0];
unset($rows);
}
// Build any HTML fields
$select_options = array('one' => "One", 'two' => "Two");
$field = $fields->label(Language::_("MyModule.package_fields.field1", true), "mymodule_field");
$field->attach($fields->fieldSelect("meta[field]", $select_options,
$this->Html->ifSet($vars->meta['field']), array('id' => "mymodule_field")));
$fields->setField($field);
return $fields;
}
...
} |
...
getEmailTags()
This method returns an array of key/value pairs with "module", "package", and "service" keys that refer to module, package, and service fields used in this module that may be used as tags in emails.
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function getEmailTags() {
return array(
'module' => array("field1", "password"),
'package' => array("field"),
'service' => array("mymodule_field")
);
}
...
} |
getAdminAddFields($package, $vars=null)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function getAdminAddFields($package, $vars=null) {
Loader::loadHelpers($this, array("Html"));
$fields = new ModuleFields();
// Create field label
$mymodule_field = $fields->label(Language::_("MyModule.service_field.mymodule_field", true), "mymodule_field");
// Create field and attach to label
$mymodule_field->attach($fields->fieldText("mymodule_field", $this->Html->ifSet($vars->mymodule_field), array('id'=>"mymodule_field")));
// Add a tooltip next to this field
$tooltip = $fields->tooltip(Language::_("MyModule.service_field.tooltip.mymodule_field", true));
$mymodule_field->attach($tooltip);
// Set the field
$fields->setField($mymodule_field);
return $fields;
}
...
} |
getClientAddFields($package, $vars=null)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function getAdminServiceInfo($service, $package) {
$row = $this->getModuleRow();
// Load the view (admin_service_info.pdt) into this object, so helpers can be automatically added to the view
$this->view = new View("admin_service_info", "default");
$this->view->base_uri = $this->base_uri;
$this->view->setDefaultView("components" . DS . "modules" . DS . "my_module" . DS);
// Load the helpers required for this view
Loader::loadHelpers($this, array("Form", "Html"));
$this->view->set("module_row", $row);
$this->view->set("package", $package);
$this->view->set("service", $service);
$this->view->set("service_fields", $this->serviceFieldsToObject($service->fields));
return $this->view->fetch();
}
...
} |
getClientServiceInfo($service, $package)
...
| Code Block | ||
|---|---|---|
| ||
class MyModule extends Module {
...
public function getAdminTabs($package) {
// The keys (i.e. "tabOne", "tabTwo") representing the method name of the tab to call when an admin clicks on it in the interface
return array(
'tabOne' => Language::_("MyModule.tab_one", true),
'tabTwo' => Language::_("MyModule.tab_two", true)
);
}
public function tabOne($package, $service, array $get=null, array $post=null, array $files=null) {
$this->view = new View("tab_one", "default");
// Load the helpers required for this view
Loader::loadHelpers($this, array("Form", "Html"));
// Set any specific data for this tab
$tab_data = array();
$this->view->set("tab_data", $tab_data);
$this->view->setDefaultView("components" . DS . "modules" . DS . "my_module" . DS);
return $this->view->fetch();
}
public function tabTwo($package, $service, array $get=null, array $post=null, array $files=null) {
$this->view = new View("tab_two", "default");
// Load the helpers required for this view
Loader::loadHelpers($this, array("Form", "Html"));
// Set any specific data for this tab
$tab_data = array();
$this->view->set("tab_data", $tab_data);
$this->view->setDefaultView("components" . DS . "modules" . DS . "my_module" . DS);
return $this->view->fetch();
}
...
} |
...
getClientTabs($package)
This method returns a list of key/value pairs representing tab names to display when a client goes to manage their service.
This method is very similar to getAdminTabs().
...