Hello World¶
Hello World - Backend¶
The structure of your new module should look like the following example:
A good starting point would be to create your first page with the traditional output "Hello, World".
Creating a new controller¶
CakePHP controllers contain all the business logic and provide the API endpoints for the frontend.
In this example we will create the "TestController".
Create the file /opt/openitc/frontend/plugins/ExampleModule/src/Controller/TestController.php mit folgendem Inhalt:
<?php
declare(strict_types=1);
namespace ExampleModule\Controller;
class TestController extends AppController {
}
Creating a new action¶
Actions contain the logic for your API endpoint.
We will now create an action with the name index to output the message Hello World.
<?php
declare(strict_types=1);
namespace ExampleModule\Controller;
class TestController extends AppController {
public function index() {
if (!$this->isApiRequest()) {
// The requested URL was: /example_module/test/index.html
// The controller only sends the HTML template to the client browser / AngularJS
// Pass the variable "message" with the content "Hello World (HTML)" to the view for .html requests
$this->set('message', 'Hello World (HTML)');
return;
}
// This get executed for API requests
// The requested URL was: /example_module/test/index.json
// Pass the variable "message" with the content "Hello World" to the view
$this->set('message', 'Hello World');
// Add the variable "message" to .json output
$this->viewBuilder()->setOption('serialize', ['message']);
}
}
Creating the view¶
The view is rendered in your browser. openITCOCKPIT supports two view types:
The HTML view is loaded by AngularJS and contains the static HTML structure with placeholders for information about the current action.
The JSON view contains the data for the placeholders that pertain to the current action.
Creating the HTML view¶
Create the file /opt/openitc/frontend/plugins/ExampleModule/templates/Test/index.php with the following content:
<?php
/**
* @var \App\View\AppView $this
* @var string $message
*/
?>
<div class="row">
<div class="col-xl-12">
<div id="panel-1" class="panel">
<div class="panel-hdr">
<h2>
<?php echo __('Example Module'); ?>
<span class="fw-300"><i><?php echo __('Hello World'); ?></i></span>
</h2>
</div>
<div class="panel-container show">
<div class="panel-content">
<!-- Output "Hello World (HTML)" that was set by the controller -->
<?= h($message); ?>
</div>
</div>
</div>
</div>
</div>
!!! info AngularJS will load the template once and then cache it. Do not use <?php foreach($data as $record): ?> to
output data.
Creating the JSON view¶
The JSON view is automatically generated by the CakePHP framework.
You can read more about this topic in the CakePHP documentation.
Assigning permissions for the "Administrator" user role¶
By default, all access to the API actions is denied. You can have openITCOCKPIT assign all permissions to the " Administrator" user by executing the following command:
openitcockpit-update --no-system-files
If your current user is not part of the "Administrator" group, you must navigate
to Verwaltung -> Benutzerverwaltung -> Verwalte Benutzerrollen and assign the permissions manually.
Querying actions¶
You should now be able to request the .html and .json actions.
Navigate in your web browser to /example_module/test/index.html to get the HTML action.
It is normal that no CSS or Javascript is loaded at this point.
By going to /example_module/test/index.json you will get the JSON representation of the action.
Hello World - Frontend¶
New menu item¶
By default, the openITCOCKPIT menu is divided into four categories (MenuHeadline): Overview, Monitoring, Administration and System Configuration.
You can either create links in these categories or create your own categories.
All menu entries for your module are defined in the file /opt/openitc/frontend/plugins/ExampleModule/src/Lib/Menu.php
definiert.
Menu entry for the existing heading¶
PHP Code
<?php
namespace ExampleModule\Lib;
use itnovum\openITCOCKPIT\Core\Menu\MenuCategory;
use itnovum\openITCOCKPIT\Core\Menu\MenuHeadline;
use itnovum\openITCOCKPIT\Core\Menu\MenuInterface;
use itnovum\openITCOCKPIT\Core\Menu\MenuLink;
class Menu implements MenuInterface {
/**
* @return array
*/
public function getHeadlines() {
$Overview = new MenuHeadline(\itnovum\openITCOCKPIT\Core\Menu\Menu::MENU_OVERVIEW);
$Overview
//Create a new Sub-Category of the Overview Headline
->addCategory((new MenuCategory(
'ExampleModule',
__('Example Module'),
1000,
'fas fa-burn'
))
//Add new Link to Sub-Category
->addLink(new MenuLink(
__('Hello world'),
'TestIndex', //Name of the NG-State
'Test', //Name of the PHP Controller
'index', //Name of the PHP action
'ExampleModule', //Name of the Module
'fas fa-code', //Menu Icon
[],
1
))
);
return [$Overview];
}
}
Result
PHPStorm
Now execute the following command to update the display for the views that have been edited.
openitcockpit-update --no-system-files
Menu items under a new heading¶
If needed, you can also create your own headings.
PHP Code
<?php
namespace ExampleModule\Lib;
use itnovum\openITCOCKPIT\Core\Menu\MenuCategory;
use itnovum\openITCOCKPIT\Core\Menu\MenuHeadline;
use itnovum\openITCOCKPIT\Core\Menu\MenuInterface;
use itnovum\openITCOCKPIT\Core\Menu\MenuLink;
class Menu implements MenuInterface {
/**
* @return array
*/
public function getHeadlines() {
$ExampleModuleHeadline = new MenuHeadline(
'ExampleModuleHeadline',
__('Example Module')
);
$ExampleModuleHeadline
//Create a new Sub-Category of the Overview Headline
->addCategory((new MenuCategory(
'ExampleModule',
__('Example Module'),
1000,
'fas fa-burn'
))
//Add new Link to Sub-Category
->addLink(new MenuLink(
__('Hello world'),
'TestIndex', //Name of the NG-State
'Test', //Name of the PHP Controller
'index', //Name of the PHP action
'ExampleModule', //Name of the Module
'fas fa-code', //Menu Icon
[],
1
))
);
return [$ExampleModuleHeadline];
}
}
Result
PHPStorm
Now execute the following command to update the display for the views that have been edited.
openitcockpit-update --no-system-files
Creating a new NG-State / AngularJS route¶
The web interface for openITCOCKPIT is built on the AngularJS framework. Each API action needs its own AngularJS state and controller.
All states are defined in the file /opt/openitc/frontend/plugins/ExampleModule/webroot/js/scripts/ng.states.js
definiert.
openITCOCKPIT.config(function($stateProvider){
$stateProvider
.state('TestIndex', { // Name of the NG-State => Same as in Menu.php
url: '/example_module/test/index', // URL the browser should display
templateUrl: '/example_module/test/index.html', // URL of the .html Template for AngularJS
controller: 'TestIndexController' // Name of the AngularJS Controller. Convention: Controller name + Action Name + 'Controller'
});
});
Creating an AngularJS controller¶
Each action encapsulates its JavaScript logic within an AngularJS controller. Controllers only execute one action at a time. Each action requires its own controller. If you want the same code in different controllers, create an AngularJS service.
Now create your "TestIndexController" under the directory:
/opt/openitc/frontend/plugins/ExampleModule/webroot/js/scripts/controllers/Test/TestIndexController.js.
Convention: /opt/openitc/frontend/plugins/ExampleModule/webroot/js/scripts/controllers/<PHPController name>/<Controller Name><Action Name>Controller.js
.
angular.module('openITCOCKPIT')
.controller('TestIndexController', function($scope, $http){
//Name TestIndexController same as in ng.states.js
//Convention: Controller name + Action Name + 'Controller' = TestIndexController
console.log('TestIndexController is loaded');
});
You can now click on your menu item and see the results.
