Portale v2 (Bozza)
Portale v2
Struttura delle cartelle/file principali
La cartella del portale si trova in: VTE_ROOT/portal/v2
Le cartelle/file principali del nuovo portale sono:
| Nome cartella/file | Descrizione |
| app | Contiene i file e le logiche per il funzionamento del portale. |
| app/controllers | Contiene i file che gestiscono le azioni di default del portale (es. Login, Logout, Edit, Detail, ecc.). |
| app/fields | Contiene i file che gestiscono i campi dei moduli del portale. |
| app/modules | Contiene delle logiche custom di alcuni moduli di vtenext (es. Documents, Processes, HelpDesk, ecc.). |
| app/PortalModule.php | Classe che gestisce le azioni dei moduli del portale (es. Create, Detail, Edit, ecc.). La classe può essere estesa per modificare i comportamenti di default di un modulo. |
| config | Contiene i file di configurazione del portale. |
| public | Contiene i file pubblici del portale (es. index.php, css, javascript, immagini, ecc.). |
| resources | Contiene le risorse utilizzate dal portale come i file per le traduzioni (lang) e i template (templates). |
| sdk | La cartella è utilizzata per inserire nuove personalizzazioni per il cliente. |
| storage | Contiene i file temporanei (es. cache, logs, ecc.). |
| vendor | Contiene le librerie esterne utilizzate dal portale. |
Webservice REST
Handler: include/Webservices/CustomerPortal.php
| Nome | Parametri | Descrizione |
|---|---|---|
| portal.info | Permette di ottenere informazioni sulla licenza e i loghi utilizzati dall'installazione di vtenext collegata. | |
| portal.login |
Body
. username: string (*)
. password: string (*)
. language: string
|
Permette di eseguire il login nel portale clienti fornendo l'email (username) e la password del contatto. Il servizio restituisce l'accesskey da utilizzare nelle chiamate successive come header (Authorization). |
| portal.logout |
Headers . Authorization |
Permette di eseguire il logout del contatto dal portale. |
| portal.send_mail_for_password |
Body
. email: string (*)
. language: string
|
Permette il recupero della password di un contatto del portale. |
| portal.modules_list |
Headers . Authorization Body
. language: string (*)
|
Permette di ottenere una lista di moduli abilitati per il profilo del contatto. |
| portal.get_list |
Headers . Authorization Body . module: string (*) . language: string . folderid: int |
Permette di ottenere la lista dei record di un modulo filtrati per la visibilità del contatto/azienda del contatto. Il parametro "folderid" viene utilizzato dal modulo Documents per ottenere i documenti di una cartella specifica. |
| portal.get_blocks |
Headers . Authorization Body . module: string (*) . language: string . mode: string (edit, create, detail, list) (*) |
Permette di ottenere la lista dei blocchi e dei relativi campi di un modulo filtrati per la visibilità del profilo. |
| portal.get_record |
Headers . Authorization Body . module: string (*) . id: int (*) |
Se il contatto ha i permessi di visibilità per il record indicato, permette di ottenere i suoi dati. |
| portal.save_record |
Headers . Authorization Body . module: string (*) . id: int (*) . values: encoded (*) |
Se il contatto ha i permessi di scrittura per il record indicato, permette il suo salvataggio. |
| portal.delete_record |
Headers . Authorization Body . module: string (*) . id: int (*) |
Se il contatto ha i permessi di eliminazione per il record indicato, permette la sua cancellazione. |
| portal.write_ticket_comment |
Headers . Authorization Body . id: int (*) . comment: string (*) |
Permette la scrittura di un commento all'interno del ticket indicato. |
| portal.get_attachments |
Headers . Authorization Body . id: int (*) |
Permette di ottenere la lista dei documenti del record specificato filtrati per la visibilità del contatto/azienda del contatto. |
| portal.download_attachment |
Headers . Authorization Body . relid: int (*) . docid: int |
Se il contatto ha il permesso di visualizzare l'allegato (relid), permette il suo download. |
| portal.upload_attachment |
Headers . Authorization Body . relid: int (*) . title: string (*) |
Permette il caricamento di un allegato relazionato al record specificato (relid). Si può indicare il nome (title) del documento che verrà generato. |
| portal.provide_confidential_info |
Headers . Authorization Body . id: int (*) . comments: string . data: string (*) . request_commentid: int (*) |
Permette di rispondere ad una richiesta di informazioni confidenziali. Il parametro "id" indica l'id del ticket, il parametro "comments" indica il commento non cifrato, il parametro "data" indica la risposta confidenziale e il parametro "request_commentid" indica l'id del commento a cui fornire la risposta confidenziale. |
| portal.get_home_widgets |
Headers . Authorization Body . language: string |
Permette di ottenere i widget configurati nel profilo associato al contatto. |
| portal.save_authenticate_cookie |
Headers . Authorization Body . contactid: int (*) |
Fornisce un hash da memorizzare in un cookie per permettere di ricordare l'accesso del contatto. |
| portal.check_authenticate_cookie |
Headers . Authorization Body . contactid: int (*) . hash: string (*) |
Permette di verificare l'hash utilizzato per ricordare l'accesso del contatto. |
| portal.change_password |
Headers . Authorization Body . username: string (*) . old_password: string (*) . password: string (*) . language: string |
Permette di cambiare la password del contatto. |
Registrare un nuovo webservice REST
Questo script deve essere eseguito in un ambiente vtenext (es. plugins/script/script.php).
<?php
$parameters = ['param1' => 'string', 'param2' => 'encoded'];
$perm = 'read'; // read, write, readwrite
SDK::setRestOperation('portal.foo', 'include/Webservices/CustomerPortal.php', 'CustomerPortalRestApi.foo', $parameters, $perm);Estendere un webservice REST esistente
Questo script deve essere eseguito in un ambiente vtenext (es. "plugins/script/script.php").
<?php
SDK::setClass('CustomerPortalRestApi', 'CustomerPortalRestApi2', 'modules/SDK/src/CustomerPortalRestApi2.php');Creare un nuovo file da posizionare all'interno di un ambiente vtenext (es. "modules/SDK/src/CustomerPortalRestApi2.php").
<?php
require_once('include/Webservices/CustomerPortal.php');
class CustomerPortalRestApi2 extends CustomerPortalRestApi {
function get_list($module, $language, $folderid = 0) {
// return parent::get_list($module, $language, $folderid);
// your custom code here
}
}Request lifecycle
Configurazione del portale
Il file di configurazione del portale si trova in "config/portal.config.php".
Per sovrascrivere i parametri deve essere utilizzato il file "config/sdk.config.php" altrimenti, in caso di aggiornamento della versione di vtenext, le modifiche potrebbero essere perse.
Ecco la lista dei parametri supportati dal nuovo portale:
| Parametro | Tipo | Default | Descrizione |
| portal_url | String | $PORTAL_URL (config.inc.php) |
Indica l'URL del portale clienti. Se la cartella del portale si trova all'interno della root directory di vtenext, la variabile verrà impostata con il valore della variabile $PORTAL_URL impostata nel file config.inc.php. |
| vte_url | String | $site_URL (config.inc.php) | Indica l'URL di vtenext e viene utilizzato per ottenere i relativi dati tramite le rest API. Se la cartella del portale si trova all'interno della root directory di vtenext, la variabile verrà impostata con il valore della variabile $site_URL impostata nel file config.inc.php. |
|
default_language
|
String |
it_it
|
Indica la lingua predefinita utilizzata nel portale clienti. Il valore può essere sostituito con una lingua supportata (vedi parametro "languages"). |
|
languages
|
Array |
['en_us' => 'US English', 'it_it' => 'IT Italiano']
|
Indica le lingue supportate nel portale clienti. Per aggiungere una nuova lingua si deve creare un nuovo file nella cartella resources/lang. |
|
production
|
Bool | false | Questa configurazione indica se gli errori devono essere visualizzati o meno. Se l'ambiente è di produzione, il valore verrà impostato su true per disabilitare la visualizzazione degli errori. Se l'ambiente è di sviluppo, il valore verrà impostato su false per consentire la visualizzazione degli errori. |
|
default_module
|
String | Indica il modulo predefinito da caricare dopo l'accesso al portale. Il valore può essere sostituito con il nome del modulo desiderato (deve essere abilitato da profilo). Se il parametro è vuoto, verrà caricata la home del portale. | |
|
favicon
|
String |
assets/img/VTENEXT_favicon.ico
|
Indica il percorso della favicon da caricare nel portale clienti. Il valore è relativo alla cartella public. |
|
login_logo
|
String |
assets/img/VTENEXT_login.png
|
Indica il percorso del logo da caricare all'interno della pagina di login. Il valore è relativo alla cartella public. [UPDATE] Il logo deve essere caricato nelle impostazioni di vtenext > Loghi. |
|
login_background
|
String | Indica il percorso dello sfondo da caricare all'interno della pagina di login. Il valore è relativo alla cartella public. | |
|
header_logo_sm
|
String |
assets/img/VTENEXT_toggle.png
|
Indica il percorso dell'icona da caricare nella barra laterale minimizzata. Il valore è relativo alla cartella public. [UPDATE] L'icona deve essere caricata nelle impostazioni di vtenext > Loghi. |
|
header_logo_lg
|
String |
assets/img/VTENEXT_header.png
|
Indica il percorso dell'icona da caricare nella barra laterale allargata. Il valore è relativo alla cartella public. [UPDATE] L'icona deve essere caricata nelle impostazioni di vtenext > Loghi. |
|
helpdesk_logo
|
String |
assets/img/helpdesk.png
|
Indica il logo utilizzato per visualizzare la risposta data dall'assistenza clienti. Il valore è relativo alla cartella public. |
|
sidebar_theme
|
String |
sidebar-dark-primary
|
Indica la classe della barra laterale principale. Può avere una luminosità "dark" o "light". Può avere anche una variante di colore, come "primary", "success", "warning", "info", "danger". |
|
enable_sidebar_search
|
Bool |
false
|
Consente di attivare/disattivare la barra di ricerca nella barra laterale principale. |
|
csrf_secret
|
String |
$csrf_secret (config.inc.php)
|
Indica la chiave segreta utilizzata per generare un token csrf. Se la cartella del portale si trova all'interno della root directory di vtenext, la variabile verrà impostata con il valore della variabile $csrf_secret impostata nel file config.inc.php. |
|
upload_dir
|
String | Indica il nome della cartella utilizzata per il caricamento dei file. | |
|
browser_title_prefix
|
String | Indica l'etichetta del prefisso da utilizzare per il titolo del browser. Il valore può essere sostituito con l'etichetta desiderata. | |
|
browser_title_suffix
|
String |
customer_portal
|
Indica l'etichetta del suffisso da utilizzare per il titolo del browser. Il valore può essere sostituito con l'etichetta desiderata. |
|
remember_cookie_name
|
String |
portal_login_hash
|
Indica il nome del cookie utilizzato per ricordare l'autenticazione dell'utente. |
|
login_expire_time
|
Int |
2592000 (one month)
|
Indica la scadenza del cookie utilizzato per ricordare l'autenticazione dell'utente. Il valore può essere sostituito con il numero di secondi desiderato. |
|
default_timezone
|
String |
Europe/Rome
|
Indica il fuso orario predefinito utilizzato nel portale clienti. Questa configurazione deve essere uguale alla variabile $default_timezone impostata nel file config.inc.php di vtenext. |
|
module_icons
|
Array |
[]
|
Con questa configurazione è possibile sovrascrivere le icone predefinite utilizzate per i moduli abilitati nel portale clienti. Le icone predefinite dei moduli si trovano in app/layouts/PortalLayout.php. I nomi delle icone si possono trovare qui https://fonts.google.com/icons. |
|
sdk_languages
|
Array |
[]
|
Con questa configurazione si possono aggiungere nuove etichette o modificare quelle esistenti. Si deve creare un nuovo file nella cartella sdk. |
|
sdk_global_php
|
Array |
[]
|
Con questa configurazione si possono aggiungere file php da caricare in ogni pagina (dovrebbero contenere classi/funzioni). Si deve creare un nuovo file nella cartella sdk. |
|
sdk_global_js
|
Array |
[]
|
Con questa configurazione si possono aggiungere js da caricare a livello globale. Si deve creare un nuovo file nella cartella public/assets/sdk. |
|
sdk_module_js
|
Array |
[]
|
Con questa configurazione si possono aggiungere js da caricare per un modulo specifico. Si deve creare un nuovo file nella cartella public/assets/sdk. |
|
sdk_global_css
|
Array |
[]
|
Con questa configurazione si possono aggiungere css da caricare a livello globale. Si deve creare un nuovo file nella cartella public/assets/sdk. |
|
sdk_controllers
|
Array |
[]
|
Con questa configurazione si possono aggiungere azioni personalizzate (campo "action" nell'url). L'array rappresenta un'associazione tra il nome dell'azione e il file che contiene la classe controller per gestire la richiesta. Si deve creare un nuovo file nella cartella sdk. |
|
sdk_module
|
Array |
[]
|
Con questa configurazione si possono aggiungere personalizzazioni su un modulo specifico. L'array rappresenta un'associazione tra il nome del modulo e il file che contiene la classe estesa del modulo. Si deve creare un nuovo file nella cartella sdk. |
|
sdk_menu
|
Array |
[]
|
Con questa configurazione si possono aggiungere aggiungere voci di menu personalizzate nella barra laterale. Si deve creare un nuovo file nella cartella sdk. |
Esempi
Creazione di un nuovo controller
Ecco un esempio di come creare un nuovo controller per gestire un'azione custom nel nuovo portale clienti.
- Modificare "config/sdk.config.php" inserendo il nuovo controller
<?php
return [
'sdk_controllers' => [
'SampleVte' => 'controllers/SampleVteController.php',
]
];
- Implementare la classe SampleVteController in "sdk/controllers/SampleVteController.php"
<?php
class SampleVteController extends \app\controllers\BaseController {
public function index($request) {
return $this->displaySomething($request);
}
protected function displaySomething($request) {
$parameter1 = $request->get('parameter1', true);
$parameter2 = $request->get('parameter2', true);
$this->viewer->assign('PARAMETER1', $parameter1);
$this->viewer->assign('PARAMETER2', $parameter2);
$layout = \app\LayoutFactory::getPortalLayout($this->viewer, $this->client, $request);
$output = $this->fetchWithLayout('sdk/SampleVte.tpl', $layout);
return new \app\Response($output);
}
}
- Creare un nuovo template in "resources/templates/sdk/SampleVte.tpl"
{extends file='layouts/PortalLayout.tpl'}
{block name=content}
<h1>Sample Vte</h1>
{/block}- Modificare "config/sdk.config.php" indicando un file sdk per l'inserimento di nuovi voci nel menù laterale
<?php
return [
'sdk_controllers' => [
'SampleVte' => 'controllers/SampleVteController.php',
],
'sdk_menu' => [
'samplevte-menu.php',
]
];
- Modificare il file "sdk/samplevte-menu.php"
<?php
return [
[
'text' => trans('SampleVte'),
'active' => false,
'prefix' => [
'type' => 'icon',
'icon_style' => 'material',
'icon_name' => 'pie_chart',
],
'action' => [
'type' => 'link',
'link_href' => "index.php?action=SampleVte",
],
],
];
Estensione di un modulo
Ecco un esempio di come estendere le funzionalità di un modulo nel nuovo portale clienti.
- Modificare "config/sdk.config.php"
<?php
return [
'sdk_module' => [
'Contacts' => 'modules/ContactsModule.php',
]
];
- Implementare la classe ContactsModule in "sdk/modules/ContactsModule.php"
<?php
class ContactsModule extends \app\PortalModule {
public $hasComments = true;
public $formColumns = 2;
public function canAddComments() {
return true;
}
}
