๐Ÿ“’Moduli

Guida alla struttura dei moduli in OpenSTAManager

Un modulo (software) รจ un componente software autonomo e ben identificato, e quindi facilmente riusabile.

Wikipedia

All'interno del progetto, i moduli vengono genericamente definiti quali sistemi di gestione delle funzionalitร  del gestionale; proprio per questo, la loro struttura e composizione risulta spesso variabile e differenziata.

Ogni modulo รจ composto da diverse sezioni, generalmente suddivise in:

OpenSTAManager presenta inoltre una struttura nativamente predisposta alla personalizzazione delle funzioni principali, il che rende il progetto ancora piรน complicato da comprendere a prima vista.

Di seguito viene presentate le strutture principali piรน comuni supportate dal gestionale; per ulteriori approfondimenti, si consiglia di controllare il codice sorgente dei moduli ufficiali.

๐Ÿ“’ Struttura

Il codice sorgente di ogni modulo di OpenSTAManager รจ all'interno di un percorso univoco all'interno della cartella modules.

.
โ””โ”€โ”€ modules
    โ””โ”€โ”€ {modulo}
       โ””โ”€โ”€ ajax
          โ”œโ”€โ”€ complete.php
          โ”œโ”€โ”€ search.php
          โ””โ”€โ”€ select.php
       โ””โ”€โ”€ modals
          โ””โ”€โ”€ {modal}.php
       โ””โ”€โ”€ plugins
          โ””โ”€โ”€ {plugin}.php
       โ””โ”€โ”€ src
          โ””โ”€โ”€ {object}.php
       โ”œโ”€โ”€ actions.php
       โ”œโ”€โ”€ add.php
       โ”œโ”€โ”€ bulk.php
       โ”œโ”€โ”€ buttons.php
       โ”œโ”€โ”€ controller_after.php
       โ”œโ”€โ”€ controller_before.php
       โ”œโ”€โ”€ edit.php
       โ”œโ”€โ”€ init.php
       โ”œโ”€โ”€ modutil.php
       โ”œโ”€โ”€ validation.php
       โ””โ”€โ”€ variables.php
       
Il nome dei file contenenti le parentesi graffe {} possono assumere qualsiasi valore.

Il gestionale supporta in modo nativo questa struttura, che puรฒ essere ampliata e personalizzata secondo le proprie necessitร : si consiglia pertanto di analizzare i moduli Iva, Dashboard e Contratti per esempi di diversa complessitร .

Attenzione: la presenza dei file sopra indicati รจ necessaria esclusivamente per i moduli fisici, cioรจ moduli che presentano la necessitร  di interagire con il codice sorgente e modificare i dati del gestionale. Per moduli presenti esclusivamente a livello di database (per sempio, Movimenti), si veda la sezione Database.

๐Ÿ“’ ajax/complete.php

Il file ajax/complete.php contiene diversi template HTML che fanno riferimento al modulo e sono gestiti tramite il parametro op che permette di identificare quale template viene richiesto.

Questi template possono essere richiamati da qualsiasi file anche al di fuori del modulo corrispondente.

๐Ÿ“’ ajax/search.php

Il file ajax/search.php si occupa di estrarre le informazioni necessarie per la ricerca globale del modulo di riferimento.

Questo avviene tramite l'esecuzione di una query e la visualizzazione in HTML dei risultati ottenuti.

๐Ÿ“’ ajax/select.php

l file ajax/select.php contiene le query che fanno riferimento al modulo per quanto riguarda la valorizzazione dei campi input select (menรน a tendina), sono gestiti tramite il parametro ajax-source che permette di identificare quale query viene richiesta.

Queste query possono essere richiamate via ajax tramite valorizzando nel campo input l'attributo ajax-source da qualsiasi file anche al di fuori del modulo corrispondente.

๐Ÿ“’ modals/{modal}.php

l file modals/{modal}.php contiene il template HTML dedicato alla visualizzazione di una specifica pop-up richiamata nel modulo.

๐Ÿ“’ plugins/{plugins}.php

l file plugins/{plugin}.php contiene lo script per la gestione di un plugin del modulo di riferimento, in caso di un plugin articolato in piรน file รจ necessario utilizzare il percorso plugins/ specifico.

๐Ÿ“’ src/{object}.php

l file src/{object}.php permette la gestione e la creazione di oggetti Eloquent del modulo andando a definire le varie funzioni specifiche dell'oggetto.

