Good Ideas

Docs

Manuale Utente

Questo manuale vuole essere una guida all’utente che installa e usa per la prima volta Syntax Desktop.

Indice

  1. Prefazione
  2. Per iniziare
  3. Il Desktop
  4. Gestione Contenuti
  5. Strumenti
  6. Informazioni aggiuntive
     

Prefazione

Syntax Desktop è un sistema di gestione dei contenuti web based.
Nasce dalla necessità di rendere il lavoro di un programmatore web (questa è la mia professione) molto più semplice. Avevo infatti bisogno di uno strumento che mi facilitasse (=automatizzare) la creazione delle interfacce di gestione dei siti web. Ho creato per questo un’applicazione multiutente in grado di generare online servizi di gestione. Ecco quindi che, dopo aver installato Syntax, si deve solamente generare i servizi di cui si ha bisogno (news, articoli, prodotti…) collegarli l’un l’altro e assegnarli ad utenti voluti.
Ho iniziato lo sviluppo a metà del 2001 e ora, nel 2004 ha avuto il primo rilascio definitivo su internet.

Per iniziare

Licenza

Questo prodotto è coperto da licenza GNU.
Tutti coloro che useranno Syntax Desktop, dovranno includere nell’home page del proprio sito questo codice:

<a href="http://www.dynamick.it/syntax-desktop/" title="Syntax Desktop Content Management System">
    <img src="http://www.dynamick.it/syntax-desktop/logo.gif" alt="Syntax Desktop" border="0" />
</a>

Requisiti

Syntax Desktop è un sistema di gestione dei contenuti web-based. Necessita di questi requisiti per poter funzionare
LATO SERVER:

  • Apache
     
  • PHP (testato su versione 4.3.3)
    NB: per ora si deve disporre del register_globals=yes (anche se gran parte dell’applicazione è già stata testata con tale direttiva settata a no).
     
  • MySQL (oppure un altro db supportato da AdoDB, da testare)

LATO CLIENT:

  • Browser: Internet Explorer 6 è preferibile (mi spiace dirlo, ma le funzionalità che offre il browser di casa Micro$oft sono molto comode).
    Testato anche su mozilla (netscape, firefox) ma hanno limitazioni di funzionalità.
     

Installazione

Copia Files
Syntax Desktop necessita di essere copiato nella document root del web server (p.e. se la document root è /var/www/html/, allora syntax deve essere installato all’interno di questa directory, generalmente in /var/www/html/syntax desktop/).

Permessi
A questo punto devono essere assegnati i permessi di scrittura alle seguenti directory:

  • modules/dump/backup (per consentire di salvare i dump del database)
  • config/cfg.php (per consentire la modifica del file di configurazione)
  • modules/aa/custom (per generare i file "service" da poter personalizzare, solo per utenti avanzati)

Database
Accertarsi di disporre di un database Mysql già creato. Per si usano altri tipi di database, probabilmente syntax dovrebbe funzionare (non è mai stato testato), visto che usa il layer AdoDB che permette la connessione a diversi tipi di database. In questi casi configurare manualmente il file config/cfg.php. Altimenti procedere oltre.

Configurazione
Lanciare dal browser la directory http://www.miosito.it/syntax desktop/ . A questo punto Syntax mostrerà 2 schermate, una di seguito all’altra

  1. Configurazione del db
  2. Popolamento del database

Autenticazione

Per autenticarsi la prima volta, inserire questi dati
username: root
password: syntax

Per rendere sicuro il sistema, consiglio di cambiare i dati di autenticazione prima possibile.

Il desktop

Il desktop è logicamente diviso in queste aree:

  1. Menu, è la zona da dove si scelgono i servizi da eseguire. Il menu ha una struttura ad albero, quindi sotto una voce potrebbe esserci un sottomenu e così via. Per queste versioni si utilizza un widget DHTML che prevede una compatibilità solamente verso internet explorer. Un upgrade da fare è l’estensione della compatibilità ai browser della famiglia mozilla.
  2. Orologio, semplice orologio
     
  3. Desktop, la scrivania vera e propria dove verranno caricati e visualizzati i pannelli di controllo delle varie aree del sito (servizi). All’interno di quest’area verranno visualizzati i vari moduli presenti in syntax. Il modulo più importante è "AutoAdmin", un modulo integrato che gestisce l’intero desktop.
     
  4. Dati account, i dati con cui ci si è autenticati (utente e gruppo di appartenenza dell’utente)
  5. Logoff, il bottone di uscita dall’amministrazione