๐Ÿ“’ actions.php

Il file actions.php gestisce tutte le operazioni supportate dal modulo.

In generale, le diverse operazioni vengono gestite attraverso attraverso una logica basata su casi (solitamente, il parametro op permette di identificare quale azione viene richiesta); il funzionamento a livello di programmazione puรฒ essere comunque sottoposto a scelte personali.

L'unico requisito effettivo risulta relativo alle operazioni di creazione dei nuovi record, per cui deve essere definito all'interno della variabile $id_record l'identificativo del nuovo elemento. Per osservare questo sistema, si consiglia di analizzare il relativo file del modulo Iva.

๐Ÿ“’ add.php e edit.php

Il file add.php contiene il template HTML dedicato all'inserimento di nuovi elementi per il modulo, mentre edit.php contiene il template HTML dedicato alla modifica degli stessi.

In base alla configurazione del modulo nel database, il file edit.php puรฒ assumere il ruolo di gestore della sezione principale dell'interno modulo. Esempi di questa gestione si possono osservare nei moduli Dashboard e Gestione componenti (si veda la sezione zz_modules).

Attenzione: il progetto individua in automatico la presenza del file add.php e agisce di conseguenza per permettere o meno l'inserimento di nuovi record. {: .notice--danger}

๐Ÿ“’ bulk.php

Il file bulk.php si occupa di gestire le azioni di gruppo accessibili nel modulo che vengono visualizzate sotto alla tabella principale.

Il file รจ formato da due parti, la prima contiene le operazioni di gruppo che vengono effettuate, sempre gestite dal parametro op, mentre la seconda parte contiene il template per la visualizzazione all'interno del modulo.

๐Ÿ“’ buttons.php

Il file buttons.php viene incluso nel file edit.php e viene utilizzato per mostrare nella parte superiore della schermata (in fase di modifica record) i pulsanti/avvisi definiti nel file.

๐Ÿ“’ init.php

Il file init.php si occupa di individuare le informazioni principali utili all'identificazione e alla modifica dei singoli elementi del modulo.

In particolare, questo file รจ solitamente composto da una query dedicata ad ottenere tutti i dati dell'elemento nella variabile $record ($records per versioni <= 2.4.1), successivamente utilizzata dal gestore dei template per completare le informazioni degli input.

๐Ÿ“’ controller_after.php e controller_before.php

Il file controller_before.php contiene il template HTML da aggiungere all'inizio della pagina principale del modulo se questo รจ strutturato in modo tabellare.

Similmente, il file controller_after.php contiene il template HTML da aggiungere alla fine della pagina principale nelle stesse condizioni.

๐Ÿ“’ modutil.php

Il file modutil.php viene utilizzato per definire le funzioni PHP specifiche del modulo, e permettere in questo modo una gestione semplificata delle operazioni piรน comuni.

Si noti che un modulo non รจ necessariamente limitato all'utilizzo del proprio file modutil.php: come avviene per esempio in Fatture e Interventi, risulta possibile richiamare file di questa tipologia da altri moduli (in questo caso, da Articoli per la gestione delle movimentazioni di magazzino).

๐Ÿ“’ validation.php

Il file validation.php viene utilizzato per effettuare controlli di validazione su un specifico campo input.

Per richiamare la validazione รจ necessario inserire l'attributo validation nel campo input con il nome del controllo da effettuare.

๐Ÿ“’ variables.php

Il file variables.php contiene le variabili che possono essere utilizzate nei template delle email per la sostituzione automatica in base al record del modulo.

๐Ÿ“’ Database

All'interno del database del progetto, le tabelle con il suffisso zz sono generalmente dedicate alla gestione delle funzioni di base del gestionale.

La gestione dei moduli avviene in questo senso grazie alle seguenti tabelle:

  • zz_modules;

  • zz_permissions;

  • zz_views;

  • zz_plugins;

  • zz_widgets.

๐Ÿ“’ zz_modules

La tabella zz_modules contiene tutte le informazioni dei diversi moduli installati nel gestionale in uso, con particolare riferimento a:

  • Nome (utilizzato a livello di codice) [name]

  • Titolo (nome visibile e personalizzabile) [title]

  • Percorso nel file system (partendo da modules/) [directory]

  • Icona [icon]

  • Posizione nella sidebar [order]

  • Compatibilitร  [compatibility]

  • Query di default [options]

  • Query personalizzata [options2]

Gli ultimi due attributi si rivelano di fondamentale importanza per garantire il corretto funzionamento del modulo, poichรฉ descrivono il comportamento dello stesso per la generazione della schermata principale nativa in OpenSTAManager.

Sono permessi i seguenti valori:

  • custom [Modulo con schermata principale personalizzata e definita nel file edit.php]

  • {VUOTO} [Menu non navigabile]

  • menu [Menu non navigabile]

  • Oggetto JSON

    { "main_query": [ { "type": "table", "fields": "Nome, Descrizione", "query": "SELECT `id`, `nome` AS `Nome`, `descrizione` AS `Descrizione` FROM `tabella` WHERE 2=2 HAVING 1=1 ORDER BY `nome`"} ]}
    SELECT |select| FROM `tabella` WHERE 2=2 HAVING 1=1

๐Ÿ“’ zz_permissions e zz_group_module

La tabella zz_permissions contiene i permessi di accesso dei vari gruppi ai diversi moduli, mentre la tabella zz_group_module contiene le clausole SQL per eventualmente restringere questo accesso.

๐Ÿ“’ zz_views e zz_group_view

Le tabelle zz_views e zz_group_view vengono utilizzate dal gestionale per la visualizzazione delle informazioni secondo i permessi accordati, oltre che dal modulo Viste per la gestione dinamica delle query.

๐Ÿ“’ zz_plugins e zz_widgets

La tabella zz_plugins contiene l'elenco di plugins relativi ai diversi moduli, mentre la tabella zz_widgets contiene l'elenco di widgets dei vari moduli.

๐Ÿ“’ Consigli per lo sviluppo

Alla base dello sviluppo di ogni modulo vi รจ una fase di analisi indirizzata all'individuazione dettagliata delle funzionalitร  dello stesso e della struttura interna al database atta a sostenere queste funzioni.

Siete dunque pregati di identificare chiaramente tutte le caratteristiche del Vostro nuovo modulo o delle Vostre modifiche prima di iniziare lo sviluppo vero e proprio (comunemente identificato con la scrittura del codice).

E' bene trascurare le fasi di analisi e di progetto e precipitarsi all'implementazione allo scopo di guadagnare il tempo necessario per rimediare agli errori commessi per aver trascurato la fase di analisi e di progetto.

Legge di Mayers

๐Ÿ“’ Sviluppo

Lo sviluppo del codice deve seguire alcune direttive generali per la corretta interpretazione del codice all'interno del gestionale: ciรฒ comporta una struttura di base fondata sui file precedentemente indicati nella sezione Struttura ma ampliabile liberamente.

๐Ÿ“’ Test

Prima di pubblicare un modulo si consiglia di effettuare svariati test in varie installazioni. Siete inoltre pregati di indicare i bug noti.

Se cโ€™รจ una remota possibilitร  che qualcosa vada male, sicuramente ciรฒ accadrร  e produrrร  il massimo danno.

Legge di Murphy

๐Ÿ“’ Installazione

L'installazione di un modulo รจ completabile in modo automatico seguendo la seguente procedura:

  • Scaricare l'archivio .zip del modulo da installare;

  • Accedere al proprio gestionale con un account abilita all'accesso del modulo Aggiornamenti;

  • Selezionare l'archivio scaricato nella selezione file della sezione "Carica un nuovo modulo";

  • Cliccare il pulsante "Carica".

Si ricorda che per effettuare l'installazione รจ necessaria la presenza dell'estensione php_zip (per ulteriori informazioni guardare qui).

Attenzione: la procedura puรฒ essere completata anche a livello manuale, ma si consiglia di evitare tale sistema a meno che non si conosca approfonditamente il procedimento di installazione gestito da OpenSTAManager.

๐Ÿ“’ Archivio ZIP

L'archivio del modulo deve essere organizzato secondo la seguente struttura:

modulo.zip
โ”œโ”€โ”€ update
|   โ”œโ”€โ”€ VERSIONE.sql
|   โ””โ”€โ”€ unistall.php
โ”œโ”€โ”€ ... - File contententi il codice del modulo
โ””โ”€โ”€ MODULE

Alcuni esempi sulla struttura dei moduli personalizzati sono disponibili nella repository https://github.com/devcode-it/example.

update/VERSIONE.sql