Gestione contenuti
 

Il sistema utente-gruppi-servizi

Definiamo innanzitutto questi tre termini:
utente: Entità che fa capo ad una persona fisica. Un utente possiede uno username ed una password per accedere al sistema. Sono predisposti altri campi (lingua, stile, ecc) che per ora non sono utilizzati.
gruppo: Insieme di utenti. Il gruppo ha la funzione di raggruppare gli utenti e di fornire un menu personalizzato. Quindi gli utenti dello stesso gruppo avranno a disposizione lo stesso menu. Il menu di ogni gruppo si gestisce cliccando il bottone PERMESSI.
servizio: Motore di gestione di un particolare contenuto. I servizi hanno il compito di gestire una parte del sito, come per esempio le news, gli iscritti e così via. Vengono organizzati in una struttura ad albero e vengono assegnati ai gruppi sotto forma di voci del menu

Ogni gruppo ha un proprio menu che può essere personalizzato dall’amministratore. Ogni menu contiene i servizi che sono abilitati al gruppo di utenti. Quindi al gruppo dei giornalisti, si inseriranno nel menu i servizi per la gestione degli articoli (articoli, news, editoriali). Al gruppo degli amministratori verranno abilitati i servizi di gestione degli utenti, gruppi e servizi.

Esempio

Dobbiamo creare un nuovo utente "pino" che abbia esclusivamente accesso alla gestione delle news.
Come fare

  • Creiamo un nuovo gruppo di utenti chiamato "gestori news". Clicchiamo sul menu [gestione contenuti->amministrazione->gruppi] per entrare nella sezione dedicata alla gestione dei gruppi. Qui clicchiamo sull’icona a destra per un creare nuovo gruppo (l’icona con un foglio bianco). Compare un modulo di inserimento dati. Nel campo name inseriamo la scritta "gestori news". Poi clicchiamo su "INSERISCI". Il nuovo gruppo ora è stato creato
  • Assegnamo i servizi al gruppo. Sempre rimanendo nella pagina dei gruppi [gestione contenuti->amministrazione->gruppi], clicchiamo sulla freccia verde PERMESSI in corrispondenza del nuovo gruppo appena creato. Vediamo che non ci sono servizi assegnati. Sempre tramite l’icona "nuovo" creiamo una nuova voce nel menu assegnandola al servizio "news". Comparirà un modulo di immissione dati:
    • name: gestione news (è il nome che comparirà nel menu)
    • service: News (il servizio da caricare). Se si lascia vuoto si crea una cartella dentro cui mettere altre voci di menu
       
    • order: 1 (l’ordine di comparsa all’interno del menu)
    • Filtro SQL:  (nulla, da lasciare vuoto). Serve per filtrare le righe. Da usare se volessimo visualizzare solo le news con la parola Verona.
    • Parent: [No Parent]. Indica dove posizionare la nuova voce di menu. Si può fare anche in modo visuale nella visualizzazione ad albero nella pagina principale.
  • Creiamo ora un utente. Clicchiamo su [gestione contenuti->amministrazione->utenti] e creiamo un nuovo utente cliccando sull’icona "nuovo documento".
    • login: pino (lo username dell’utente)
    • password: xxxxxx (la password che userà per l’accesso)
    • gruppo: gestori news (che abbiamo appena creato)
    • temaxx: –
    • lingua: –

Ora il nuovo utente pino potrà entrare nel sistema e gestire le news.

Service-o-matic

Questa sezione spiegherà in modo dettagliato come creare i servizi. Service-o-matic è lui stesso un servizio e lo si attiva cliccando su [Gestione contenuti->amministrazione->servizi->struttura]. Tutti gli altri sono stati generati in modo automatico da lui stesso. E’ per questo motivo che ritengo che la vera forza di Syntax sia proprio service-o-matic.
Quando si clicca su un servizio il motore di syntax cerca nel database la struttura del servizio e ne carica i dati. Quindi per aggiungere o togliere un campo, inserire, modficare o cancellare un servizio, basta semplicemente modificare la struttura presente sul db tramite service-o-matic.
Per iniziare clicchiamo su [gestione contenuti->amministrazione->Service-o-matic].
Inizialmente service-o-matic si presenta normalmente come tutti gli altri servizi. Viene mostrata la lista dei servizi a disposizione. Ecco le colonne che identificano un servizio:

  1. id: identificativo del servizio
  2. nome: nome del servizio
  3. tabella: tabella sul db che contiene la struttura e i dati gestiti dal servizio. Per esempio, il servizio news, conterrà i campi della news (struttura) e le news stesse (dati)
  4. percorso: service-o-matic è in grado di generare fisicamente un file php con lo scopo di essere poi modificato manualmente per gli utenti esperti. Normalmente service-o-matic non genera il file ma la visualizzazione del servizio avviene in modo dinamico sulla base della struttura del servizio presente sul database. Come vedete solamente service-o-matic ha, alla voce percorso, la scritta /ihtml/serviceomatic.php .
  5. Descrizione: descrizione del servizio
  6. DB sync: ha la funzione di sincronizzare la struttura del servizio con la tabella nel db. Se è spuntata, allinea i campi nel DB con la struttura imposta al servizio. Questa opzione è molto pericolosa (ma molto potente) perchè modifica la struttura delle tabelle. Usatela con cautela.
  7. Chiave inglese: serve per modificare la struttura del servizio
  8. Modifica e Cancellazione

Creazione di un nuovo servizio
Procediamo alla creazione di un nuovo servizio per la gestione degli articoli di un negozio. Clicchiamo sull’icona "nuovo documento".
STEP INIZIALE:

In rosso vengono evidenziate i campi obbligatori.

  • nome: il nome del servizio
  • tabella: il nome della tabella sul database. Se si omette, la nuova tabella sul database avrà lo stesso nome del servizio
  • descrizione: la descrizione del servizio
  • parametri: il numero di paramentri (campi) da gestire. Da tener presente anche la necessità di un campo chiave per identificare le righe. Quindi aggiungete sempre 1 al numero di parametri desiderato. (p.e. nome, descrizione, costo e in più aggiungete un campo id, quindi 4)
     
  • Sincronizza il db: genera una tabella sul db con la struttura che dettaglieremo nei prossimi passi. Non spuntarla se si dispone già di una tabella popolata di dati. In questo caso si dovrà modellare il servizio in base alla tabella già fatta
  • icona: icona associata al servizio. Sceglierla direttamente dalla lista sotto cliccando su quella desiderata.

Andiamo avanti

 

STEP 1

Specializziamo i parametri del servizio. Vengono visualizzate un numero di righe pari al numero di parametri impostati al passo precedente.
Per ogni riga definiamo:

  • Il tipo: Può essere un campo di testo, un checkbox, un menu a tendina, un campo di immissione di file, ecc. Preferibilmente impostare il primo campo del tipo "chiave". Sarà un campo numerico gestito da syntax che identifica le righe di quel particolare servizio.
  • Il nome del campo. Può essere per esempio "nome", "descrizione", "id", ecc…
  • Etichetta: è la scritta che compare nel modulo di modifica dei dati.
  • Help: descrizione della funzione del campo
  • join: serve per poter unire questo campo ad un’altro campo di un’altro servizio. Verranno presentati una lista dei servizi già presenti.
  • Order: ordine di visualizzazione del campo all’interno del modulo di modifica dei dati
     
  • order by: ordinamento iniziale delle righe per il campo prescelto.

STEP 2

Ultimo step. Sistemiamo gli ultimi valori. Ogni tipo di campo ha i propri dati da impostare. Quindi per un campo di testo imposteremo la lunghezza, per un campo di immissione di immagini, imposteremo la directory di destinazione, ecc
Lo spunto "genera il file php" impone a syntax di generare fisicamente un file autonomo che contiene il motore per la gestione del servizio. Questo permette la modifica direttamente sul codice per personalizzare il servizio.
Fine
Verrà infine chiesto a che gruppo aggiungere il servizio appena creato.
 

Modifica del servizio
La modifica del servizio avviene cliccando l’icona "chiave inglese" in corrispondenza del servizio desiderato. Si seguiranno gli stessi passi dell’inserimento, ma questa volta i campi saranno già popolati con i valori del servizio da modificare.