Il file VERSIONE.sql (dove VERSIONE sta per la versione del modulo con _[underscore] al posto di .[punto]) contiene le operazioni di installazione e aggiornamento del modulo a livello del database, comprendenti la creazione delle tabelle di base del modulo e l'inserimento di ulteriori dati nelle altre tabelle.

update/unistall.php

Il file unistall.php contiene le operazioni di disinstallazione del modulo a livello del database, e deve prevedere l'eliminazione delle tabelle non piรน necessarie e dei dati inutilizzati.

<?php

include_once __DIR__.'/../../core.php';

$dbo->query("DROP TABLE `tabella`");

MODULE

Il file MODULE รจ infine il diretto responsabile dell'installazione del modulo poichรฉ definisce tutti i valori caratteristici dello stesso; in caso di sua assenza la cartella compressa viene considerata non corretta.

name = "Nome del modulo"
version = "Versione"
directory = "Cartella di installazione"
options = "Operazione da eseguire all'apertura"
compatibility = "Versioni di compatibilitร "
compatibility = "Compatibilitร  del modulo"
parent = "Genitore del modulo"

๐Ÿ“’ Moduli di base

Nella versione base del gestionale sono presenti, all'interno della cartella modules, i seguenti moduli.

.
โ”œโ”€โ”€ aggiornamenti
โ”œโ”€โ”€ anagrafiche
โ”œโ”€โ”€ articoli
โ”œโ”€โ”€ attributi_combinazioni
โ”œโ”€โ”€ backups
โ”œโ”€โ”€ banche
โ”œโ”€โ”€ beni
โ”œโ”€โ”€ carrelli
โ”œโ”€โ”€ categorie_articoli
โ”œโ”€โ”€ categorie_documenti
โ”œโ”€โ”€ categorie_impianti
โ”œโ”€โ”€ causali
โ”œโ”€โ”€ causali_movimenti
โ”œโ”€โ”€ checklists
โ”œโ”€โ”€ contratti
โ”œโ”€โ”€ custom_fields
โ”œโ”€โ”€ dashboard
โ”œโ”€โ”€ ddt
โ”œโ”€โ”€ emails
โ”œโ”€โ”€ eventi
โ”œโ”€โ”€ fasce_orarie
โ”œโ”€โ”€ fatture
โ”œโ”€โ”€ gestione_documentale
โ”œโ”€โ”€ giacenze_sedi
โ”œโ”€โ”€ impianti
โ”œโ”€โ”€ import
โ”œโ”€โ”€ impostazioni
โ”œโ”€โ”€ interventi
โ”œโ”€โ”€ iva
โ”œโ”€โ”€ liste_newsletter
โ”œโ”€โ”€ listini
โ”œโ”€โ”€ mansioni
โ”œโ”€โ”€ misure
โ”œโ”€โ”€ modelli_primanota
โ”œโ”€โ”€ movimenti
โ”œโ”€โ”€ newsletter
โ”œโ”€โ”€ ordini
โ”œโ”€โ”€ pagamenti
โ”œโ”€โ”€ partitario
โ”œโ”€โ”€ piano_sconto
โ”œโ”€โ”€ porti
โ”œโ”€โ”€ preventivi
โ”œโ”€โ”€ primanota
โ”œโ”€โ”€ relazioni_anagrafiche
โ”œโ”€โ”€ reparti
โ”œโ”€โ”€ ritenute
โ”œโ”€โ”€ ritenute_contributi
โ”œโ”€โ”€ rivalse
โ”œโ”€โ”€ scadenzario
โ”œโ”€โ”€ segmenti
โ”œโ”€โ”€ smtp
โ”œโ”€โ”€ spedizioni
โ”œโ”€โ”€ stampe
โ”œโ”€โ”€ stampe_contabili
โ”œโ”€โ”€ stati_contratto
โ”œโ”€โ”€ stati_intervento
โ”œโ”€โ”€ stati_preventivo
โ”œโ”€โ”€ statistiche
โ”œโ”€โ”€ stato_email
โ”œโ”€โ”€ stato_servizi
โ”œโ”€โ”€ tecnici_tariffe
โ”œโ”€โ”€ tipi_anagrafiche
โ”œโ”€โ”€ tipi_documento
โ”œโ”€โ”€ tipi_intervento
โ”œโ”€โ”€ tipi_scadenze
โ”œโ”€โ”€ utenti
โ”œโ”€โ”€ viste
โ”œโ”€โ”€ voci_servizio
โ””โ”€โ”€ zone

Last updated