Template Engine

Il sistema di gestione delle pagine è semplice e lineare. I concetti da chiarire sono due:

  • pagine: sono le pagine che formano il sito. All’interno della pagina inseriamo il contenuto tramite un form visuale WYSIWYG, simile alle normali applicazioni office. Ogni pagina, al momento della compilazione, è resa tramite una directory che ha lo stesso nome della pagina. All’interno della directory ci sarà un file index.php che conterrà il testo della pagina. Tutto questo per avere un url ghiotto per i motori di ricerca. Per esempio, http://www.miosito.it/la storia/ oppure http://www.miosito.it/i prodotti/
  • template: è il modello grafico, la cornice che contiene il contenuto della pagina. Il template è gestito dal motore smarty.php.net, quindi si possono inserire tutti i tag specifici di smarty.  Il template può essere scelto tra i file della directory  [syntaxroot]/public/template/  oppure può essere creata al volo nell’apposita area di testo WYSIWYG. In quest’ultimo caso si deve avere l’accortezza di racchiudere il template tra due righe di comando
    {include file="header.tpl" }
    ….template….
    {include file="footer.tpl"}
    dove header.tpl è un file messo nella dir [syntaxroot]/public/template/ che contiene l’header (<html><head>….</head><body>) di un file html e
    footer.tml è il file che contiene la chiusura del file html (</body></html>)

La struttura delle pagine può essere gestita tramite la struttura ad albero nella parte sinistra del desktop. E’ possibile fare un drag ‘n drop delle pagine, per strutturare meglio il sito. Importante è ricordarsi di cliccare "salva le modifiche" posto sotto alla struttura dell’albero.

Importante: Per rendere effittive le modifiche sulla struttura bisogna compilare le pagine cliccando sul bottone rosso "compila"

Tag
 

All’interno dei template è possibile inserire tag specifici che poi il motore smarty interpreterà.
Questi tag hanno la seguente forma:
{nomefunzione parametro1="valore1" parametro2="valore2"}
dove:

  • nomefunzione è il nome della funzione da richiamare. Le funzioni risiedono nella directory [syntaxroot]/public/plugin e vengono caricate automaticamente da smarty. Per creare nuove funzioni basta inserire un nuovo file all’interno di questa directory col nome di function.nomefunzione.php
     
  • parametro1 è il nome del parametro da passare alla funzione nomefunzione
  • valore1 è il valore del parametro1
  • parametro2 e valore2 come parametro1 e valore1

Alcune funzioni sono già state create come:

  • {menu} restituisce la lista delle pagine del sito
  • {page} inserisce il contenuto della pagina
  • {news} inserisce il contenuto della news
  • {listaNews} elenca le ultime 3 news

Per il momento, Syntax non prevede funzioni automatiche che uniscono i servizi creati dall’utente con il sistema a template. Occorre quindi, dopo aver creato il servizio, scrivere una funzione (plugin) che prenda il contenuto gestito dal servizio e che lo interfacci col sito. Come è stato fatto con {news} e {listaNews} per il servizio news.

Per maggiori informazioni su smarty, visitate il sito ufficiale http://smarty.php.net

Strumenti

Alla voce strumenti, Syntax Desktop fornisce alcuni servizi per la manutenzione e personalizzazione dell’applicazione.

  • Visualizza il sito: per visualizzare il sito all’interno di Syntax Desktop
  • Contatta l’amministratore: per spedire un’email direttamente all’amministratore
  • FileManager: simile ad un piccolo client ftp per gestire i file (ancora da implementare)
     
  • Shell: una shell (dove è permessa) per gestire direttamente il server.
  • Ripristina il database: per caricare una copia di backup del database precedentemente salvata.
  • Salva il database: per creare un backup dello stato attuale del database
  • Impostazioni: per vedere i parametri di configurazione del db
  • Debug: flag per attivare il debug
  • Sfondo: per cambiare lo sfondo di Syntax
  • Stile: per modificare i colori di Syntax
  • Disconnetti: per cambiare identità e ritornare anonimo
     
  • Esci: per chiudere la finestra.

Informazioni aggiuntive
 

Michele Gobbi
Verona, 24 Maggio 2004
www.dynamick.it
info@dynamick.it