Download - Shellmanager096
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
1
ShellManager Version 0.9.6
native component for Joomla! 1.6 / 1.7 www.dazo.it
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
2
Creare un nuovo componente
Dopo aver istallato shellmanager possiamo creare dei veri e propri componenti per Joomla.
Clicchiamo su Nuovo. Apparirà un form in cui inserire le prime informazioni per la creazione del
nostro componente.
Titolo: il nome del componente
Scegli la tabella: La tabella a cui collegare il componente. Ogni componente è collegato ad una
tabella. Da questa tabella poi si gestiranno gli elenchi e il form di inserimento lato amministrazione.
Icona: Scegli un icona da associare al componente.
Versione: I componenti creati con shellmanager possono essere esportati ed installati in altri siti
per cui è importante gestire la versione che si sta sviluppando. Dopo che abbiamo creato un
componente e desideriamo modificarlo possiamo prima cambiare il numero di versione così ché
quando esportiamo la nuova versione verrà creato anche un sistema di update dalle versioni
precedenti.
Licenza/Autore/Email/Copyright/Descrizione: sono informazioni opzionali che vengono salvate
quando si esporta il componente.
Dopo aver fatto salva ci si trova in una seconda schermata che mostra ulteriori parametri.
Gestione dei dati: E‟ possibile creare due tipi di componenti, uno classico in cui verranno gestiti
gli elenchi degli articoli da cui poi accedere alla modifica dei singoli dati e un altro sistema in cui
mostrare direttamente il form di modifica collegato ad uno specifico record del db.
(Edit) appare solo se viene scelto di modificare un solo record e identifica il campo che si desidera
mostrare.
Query: E‟ possibile modificare la query che estrae i dati degli elenchi per impostarne un
ordinamento prestabilito oppure per filtrare i dati da visualizzare.
Numero di records per pagina: La paginazione di default
Parametri template (Se non avete specifiche esigenze potete lasciare questi dati così come sono)
Template Edit: è il template del form di inserimento.
Template display e Template Lista sono i template degli elenchi
Icona: E‟ l‟icona da associare al componente
Titolo E‟ il titolo del componente.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
3
Approfondimenti:
Le versioni
Come avrete notato abbiamo due versioni della nostra bacheca, una senza form e una con il form
di inserimento. Proviamo ad installare la versione 1 su di un altro sito. Giustamente ancora non
abbiamo il form lato utente che abbiamo creato soltanto successivamente alla prima versione, ma
se senza rimuovere la prima versione installiamo sopra la seconda ecco che il form appare
aggiornando la versione corrente. Ovviamente è possibile istallare il componente direttamente alla
versione 2.
Attenzione!
Questo sistema funziona solo aggiornando dalla versione precedente all‟ultima ma se esisteva
una versione 3 del nostro componente non possiamo installare dalla 1 direttamente la 3 senza la
due.
Note sulla creazione dei componenti
Sia i file di lingua che l‟xml con i parametri non vengono gestiti da ShellManager per la parte di
modifica, tuttavia possono essere modificati manualmente.
Gestione dei titolo nei componenti lato amministrazione
In amministrazione ogni pagina dei componenti che create hanno un titolo. Questo può essere
settato da shellManager >modifica e modificare il campo titolo.
All‟interno del titolo possono essere usate le seguenti variabili
%task% che generalmente sarà DISPLAY_ARTICLE, NEW_ARTICLE o EDIT_ARTICLE (nel file di
lingua potete poi inserire il nome più appropriato da far apparire
%parentTitle% carica il titolo del componente padre.
%firstTitle% carica il titolo del componente di primo livello. Ad esempio se abbiano un componente
nazione che ha un figlio regione che a sua volta ha un figlio provincia
Nel titolo provincia possiamo scrivere %firstTitle% per inserire inizialmente il titolo originario del
record che stiamo modificando. Se nel titolo del componente padre vi era già una variabile %task%
questa viene rimossa.
%pathTitle% stampa il percorso del componente che si sta visualizzando. Usando l‟esempio
precedente stamerà /regione/provincia.
%customVariable% ovviamente si possono richiamare tutte le variabili passate in get, post o lette
all‟interno del record che si sta modificando scrivendo, come di consueto, il nome della variabile
che si desidera stampare
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
4
Database
Permette di modificare la tabella collegata al componente. Puoi creare o rimuovere campi del
database di Joomla e definirne i tipi. Quando si crea un campo viene chiesto se aggiungerlo al
form, all‟elenco e/o ai template. Queste sono degli automatismi per semplificare la creazione del
componente in quanto creano i record per poter poi modificare e visualizzare il nuovo campo
inserito. E‟ da tenere presente che comunque queste operazioni possono essere fatte in un
secondo tempo manualmente. Per ultimo è stata inserita la possibilità di creare un campo per il
collegamento alle categorie. Questa operazione non crea di per sé campi particolari nel database,
bensì si occupa di gestire quelle operazioni che servono per gestire il campo creato con le
categorie di Joomla!. Anche in questo caso è possibile ripetere le operazioni manualmente, ma
non essendo ovvie è consigliato creare il collegamento attraverso questo sistema.
I tipi di campi sono:
Testo piccolo (VarChar 250) permette di inserire un testo al massimo di 250 caratteri
Testo grande (Text) permette di inserire un testo di grandi dimensioni
Numero (int)
Data (DateTime) permette di inserire una data
Categoria questo è l‟unico campo speciale e crea i file necessari a collegare le categorie
all‟articolo.
List
Genera l‟elenco degli articoli del componente che verrà visualizzato lato amministrazione. E‟ un
elenco e serve generalmente per poter scegliere l‟articolo da modificare. Attenzione come regola
generale evitate di inserire più volte lo stesso campo.
Button
Sono i comandi che si trovano in alto a destra e servono per gestire le operazioni che si possono
fare all‟interno della pagina. Questi vengono generati automaticamente ed quindi raro che si abbia
bisogno di intervenire su di essi. L‟aggiunta di un bottone non significa automaticamente che
vengono aggiunte anche le operazioni necessarie al funzionamento.
Form
Gestisce i campi che possono essere creati e/o modificati all‟interno del componente
Views
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
5
Mostra l‟elenco dei template adibiti alla visualizzazione del componente. Una volta creato un nuovo
template può essere collegato al menù di Joomla! come già avviene per gli altri componenti. Le
view gestiscono le query di estrazione in modo del tutto indipendente dal lato amministrativo
consentendo così una maggiore flessibilità dei contenuti. Le query come altri parametri possono
essere modificate cliccando sul titolo della view (oppure selezionando la riga e premendo
modifica). Qui possiamo accedere ai seguenti comandi:
Template
Dopo aver creato le query necessarie alla visualizzazione di tutti i dati si può passare alla
creazione di un template ovvero di come questi dati verranno visualizzati nel sito. Il form
genera in automatico alcuni modelli di template che tuttavia possono essere modificati
manualmente (Modifica template). Quest‟ultima operazione non permette di ritornare a
generare il template in automatico per cui è bene finché possibile non usarla. Il workflow
ideale è quindi quello di creare tutto il template senza modificare il codice php e solo alla
fine, se indispensabile andare ad intervenire sul codice. E‟ invece possibile modificare
piccole sezioni di codice attraverso il bottone PHP. Il codice php modificato viene
comunque sovrascritto se si rigenera il template a patto che non venga inserito il lucchetto
sulla colonna stampa.
Addnew
Aggiugne una view figlia. Per semplificare faccio subito un esempio: Mettiamo di voler
creare una gallery. Questa sarà gestita da due tabelle, una con il titolo e la categoria
(gallery), un'altra con le immagini (un record per ogni immagine). Quindi quando creiamo le
view dovremo creare una view principale con il titolo ed una secondaria (figlia) con le
immagini. In questo modo quando viene visualizzata una gallery avremo una prima query in
cui è caricato il titolo e la categoria, una seconda con l‟elenco delle immagini. In questo
esempio il template che alla fine gestirà padre e figlio sarà comunque il template del padre.
Infatti dopo aver creato la view figlia se andiamo a vedere il sistema per generare il
template, questo avrà inserito anche tutti i campi della seconda query.
Ricerca
Gestisce i campi di ricerca che appariranno nel sito.
Collega
Permette di collegare una view agli articoli di Joomla!. Continuando l‟esempio precedente
potremmo voler visualizzare gli articoli con delle gallery. Una volta collegata una view agli
articoli apparirà il collegamento sul form di inserimento degli articoli stessi.
Rimuovi collegamento
Il bottone appare quando una view è collegata ad un articolo e ne permette la rimozione.
Form
Lo si usa quando siha la necessità di creare form lato. Affinché quest‟ultimo possa essere
visualizzato dopo aver creato il form bisogna rigenerare il template. Esistono
prevalentemente due sistemi di visualizzazione: Il primo è quello di generare il template
lasciando come unico campo stampabile appunto il form. In questo modo ne verrà creato
sempre un solo (come tipo di template scegliete articolo singolo). Il secondo caso invece è
quello di stampare il form insieme ai dati estratti dalla view. In questo modo verrà generato
un form per ogni record (può essere usato ad esempio per gestire un bottone “vota
l‟articolo”).
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
6
Add new
Come per le view l‟add new dei componenti crea un nuovo controller figlio.
Esporta
Genera il componente affinché possa essere esportato ed installato nuovamente su un altro
Joomla. Affinché i componenti creati con ShellManager possano continuare a funzionare è
necessario che sul sito di destinazione sia presente già un‟istallazione di ShellManager.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
7
Tutorial Bacheca
Creiamo un nuovo componente da titolo Bacheca Utenti e collegato ad una nuova tabella bacheca
utenti
Fate salva e alla schermata successiva salva e chiudi.
Adesso creiamo il database. Questo dovrà contenere un testo, il nome dell‟autore, la data di
inserimento e se il commento è approvato oppure no. Andando su database potete aggiungere i
campi così da avere uno schema simile alla seguente figura
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
8
Una volta creati tutti i campi premete il bottone torna indietro per ritornare all’elenco di componenti di
shellmanager.
Ora modifichiamo il List ovvero come verranno mostrati i dati nell’elenco lato amministrazione. Come
potrete notare questo è già stato in parte popolato, quello che dobbiamo fare è migliorarne l‟aspetto
per renderlo più funzionale.
Clicchiamo su testo e dentro parametri
testo > attiva link scegliamo si.
Per la data scegliamo formatta il campo
come data in basso a sinistra mentre per
l‟approvazione scegliamo “Crea una
colonna con dei bottoni a seconda dei
valori che il campo assume.”. Quest‟ultima
funzione permette di creare dei bottoni
come quelli che per gli articoli definiscono
se pubblicati oppure no. In questo caso
nei Parametri bottoni inserite quale
immagine deve apparire se il valore è 0 e
in quale valore dovrà essere modificato se
si premerà sull‟immagine così come è
illustrato nella figura.
Saltiamo il comando button e passiamo al form.
Qui modifichiamo testo come editor, data come calendar e approvato come checkbox.
Il lato amministrativo è finito, ora possiamo andare a vedere il risultato:
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
9
Le query Questo capitolo è essenziale per capire il funzionamento della struttura del
componente quindi leggetelo !!!
Le query sono le interrogazioni al database. Do per scontato che sappiate già scrivere una query
di base, quello che spiegherò in questa sezione è come ShellManager gestisce le query.
Partiamo dal lato amministrazione. Le query in amministrazione servono per visualizzare i dati
degli elenchi. Quando si genera un componente viene generata una query del tipo SELECT *
FROM #__miatabella LIMIT 0, 20. Il limite viene gestito dal valore che viene inserito sul campo
paginazione. Se tuttavia si vuole modificare la query che estrae i dati ad esempio vogliamo che il
nostro componente visualizzi solo le categorie di una data estensione o solo gli articoli di un
determinato autore è possibile modificare le query attraverso i filterstr. Questi generano porzioni di
query che poi vengono tutte ricomposte quando il componente che avete creato deve eseguire la
query.
Sempre in amministrazione è possibile annidare i componenti uno dentro l‟altro così da creare
delle relazioni tra tabelle. Ad esempio shellgallery a come componente figlio shellgalleryimages
che contiene l‟elenco di tutte le immagini di una singola gallery. In realtà shellgalleryimages non è
un vero e proprio componente, ma soltanto un ulteriore controller del componente principale.
Esistono due modi per collegare un controller ad un componente principale, o tramite un campo
collegato (quindi con un tipo di relazione 1:N) oppure tramite una relazione 1:1; In tutt‟e due i casi
quando si crea un controller bisogna specificare il campo che identifica il collegamento e che
memorizzerà l‟id del componente principale. La differenza quindi tra i due tipi di gestione dei dati
consiste nel fatto che nel caso di una relazione 1:N quando si andrà a modificare i dati del
controller si passerà prima in una schermata con l‟elenco dei dati collegati da cui poi si potrà
aggiungere/rimuover/modificare i vari record. Nel caso invece di relazioni 1:1 quando si
visualizzano i dati collegati verrà visualizzato unicamente il form di modifica.
Ogni volta che si genera un controller viene anche generato un bottone nel componente principale
che porta dal form di inserimento a visualizzare i contenuti correlati. Dalla versione 0.9.5 è
possibile visualizzare i dati delle tabelle correlate all‟interno del form di inserimento del
componente principale attraverso l‟uso del campo subform (lo si può creare quando si crea il form
per la gestione dei dati). Anche in questo caso potete vedere un esempio in shellgallery.
Dal lato utente le view non si differenziano particolarmente dal discorso appena fatto se non per il
fatto che per ogni view possono essere eseguite contemporaneamente le query della view
corrente, delle view figlie e della view padre (nel caso siano presenti ovviamente). Quindi
prendendo sempre come esempio ShellGallery la view galley_single esegue sia la sua query che
quella di list_of_images. Il campo di collegamento tra le view principali e le view figlie è identificato
dal campo accanto all‟elenco a tendina da cui si sceglie la tabella . In realtà la scelta di questo
campo nelle view collegate non fa altro che aggiungere alla query una clausola WHERE all‟interno
di filterstr5 (il fatto che sia sul 5 non è rilevante). Quindi se andiamo a vedere la query di
list_of_images vedremo che è
SELECT * FROM josk_shellgalleryimages WHERE josk_shellgalleryimages.collid = 'var[id]'
Dove „var[id]‟ è l‟id della tabella principale (gallery_single).
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
10
Se il campo delle tabelle delle
view figlie non fa altro che
generare un filterstr, il campo
della tabella della view che si sta
visualizzando identifica invece
quale campo verrà usato per
filtrare i dati attraverso l‟url
richiesto. Cosa vuol dire? Negli
url di ShellManager sono
composti di base da tre parametri
option, view e id. Se ad esempio
vogliamo visualizzare un solo
record possiamo passare nell‟url
l‟id del record da visualizzare.
Tuttavia se vogliamo fare le cose un po‟ più raffinate invece di passare l‟id possiamo passare una
stringa e dire alla query con quale campo compararla. Ad esempio su ShellGallery per visualizzare
i singoli album fotografici viene passata nell‟url l‟alias e quindi sulla tabella è stato segnato il campo
alias come campo di riferimento da comparare. Quindi la query è del tipo avra
WHERE #__shellgallery.alias = 'var[id]'
Da notare che il parametro passato nell‟url non è importante se è un alias, un id, un array o che
altro, questo sarà sempre memorizzato come Id ($_GET(“id”)).
Ricapitolando quando creiamo una view annidata possiamo usufruire della query nella view
principale (e quindi i dati verranno gestiti e visualizzati dal template della view principale), ma
possiamo anche decidere di creare un template nella view figlia e quindi linkare alla view figlia e
visualizzarla.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
11
I Filterstr
Abbiamo detto che le query si creano aggiungendo filterstr, quindi vediamo nel dettaglio come
funzionano:
Where: aggiunge una clausola per filtrare i dati dove il valore del confronto può essere o una
costante (Stringa) e quindi scrivete semplicemente la stringa (es: nome_utente = Giulio) sul valore
di confronto scrivete Giulio (un esempio più comune : published = 1, valore di confronto scrivete 1)
oppure una variabile. Le variabili sono scritte tra due percentuali quindi ad esempio il valore di
confronto è %id% . Ma dove prende questo id? Le variabili in shellmanager vengono cercate prima
tra le query principali, poi dall‟url, dai valori passati in post o alcune volte cercando anche tra i
valori in sessione.
LEFT JOIN: Se in un campo si ha un riferimento ad un id di un‟altra tabella potete rich iamare un
campo di quest‟ultima all‟interno della vostra query. Ad esempio se abbiamo il campo id_categoria
usando un left join possiamo richiamare il nome della categoria. E‟ importante che il collegamento
ritorni un solo risultato. Nel caso tornassero più risultati la query non da errore, ma vengono
duplicati tutte le righe per il numero di risultati del left join.
Campo di destinazione è generalmente l‟id della tabella da richiamare. Campo di origine è il campo
in cui abbiamo memorizzato l‟id. Campo da aggiungere è il nome che vogliamo poter stampare. Il
campo da aggiungere e il campo di destinazione devono far parte della stessa tabella altrimenti la
query darà errore. Su nuovo nome del campo potete scrivere qualsiasi cosa. Questa sarà il nome
della variabile in cui verrà memorizzata il risultato del campo da aggiungere. Anche qui una piccola
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
12
accortezza, il nome della variabile non deve avere né spazi ne caratteri strani. E‟ possibile
aggiungere più left join alla stessa tabella, tuttavia in questo caso farà fede sempre e solo il primo
campo di destinazione aggiunto.
ORDER BY: serve per ordinare i risultati della query.
Publish: Se nella vostra tabella esiste un campo published che assume il valore 1 quando
l‟articolo è pubblicato è possibile usare questo campo per gestire la pubblicazione dell‟articolo. In
più in modo facoltativo possono essere gestite anche la data di pubblicazione e fine pubblicazione.
Custom Query: Questo campo permette di inserire una porzione di query scritta da voi. Potete
aggiungere SELECT, FROM, LEFT JOIN, WHERE e ORDER BY. Ad esempio potete scrivere
WHERE color = 1 OR color = 3
Questa clausola verrà aggiunta al resto della query. Non c‟è quindi bisogno di scrivere tutta la
query, basta inserire la porzione di cui avete bisogno. Se ad esempio accanto a questa custom
query aggiungiamo nel filtro successivo una clausola WHERE id > 5 la query che verrà generata
sarà:
SELECT * FROM #_mia tabella WHERE (color = 1 OR color = 3) AND id > 5;
Da notare quindi che i filtri WHERE vengono collegati tra loro da l‟operatore AND per cui situazioni
particolari possono aver bisogno dell‟aggiunta di parti di query scritte a mano.
SubQuery: Le subquery sono query che vengono eseguite per ogni risultato dalla query
principale. Il concetto è molto simile alle view figlie, tuttavia queste non vengono visualizzate nel
template per cui per poterle usare devono essere poi richiamate attraverso campo code (quindi
dovete scrivervi il codice php a mano). Le subquery sopperiscono al limite di un solo livello di
annidamento delle view (limite che non esiste per la creazione di componenti nel lato
amministrativo). Questo limite è stato inserito per evitare di creare strutture in cui venissero
generate centinaia di query per pagina. Quindi fate molta attenzione nell‟uso delle SubQuery!
Usare i risultati delle SubQuery:
Se la subquery è stata generata nella view principale il codice per stampare l‟array è
<?php print_r ($data[$y]->subQuery0[0]); ?>
Se avete inserito più subquery la prima si chiamerà subQuery0, la seconda subQuery1 e così via.
Se invece stiamo richiamando una subquery generata da una view figlia che ad esempio si chiama
CICLO LIST_OF_IMAGES_ROWS scriveremo
<?php print_r ($data[$y]->list_of_images_rows[$z]->subQuery0); ?>
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
13
I Form di inserimento
Introduzione
Quando si crea un form questo è composto da una serie di campi racchiusi all‟interno di fieldset. I
fieldset sono quindi gruppi che racchiudono una serie di campi e provvedono sia all‟impaginazione
che alla riorganizzazione logica dei form. I label e le descrizioni accettano anche variabili dei file di
traduzione così da rendere nel caso il form multilingua. E‟ possibile rielaborare i dati prima del
salvataggio attraverso i filtri oppure non collegare il campo a nessuna tabella per effettuare una
successiva rielaborazione prima del salvataggio direttamente in php. In amministrazione all‟interno
del componente appena creato avete a disposizione nella cartella controller la classe per
rielaborare i dati nelle varie fasi di inserimento. Potete seguire gli esempi all‟interno dei controller di
ShellManager stesso per capirne il funzionamento.
Collegamento al database
Per ogni campo è possibile scegliere il collegamento al database, creare un nuovo campo del
database in cui inserire i risultato oppure non collegare il campo a nulla. Quest‟ultima opzione è
valida per i campi inseriti in fieldset che contengono dei parametri, sia per memorizzare campi da
rielaborare in fase di inserimento.
Possibili campi
Hidden, text e textarea Sono i classici campi hidden, text e textarea.
CustomField (Utenti esperti): Se desiderate usare un campo di cui avete scritto il codice o che fa
parte dei fields di Joomla potete caricarlo usando questo campo.
Nome: Il nome del campo che si sta richiamando
Parametri: I parametri per personalizzare il campo scritti in Json
Alias Crea un unico (Quindi non si possono avere due valori uguali nella stessa tabella) in cui dati
sono formattati per essere accettati nelle url (quindi senza spazi o caratteri speciali). Può essere
utilizzato al posto dell‟id per chiamare le pagine in cui si desidera avere un url ottimizzato per il seo
Image (Al suo posto si può anche usare file) Crea un campo in cui caricare le immagini
Scegli la directory: Scegli la cartella all‟interno di images/ in cui salvare i file caricati.
Radio Crea un‟elenco di opzioni che possono essere selezionate una in esclusione dell‟altra.
Opzioni: I valori di una radio sono scritti qui in formato testo ante dividendo le varie opzioni
con il punto e virgola. Si può anche inserire un label dividendolo con i :. Es 0:no;1:si
Impaginazione: Scegli come impaginare i dati
Attiva show/hide fieldset: Da la possibilità di far apparire delle porzioni di form a seconda
dell‟opzione scelta dall‟utente.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
14
List Crea un elenco a tendina.
Opzioni: Le opzioni dell‟elenco divise da punto e virgola. Si può anche inserire un label
dividendolo con i :. Es 0:no;1:si
ListTable L‟elenco delle tabelle del database
listColumns L‟elenco dei campi di una tabella
listselectbyquery Crea un elenco a tendina con dei dati estratti dal database.
Tabella: La tabella da cui estrarre i dati
Query: la query da eseguire. I valori che deve tornare la query sono id e title.
listTableColumn Crea un elenco a tendina in cui mostrare l‟elenco delle tabelle e i relativi campi
calendar Crea un campo in cui inserire la data
Formato della data: il formato in cui visualizzare la data (Queste opzioni possono essere
cambiate dal file di lingua)
Data predefinita: Se ancora non è stata salvata nessuna data può essere inserita la data
odierna
Fieldset Tutti i campi devono essere racchiusi da uno o più fieldset. Questi raggruppano porzioni
di form e ne provvedono all‟impaginazione.
Impaginazione: Se mostrare a tutta pagina, a sinistra, oppure a destra il fieldset. Se si
decide di mostrare a destra bisogna che il fieldset precedente sia mostrato a sinistra.
Associa a un campo: E‟ possibile associare tutti i campi di un fieldset ad un unico campo
del database. In questo caso i dati verranno salvati in formato Json. Se si associa un
campo nel fieldset tutti i campi al suo interno non dovranno essere collegati ad alcun
campo del database
Mostra solo se: Se vi sono campi in cui è attiva l‟opzione show/hide Fieldset è possibile
selezionare l‟opzione a cui associare il fieldset così da mostrare il gruppo di campi solo nel
caso che l‟utente abbia selezionato quella specifica opzione
Editor Crea un campo formattato in html
Mycategory Crea un campo in cui collegare le categorie.
Gruppo di categorie per: Le categorie sono collegate ai componenti per cui è importante
filtrarle per mostrare solo le categorie relative al componente che si sta usando. Se ad
esempio volessimo mostrare le categorie degli articoli inseriremmo qui „com_content‟
Categorie multiple: Se si desidera poter far aggiungere ad un utente più categorie queste
verranno salvate in formato JSon.
Folderlist L‟elenco delle cartelle di images
File Permette di caricare un file. Se è un‟immagine da la possibilità di elaborarla definendone le
dimensioni e nel caso la creazione di una thumbs.
Accesslevel L‟elenco dei gruppi di accesso lato utente (public/register/special)
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
15
User Crea un campo in cui selezionare un utente di Joomla
UserGroup Crea l‟elenco dei gruppi dei permessi di accesso.
ArticleLink Crea un campo in cui collegare un articolo
Checkbox Crea un checkbox
Checkboxes Crea un elenco di checkbox. I dati verranno salvati in formato JSon.
Color Crea un pickcolor per selezionare un colore.
UserGroups Un campo in cui selezionare più usergroup
Users Un campo in cui selezionare più utenti
Multiselect (Utenti esperti) Crea un elenco a tendina secondo dei parametri avanzati
IFrame (v0.9.5)
In questo campo è possibile caricare un altro form all‟interno di un iframe.
Option: il nome del componente da form da eseguire
View: La view da eseguire (queste informazioni potete trovarle caricando il form che
desiderate collegare e guardando l‟url generata da Joomla)
Campo collegato: Questo campo deve essere lo stesso che collega il form di orgine da
quello di destinazione
Valore: Il valore del campo collegato. E‟ possibile inserire sia una costante che una
variabile. Se ad esempio scriveremo id il programma andrà a reperire l‟id passato nell‟url.
Altezza: l‟altezza dell‟iframe espressa in pixel
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
16
Le View
Le view sono gli elementi che vengono visualizzati nel sito. Ogni View è indipendente e può essere
collegata ad una query che ne estrae i dati.
Title:
Da questo link è possibile gestire la query della view e le opzioni di integrazione con Joomla.
Detail:
Title: il nome della view
Create a module: Se selezionata verrà creato un modulo invece di un view del
componente
Tipo: E‟ possibile creare view che visualizzano query o view in cui scrivere il
codice php senza che vengano estratte in automatico le query
Description: è un campo in cui annotare come e quando usare la view creata
Option & Seo
Attenzione queste opzioni sono collegate alla tabella corrente. Se viene cambiata la tabella
è importante salvare e successivamente reimpostare i valori desiderati. La maggior parte di
queste opzioni si attivano unicamente se viene estratto un singolo risultato e non
funzionano nei casi di elenchi.
Static title: Il titolo della pagina
Add title: Se si desidera è possibile collegare un campo della query al titolo della
pagina
Default Metakey: E‟ un‟opzione seo per definire delle chiavi statiche
Default description : E‟ un‟opzione seo per definire la descrizione della pagina
Add keywords: E‟ possibile scegliere un campo per popolare le keywords della
pagina
Add description: E‟ possibile scegliere un campo per popolare la description
della pagina
Category: Se tra i dati estratti esiste un campo che identifica l‟id di una categoria
è consigliabile inserirlo per avere a disposizione le opzioni della categoria stessa
quali il breadcrumbs, l‟access della categoria e le relative impostazioni seo
Access: Ogni pagina può essere protetta da un livello di accesso dinamico scelto tra i campi
estratti dalla query della view
User Access: E‟ possibile limitare l‟accesso ad una view ad un solo utente o ad un gruppo di utenti
definito in un campo della tabella. Nel caso di gruppi di utenti questi possono essere popolati in
amministrazione usando un campo users che salva un testo formattato in JParameter.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
17
url menu: In alcuni casi particolari può essere necessario poter filtrare i dati che
verranno estratti a seconda del menu che si crea. Con questa opzione è
possibile aggiungere un campo tra i parametri della view nella creazione delle
voci di menu in cui scegliere una categoria o inserire un testo con il quale filtrare
i dati. I dati del testo vengono filtrati attraverso l‟id. Il campo associato all‟id può
essere scelto nella tabella
search: Se si desidera creare dei form di ricerca questi sono associati per
default alla view su cui vengono creati. E‟ quindi possibile accettare solo i filtri
inerenti alla view creata o qualsiasi filtro che venga passato. Questo secondo
caso deve essere usato con attenzione perché potrebbe generare errori nella
query di estrazione, ma è utile se si vuole filtrare i dati attraverso la creazione di
un modulo di ricerca.
Parameter
The view's query: Qui viene mostrata la query che verrà eseguita. Per
modificare la query usate i filterStr poco più in basso. Se il debug di Joomla è
attivo questa opzione viene disabilitata.
Table: Questo è il campo più importante di tutto il form ed identifica la tabella su
cui verrà eseguita la query. L‟elenco dei campi che segue serve poi ad
identificare su quale valore l‟id dell‟url deve essere associato. Tutti gli url
generati da shellmanager sono infatti basati su tre soli valori:
Option che identifica il componente da eseguire
View che identifica la view
Id che serve a filtrare i risultati. Quest‟ultimo segmento non deve per forza
essere associato all‟id, ma può essere invece collegato al altri campi della
tabella come ad esempio ad una categoria o se si desidera creare un url friendly
ad un campo alias. Nelle view figlie invece il campo della tabella identifica
invece il collegamento alla tabella principale.
filterStr: Attraverso questa serie di opzioni è possibile modificare le query che
vengono create.
Number of records per page: E‟ il limite dei records da visualizzare per pagina.
Quando si visualizza un singolo articolo, anche se siete sicuri che la query
ritornerà un singolo risultato inserite ugualmente 1 in questo campo per
comunicare alla programma che il risultato e sarà unico.
Template no results: Se la query non ritorna risultati è possibile scegliere di
visualizzare un‟altra view. Qui dovete scriverne il nome corretto.
Run duplicate query: Se create view figlie che puntano alla stessa tabella potete
scegliere se eseguire queste query oppure no. In una struttura standard formata
da una view padre in cui si visualizzano l‟elenco degli articoli collegata ad una
view figlia che visualizza i dettagli di un singolo articolo, le due view puntano alla
stessa tabella e non vi è necessita che durante la visualizzazione dell‟elenco
venga eseguita la query figlia.
Load child view: Anche qui potete scegliere se eseguire le query delle view figlie
oppure richiedere unicamente il totale dei dati estratti.
Template pagination link: Per ogni pagina creata con ShellManager è permessa
una sola paginazione, tuttavia è possibile scegliere a quale view impostare la
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
18
paginazione. Ad esempio in un articolo con i commenti può essere più utile
avere la paginazione sui commenti che non sull‟articolo stesso.
Template
Veniamo alla grande novità della versione 0.9.5 la creazione delle view. A differenza delle versioni
precedenti in cui si potevano scegliere solo poche opzioni per ogni campo, ora è possibile creare
le opzioni che si vogliono visualizzare e personalizzarle attraverso specifici form. Il codice è stato
completamente riscritto permettendo di creare un sistema modulare ed espandibile per le versioni
future. Oltretutto se prima la creazione delle view si poggiava su di una tabella in cui memorizzare i
dati, ora le view sono indipendenti dal database permettendo quindi una gestione più versatile e
permettendo di creare degli ibridi in cui scrivere sia codice php che lasciare la possibilità di
personalizzare alcune opzioni da interfaccia.
Questa pagina genera fisicamente un codice php che sarà poi la pagina visualizzata. Ovviamente
se si prova a cambiare la query di estrazione dei dati la view deve essere rigenerata altrimenti darà
errore.
Iniziamo dai bottoni:
Torna indietro: ritorna a shellmanager
Elenco view: torna all‟elenco delle view
Crea XML: crea l‟xml con le opzioni da visualizzare quando si crea una nuova voce di menu.
Go back: Torna al template precedente alle ultime modifiche apportate. Si può tornare al
massimo 9 volte indietro.
Crea template: Dopo aver configurato le varie opzioni premete crea template per rigenerare il
template (E‟ un po‟ come salva). Fate molta attenzione perché bisogna seguire delle regole nella
configurazione di queste opzioni e sono:
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
19
Se si aggiunge un campo da visualizzare (ADD) non verranno salvate ulteriori
modifiche ad altri campi. Quindi se dovete aggiungere un campo o una porzione di
codice selezionate ADD scegliete cosa aggiungere, ma non modificate null‟altro,
tanto non verrà salvato
Se si sceglie di modificare il codice di una riga questa si trasforma in un campo
CODE
Se si modifica un ciclo verranno modificati tutti campi che fanno parte del ciclo
stesso quindi scegliete le opzioni del FORM del ciclo, cambiate le opzioni e ricreate
il template prima di modificare eventuali altre opzioni.
Non è possibile attraverso l‟ordinamento portare campi all‟interno o all‟esterno di
cicli diversi
Non aggiungete mai commenti scritti con /* */
Il primo campo deve essere sempre un campo CODE e non può essere eliminato.
Il fatto che le view generano il codice php ha l‟enorme vantaggio di essere
fortemente personalizzabili e di avere un impiego di risorse relativamente contenuto
rispetto ai normali cck, tuttavia può capitare che il codice generato dia errore. I casi
più comuni sono:
o Se si cambia la query e non si ricrea la view
o Se si cerca di visualizzare un campo in modo sbagliato: ad esempio si cerca
di visualizzare come data un link, oppure come immagine un titolo.
o Se si rimuove una view collegata o una view figlia senza correggere poi la
view.
o Se si scrive codice php sbagliato
o Se si rimuove il primo campo Code in cui era stato scritto del codice in
automatico.
Concetti base
I CICLI:
Quando create una query questa estrarrà dei dati. Questi dati vengono visualizzati in una view
attraverso un ciclo. Esistono tre tipi di cicli e sono:
_default : in cui vengono visualizzati i dati della query principale
Parentdata: Sono i dati della query padre. Questo ciclo appare in automatico solo nella
visualizzazione delle view figlie in cui ha senso farlo apparire.
*_rows : sono tutti i dati delle query figlie.
LE TABS A DESTRA
A destra di ogni riga troviamo alcuni tabs. Se è selezionato NO quando viene creato il template
quella riga non viene modificata. Questo accade anche se avete modificato i parametri della riga
stessa.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
20
CODE vi mostra il codice riferito alla riga. Se selezionate code e salvate ad esclusione dei cicli le
righe si trasformano in righe CODE e perdono i form di per essere modificate in automatico.
FORM Sono le opzioni della riga. Le righe possono essere code, cicli, tag, field o special. Ad
esclusione dei Code gli altri tipi hanno una serie di form per modificare i dati in automatico.
Ricordatevi sempre che le modifiche hanno effetto solo se il pallino accanto al form modificato è
selezionato quando premete crea template.
ADD Il primo campo CODE e i cicli hanno poi un tab ADD che serve ad aggiungere nuove righe.
MANAGE Infine i campi TAG hanno un tab Manage che serve a definire quali righe fanno parte del
TAG stesso. I tag sono dei contenitori e possono essere usati per particolari impaginazioni.
CODE
All‟interno di un template è spesso necessario inserire alcune righe di codice personalizzato. Per
fare questo si può usare un campo code.
Comment: è possibile scrivere un piccolo promemoria definendo cosa fa il campo in
questione. In questo campo non è permesso inserire codice o tags di alcun tipo
Code: l‟editor in cui scrivere il proprio codice. Se state scrivendo molto codice e
l‟area risulta piccola, create il template (fate attenzione che il tab code sia spuntato
altrimenti i vostri sforzi non verranno salvati). Dopo aver creato il template l‟editor
del code di ridimensiona a seconda della quantità di codice scritto.
Add parent tag. Se il codice che state scrivendo produce un output html lasciando
spuntata questa opzione vengono aggiunti gli eventuali tag del gruppo di
appartenenza. Ad esempio se avete un ciclo che genera una tabella la porzione di
codice scritta verrà racchiusa tra i tag <td></td>
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
21
FORM
I form sono innumerevoli provo qui a farne una panoramica:
I Field sono i campi estratti dalla query e possono essere formattati in :
Date
Serve a visualizzare una data
o Date format – il formato della data
o XML aggiunge un parametro con cui personalizzare la data in fase di
creazione della voce del menu
o Label è un parametro opzionale che viene visualizzato solo a seconda del
gruppo di appartenenza e solo dopo aver rigenerato il gruppo di
appartenenza (quindi se volete usare il label dopo dovete selezionare il form
gruppo di appartenenza e ripremere crea template
Download
Crea un link per scaricare un file. I download devono essere accompagnati da un
campo che definisce i permessi di accesso.
o Class gli stili css base
o Count Selezionate il campo in cui memorizzare il numero di download fatti
dagli utenti (opzionale)
o Access Field: il campo in cui verificare i permessi per scaricare il file
(obbligatorio)
o Group Access: I gruppi di accesso per poter scaricare il file
o User Access: un campo in cui specificare quali utenti possono scaricare il file
o Text: il testo del download. Qui si possono usare alcuni parametri:
%file%
%fileName%
%extensionName%
%downloadCount%
Image
Serve per creare un‟immagine.
o Resize: la dimensione dell‟immagine. Le dimensioni possono essere
impostate in shellmanager/parametri
o Description: il campo descrizione associato all‟immagine
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
22
o Link: se l‟immagine deve essere linkata. I link possono essere o le view del
componente oppure un link speciale è popup image che permette di
visualizzare in un popup l‟immagine a tutto schermo.
o XML è collegato al resize dell‟immagine.
JParameter
Serve a visualizzare le informazioni dei campi formattati in questo speciale sistema.
o Show: Definisce se mostrare un solo parametro oppure tutti
o Type: Scegli come mostrare i dati
Link
Formatta il campo in modo da creare un link
o Formatted ne definisce i tag e gli stili
o Standard Link: Puoi scegliere o una view del componente oppure puoi
decidere di usare il campo come link stesso (simple link)
o Field To link: Qui viene scelto il campo da passare come id. L‟opzione
AutoDetect cerca di capire qual è il campo più appropriato, però non fateci
troppo affidamento.
Text
Stampa il campo selezionato
o Pretext e postText sono elementi html o php precedenti e successivi la
stampa del campo.
o Crop text : il numero di caratteri prima del crop. Il sistema cercherà
comunque di concludere la parola prima di tagliare il testo.
o Xml: passa al menu l‟opzione di visualizzare o nascondere il campo.
I cicli possono essere
Columns o Table
Columns
Il ciclo a colonne è quello standard e va bene per la maggior parte delle
visualizzazioni
o N. columns: Il numero di colonne in cui dividere il template. Essendo un
sistema tabless si basa sui css e l‟impaginazione potrebbe essere
influenzata dal template usato.
o Use Label: definisce se stampare i label inseriti nelle righe del ciclo
oppure ignorarli
o Add XML: permette di impostare il numero di colonne dal menu
o Label: E‟ la scritta che apparirà tra i parametri del menu.
Table
Visualizza i dati in una tabella
o Add Title: Definisce se usare i label come titoli delle tabelle. Se il sito ha
molte visite è consigliato scrivere i titoli della tabella a mano per
ottimizzare le prestazioni.
Le righe special sono utilizzate per creare porzioni di codice che non sono strettamente
legate alla visualizzazione di singoli campi e possono essere:
Form
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
23
Mostra il form creato per la view
o Automatic Fill: compila i campi del form con i risultati della query. Questa
opzione è utile per creare form di modifica dati
o Save form: decide se salvare oppure no il form (Diciamo che
generalmente conviene selezionarla)
o Send Email to Admin: Invia un‟email agli utenti abilitati a ricevere le email
di sistema (di solito il superamministratore). E‟ possibile richiamare i
campi compilati attraverso i nomi dei campi tra percentuali. Ad esempio
%titolo% stamperà il campo del form titolo.
Link
Crea un link non legato ad un campo. Questo è pressoché identico ai campi link
tranne che per l‟opzione text in cui inserire il testo del link da visualizzare
Load View
Questa opzione permette di caricare altre view all‟interno della view che si sta
visualizzando. Questo evita di dover riscrivere le view estratte da altri
componenti.
o Load View: Seleziona la view da caricare
o Params: Puoi definire due opzioni per filtrare i dati della view da caricare.
La prima opzione è id ed è come nei normali url, la seconda „option‟
definisce un secondo filtro della query questa volta statico. Ad esempio
nei commenti esiste una view apposita creata per essere caricata da
eventuali altri componenti (connect_generic_comment) e presenta nella
query due campi per filtrare i dati che sono genericcollid e genericoption.
Il primo serve a collegare i commenti all‟articolo a cui si stanno
visualizzando mentre la seconda opzione filtra i risultati per il
componente a cui si collegano. Quindi se si vogliono aggiungere i
commenti ad un proprio componente su id si può scegliere come campo
di collegamento id, mentre su option si può scrivere il nome del
componente a cui si stanno collegando.
Pagination
Aggiunge la paginazione
Search
Aggiunge la ricerca.
o Load View: è possibile aggiungere un qualsiasi modulo di ricerca dello
stesso componente. Ovviamente la pagina dei risultati sarà la view
scelta.
Separator
E‟ un semplice div che annulla eventuali float e serve unicamente per
impaginare i dati
I Tags per ultimo sono gruppi che modificano l’impaginazione della view. Questi possono
essere
Div
Racchiudono le righe che fanno parte di questo gruppo tra due div
o Align defisce l‟allineamento del div.
o Width: La larghezza del div (può essere sia in percentuale che in pixel
o Border: Disegna un bordo intorno al div
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
24
o Internal tag: Decidi se i dati del gruppo dovranno avere dei tag che li
racchiudono oppure no.
Table
Crea una tabella
Null
Non crea nessun tag, tuttavia può essere comodo per raggruppare i dati.
ADD
Ricordati che quando crei una nuova riga eventuali altre modifiche apportate prima di creare il
template andranno perse.
E‟ possibile creare campi CODE, GROUP (tag), SPECIAL oppure una riga per ogni campo
estratto.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
25
Modificare i componenti istallati Per acquistare un po‟ di dimestichezza con il sistema Shellmanager di seguito viene mostrato
come è possibile adattare alle proprie esigenze i componenti istallati nel pacchetto base.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
26
Shell_Profiler
Shell_profiler sostituisce il sistema di registrazione di Joomla aggiungendo la possibilità di
rimuovere gli utenti e di modificare i campi del profilo. Il profilo utenti permette oltretutto di gestire
gli inserimenti fatti dall‟utente tramite un sistema a tab semplice e veloce.
Per attivare il nuovo sistema di registrazione basterà andare su moduli, cancellare la pubblicazione
del login di Joomla, e pubblicare mod_shelllogin
assegnandogli una posizione (va bene la stessa del
login di joomla). Fate attenzione a verificare che il
nuovo modulo sia pubblicato nelle pagine in cui
volete farlo apparire, perché appena installato
questo viene segnato come pubblicato in nessuna
pagina.
Il nuovo modulo si presenta pressocché uguale al
login classico di Joomla, infatti è soltanto un
modifica di quest‟ultimo. Per password o nome
utente dimenticati richiama il sistema classico di
Joomla, mentre per la registrazione richiama il
nuovo componente shell_profiler.
La registrazione è molto essenziale tuttavia aggiunge un primo importante elemento: il captha.
Il secondo elemento fondamentale che introduce la nuova registrazione è la possibilità di
modificare i campi da inserire. Un elemento classico che probabilmente vorrete aggiungere sono i
termini e condizioni di utilizzo. Andiamo in amministrazione / shellmanager e clicchiamo sul
bottone view del componente shell_profiler. Ci troviamo di fronte ad un nuovo elenco, andiamo sul
bottone form di shell_register_user e premiamo in alto a sinistra Nuovo.
Label : Disclaimer
Collega al database: no
Crea un: Textarea
Nome del campo: disclaimer (ma un nome vale l‟altro)
valore predefinito: Il nostro disclaimer
Solo lettura: sì
Dimensione del campo:piccola
Salva e chiudi.
Ora aggiungiamo il checkbox clicchiamo su nuovo e settiamo i seguenti parametri:
Label: Accetta
Collega al database: no
Crea un: checkbox
Nome del campo: accetta (ma un nome vale l‟altro)
valore predefinito: 0
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
27
Campo obbligatorio: sì
Parametri checkbox/valore: 1
Salva e chiudi.
Per ultimo riordiniamo i campi in modo da avere il bottone salva in fondo ed ecco il risultato finale:
Se invece vogliamo gestire le schede dell‟utente possiamo sempre dalle view camb iare,
aggiungere o rimuovere gli elementi da visualizzare. Ad esempio se non volessimo dare la
possibilità ad un utente di inserire una descrizione sulla view profile scorriamo nell‟elenco e
disabilitiamo la riga #__CONTACT_DETAILS.MISC (text) premendo il primo check verde che si
trova a sinistra dell‟intestazione.
Così facendo non verrà più visualizzata nel profilo la descrizione inserita dall‟utente. Ora per
evitare anche che l‟utente possa inserire comunque una descrizione torniamo all‟elenco delle view
ed andiamo a modificare il form di shell_profiler_edit rimuovendo la riga misc (tipo:frontend editor).
In questo modo eliminiamo il campo anche nel form di modifica del profilo dell‟utente.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
28
ShellGallery
Le gallery possono essere inserite dagli utenti o
dagli amministratori tramite i form di inserimento
presenti in amministrazione. Per prima cosa
bisogna inserire una o più categorie a cui le gallerie
inserite potranno appartenere. Nell‟esempio che
seguirà creeremo tre categorie una per ogni azione
possibile:
Galleria collegata ad un articolo conterrà le immagini appunto collegate ad uno specifico articolo
Album personale che conterrà le gallery degli utenti
Album inserito dall’amministratore sarà invece riservata alle gallerie fotografiche inserite in
amministrazione.
Iniziamo dalle gallerie collegate ad un articolo. Andiamo sugli articoli di Joomla, e scegliamo
l‟articolo a cui aggiungere una gallery. In alto a destra troveremo il bottone ShellGallery,
premiamolo e creiamo una nuova gallery. Fate attenzione al menu perché i primi due bottoni non
sono legati al form di inserimento della gallery ma si riveriscono al collegamento con l‟articolo
Quindi torna indietro permetterà di
tornare all‟articolo di Joomla,
mentre salva si riverisce
unicamente all‟elenco articoli e
non al salvataggio del form (nelle
prossime versioni correggerò
questo bottone adesso poco
chiaro).
Dopo aver creato la nostra gallery
salvandola con il bottone Salva e
Chiudi, nell‟elenco delle gallery
create selezioniamola e premiamo
salva. A sinistra il risultato finale.
Passiamo agli album personali. Se ci logghiamo dal lato pubblico del sito (frontend) possiamo
accedere al nostro profilo dove, all‟interno della tab gallery possiamo trovare il „tasto mostra tutte le
gallery‟. All‟interno di questo elenco troviamo il bottone crea una nuova gallery, mentre se
decidiamo di visualizzare un singolo album fotografico troveremo tutti i bottoni per modificare le
singole immagini. Se andiamo su crea una nuova galleria fotografica troviamo però che l‟utente
può scegliere tra tutte le categorie create all‟interno di shellgallery. Poniamo di voler inserire tutte
le gallery degli utenti all‟interno dell‟unica categoria “album personali”.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
29
Andiamo in amministrazione Shellmanager e clicchiamo sulle view di shellgallery. Qui dovremo
modificare i form di inserimento e di modifica delle gallery che sono rispettivamente
add_shell_gallery e edit_shell_gellery. In questo esempio modifichiamo uno dei due form, l‟altro lo
si fa uguale. Clicchiamo sul form di add_shell_gallery e successivamente scegliamo catid (tipo
mycategory). Noi vogliamo che tutti gli album inseriti dagli utenti siano salvati con la stessa
categoria, quindi la categoria deve diventare una costante non modificabile dagli utenti. Scegliamo
il campo hidden che permette di passare al form un valore determinato senza che questo venga
visualizzato dall‟utente. Inseriamo come valore predefinito d‟id della categoria a cui vogliamo far
collegare gli album fotografici degli utenti ed infine premiamo salva. Sul lato utente adesso
premendo il bottone crea una nuova gallery vedremo che non appare più il menu a tendina in cui
scegliere la categoria.
Per finire il nostro esempio passiamo a creare una pagina in cui visualizzare soltanto le gallery
inserite in amministrazione, quindi tutte le gallery che hanno come categoria Album inserito
dall’amministratore. Torniamo in amministrazione, Shellmanager e visualizziamo nuovamente le
view delle gallery. La view che si occupa della visualizzazione degli elenchi è gallery_list,
clicchiamo sul titolo e in fondo, all‟interno di opzioni & seo impostiamo url menu su category.
Premiamo salva e chiudi ed andiamo sul template di gallery_list. Qui dobbiamo soltanto premere
crea XML in modo da rigenerare l‟xml dei parametri collegati alla voce di menu. Tramite queste
operazioni abbiamo generato la possibilità di passare nell‟url della voce di menu un id contenente
la categoria. Quindi quando creeremo la voce di menu associata a gallery_list ci verrà richiesto
quale categoria scegliere e questo valore verrà passato di default nell‟url. Questo non vuol dire che
i dati verranno automaticamente filtrati, in realtà il filtro vero e proprio lo inseriamo noi quando
creiamo la query che estrae i dati. Gallery_list è già predisposta per questa opzione tuttavia se
doveste creare un nuovo componente è importante ricordarsi di generare la query appropriata.
Per finire l‟esempio creiamo una nuova voce di menu, come tipo selezioniamo gallery_list,
scegliamo il titolo e a destra selezioniamo la categoria “album inserito dall‟amministratore”. Se
adesso andiamo a vedere il risultato finale ci accorgeremo che le gallery sono filtrate per la
categoria scelta. Tuttavia nel template è previsto un link che riporta a mostrare tutte le gallery,
quindi se volgiamo eliminare questa opzione, dobbiamo ancora fare un ultimo sforzo modificando il
template della view di gallery_list . Visualizziamo il codice della prima riga (CODE (title filter
category)) e cancelliamo le ultime nove righe. Premiamo il bottone „crea template‟ facendo
attenzione che il tab code sia selezionato come mostra la figura sottostante.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
30
FileManager
In questo esempio mostreremo come creare un catalogo di libri da
scaricare in pdf. La prima cosa da fare sarà creare la struttura
delle categorie. Andiamo su Filemanager/categories e creiamo
una struttura sul tipo di quella illustrata nella figura. Sulle categorie
possiamo anche aggiungere delle immagini e descrizioni per
rendere più completo il nostro catalogo. Poi torniamo su
Filemanager e popoliamo le nostre categorie inserendo alcuni pdf.
Preparati i dati, creiamo una nuova voce di menu, tipo di voce:
download_manager. Inseriamo il titolo e salviamo. Se andiamo
adesso sul lato utente vediamo che è apparsa la nostra nuova
voce di menu che linka ad una pagina tipo questa:
Nel lato utente viene visualizzata la
categoria corrente in alto, le
sottocategorie subito dopo e solo
alla fine i vari file da scaricare. Se
nelle sottocategorie sono presenti
altri livelli annidati di categorie
queste vengono mostrate sotto il
titolo, così come vengono
conteggiati i file presenti in una
sottocategoria mostrando il totale
dei file caricati.
Ora vediamo di modificare il nostro componente. Iniziamo aggiungendo l‟autore che mi sembra
essenziale per un catalogo di libri. Vediamo di fare una cosa ben fatta e creiamo un nuovo
componente con l‟elenco degli autori. Andiamo su ShellManager / nuovo e scriviamo
Titolo: autori_libri
Scegli la tabella: nuova/autore_libri
icona shellprofiler (che mi sembra la più appropriata)
E poi premiamo salva e chiudi e di nuovo salva e chiudi quando ci si presenta la seconda
schermata. Ecco creato il nostro nuovo componente! Ora andiamo su Database ed inseriamo i
seguenti campi
nome: testo piccolo
vita:testo grande
Torniamo indietro su ShellManager andiamo su list e clicchiamo su nome. Selezioniamo in fondo a
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
31
destra attiva link sì e salviamo. Torniamo di nuovo su ShellManager > Form (nella riga di autore)
clicchiamo su vita e scegliamo crea un … editor. Di nuovo salva.
Adesso colleghiamo sempre per l‟amministrazione i file da scaricare agli autori. Sempre da
ShellManager andiamo sulla riga di e premiamo nuovo.
Label: Autore
collegamento al database: crea una nuova voce
Crea un: listselectquery
nome del campo: autore
e sui parametri list select by query selezioniamo
tabella:autore_libri
e su crea la query selezioniamo custom query e scriviamo su query:
SELECT id, nome AS titolo FROM #__autore_libri ORDER BY nome ASC
Adesso se andiamo su file manager ed aggiungiamo una nuova scheda ci troveremo un nuovo
campo in cui aggiungere l‟autore.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
32
Infine dobbiamo riorganizzare la gestione lato utente. Andiamo su shellmanager e clicchiamo sul
bottone view di file manager. Abbiamo tre pagine in cui si vedono le schede dei singoli file da
scaricare: download_manager, filemanager_result_filter e single_filemanager. Vediamo come
modificare single_filemanager: clicchiamo prima sul titolo per modificare la query di estrazione dei
dati. Poiché abbiamo inserito un campo che si collega ad un‟altra tabella se stampassimo il campo
stesso visualizzeremmo l‟id dell‟autore per cui per prima cosa dobbiamo aggiungere alla query un
LEFT JOIN che ci estragga in nome dell‟autore. Andiamo su di un campo filterStr ancora libero
clicchiamo su genera e compiliamo il campo con i seguenti parametri:
Scegli la funzione: Left Join
Campo di destinazione: #__autore_libri / id
campo di origine: autore
Nome da aggiungere: #__autore_libri / nome
Nuovo nome del campo: scrittore
Premiamo genera query e poi salva. Quando si scrive una nuova query per le view o si modifica
una query esistente conviene sempre prima premere il bottone salva e poi salva e chiudi. Questo
perché il primo campo a destra (di sola lettura ) mostra il riepilogo della query che andremo ad
eseguire e nel caso anche gli eventuali errori quindi premendo prima salva vediamo il riepilogo
della query e se tutto va bene possiamo premere salva e chiudi per tornare all‟elenco delle view.
Ora andiamo sul template di Single_filemanager e aggiungiamo il campo da visualizzare.
Andiamo su ciclo_default > ADD e come tipo scegliamo scrittore. Premiamo crea template. Adesso
se andiamo sul lato utente e visualizziamo un singolo libro da scaricare prima del bottone torna
indietro dovrebbe essere apparso il nome dello scrittore, tuttavia noi vogliamo impaginarlo
sull‟elenco a destra perché ci sembra più gradevole. Andiamo su Tag tag_0 (div) e clicchiamo su
manage.
Spuntiamo scrittore e creiamo il template. Il Manage dei tag serve a definire quali elementi si
trovano all‟interno di questi tag. Dopo aver creato il template ci accorgeremo infatti che la riga
#__SHELLFILEMANAGER.SCRITTORE è stata inserita all‟interno del gruppo. Andiamo sul form
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
33
della nuova riga e come label inseriamo scrittore. Rigeneriamo il template, riordiniamo i campi se
ce n‟è bisogno ed ecco il risultato finale:
Ovviamente dobbiamo ripetere il passaggio per tutti gli altri template. filemanager_result_filter è
identico per cui non c‟è bisogno di spiegazioni, mentre download_manager si differenzia
leggermente in quanto l‟elenco dei file da scaricare non è il ciclo default, ma CICLO
CATEGORY_FILES_ROWS, quindi la query da modificare non si trova dentro
download_manager, ma bisogna andare su category_child.
Aggiungere un campo di ricerca
Continuando l‟esempio precedente vediamo come aggiungere un campo di ricerca a tendina con
l‟elenco degli scrittori. Il sistema di ricerca di Filemanager usa un piccolo trucco per aggiungere il
campo di ricerca agli elenchi delle categorie, per cui forse non sarebbe il componente più indicato
per mostrare il funzionamento dei campi di ricerca, tuttavia adesso focalizziamo la nostra
attenzione sulla parte più semplice, ovvero l‟aggiunta del campo di ricerca. Sull‟elenco delle view di
file manager clicchiamo sul bottone ricerca del template category_files e premiamo su nuovo.
Label: scrittore
Tipo di ricerca: Ricerca a tendina
Tabella: autore_libri
Titolo: nome
Valore:id
Salva e chiudi
Abbiamo già finito, se andiamo sul nostro sito sarà apparso un elenco a tendina con la ricerca per
scrittore… semplice, no?
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
34
Note minime per i programmatori
Lato amministrazione: I componenti creati mantengono una struttura molto simile a quelli standard di Joomla (fatta eccezione per i model). Nella cartella controller è possibile riscrivere i vari passaggi nella visualizzazione e modifica dei dati.
Per prima cosa creiamo un file con il nome del componente o di un suo controller figlio
appuntamenti.php
class ShellManagerControllerAppuntamenti extends VC_Controller { //
protected function display($arg = null) { parent::display($arg); } // protected function edit($arg = null) { parent::edit($arg); } // protected function save($arg = null) { parent::save($arg); } // protected function apply($arg = null) { parent::apply($arg); } // protected function saveData() { parent::saveData(); } }
Poniamo ora di voler modificare il salvataggio dei dati. Sostituiamo la funzione saveData con la seguente: protected function saveData() { $post = JRequest::get( 'post' ); $this->model->setData($post); $this->model->execute("saveData"); if ($this->model->getParam("isError")) { $app =& JFactory::getApplication('administrator'); $app->enqueueMessage('Si è verificato un errore Nel salvataggio dei dati: '.$this->model->getParam("error"), 'error'); } } }
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
35
Ora abbiamo a disposizione i dati prima di essere salvata ($post). Possiamo quindi fare tutti i controlli e modifiche che desideriamo prima di salvare i dati stessi. Lo stesso discorso lo si può fare per l‟edit. protected function edit($arg = null) { JRequest::setVar("task", "edit"); if ($this->editSetDefault()) { $this->editLoadData(); /*
i dati adesso possono essere reperiti e modificati attraverso $this->model->data['rows'] */
$this->editSetTemplate(); } } Form lato utente: la maggior parte delle modifiche avverranno ovviamente nel template. Per i form lato utente è possibile interagire prima del salvataggio attraverso la funzione
function saveDataNomeView($post) { return $post } Dove NomeView è appunto il nome della view. Se return = null allora il form non viene più salvato. In questo modo si può ad esempio creare un form per l‟invio di email senza dover salvare nulla, oppure fare controlli specifici prima di decidere se salvare o no i dati inviati.
La seconda funzione richiamata dai form è invece dopo il salvataggio
function AfterSaveNomeView($bool) { }
Dove $bool è true se i dati sono stati salvati oppure è false in caso contrario.
Da ultimo è da notare che i form lato utente non vengono compilati in automatico come quelli lato amministrazione. Questo vuol dire che se stiamo modificando uno specifico articolo per impostazione predefinita i campi del form non visualizzeranno i dati dell‟articolo se non espressamente richiesto. Quindi diamo un rapido sguardo su come si scrivono i form lato utente.
La prima grossa differenza sta nel fatto che i form lato utente bisogna se si desidera inviare i dati inserire alla fine un bottone submit.
La seconda differenza sussiste nei parametri delle fieldset in cui è possibile decidere se alcuni campi contenuti devono essere visualizzati prima o dopo l‟invio dei dati.
Il terzo è la gestione di campi speciali come hidden che non vengono stampati lato utente ma memorizzati in sessione per evitare falle sulla sicurezza. Anche i controlli sui campi sono più severi rispetto al lato amministrazione e seguono le specifiche riportate da Joomla! 1.6 sulla creazione dei form.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
36
Per ultimo e forse più importante di tutti è la gestione dei valori predefiniti in parametri base.
Se desideriamo visualizzare i dati dell‟articolo principale collegato al form dobbiamo richiamarlo tramite la variabile
%parentArticle.nomeCampo%
Se il form è connesso ad un articolo di Joomla! si possono reperire id, titolo, categoria e autore (Createdby) tramite
% joomlaArticle.nomeCampo%
I dati legati all‟estrazione diretta della view quindi quelli del form vero e proprio sono invece estratti usando la variabile
%article.nomeCampo%
Per estrarre i dati dell‟utente che sta scrivendo il form è possibile usare la variabile
%user.nomeCampo%
Per finire se si desidera ricavare variabili get o post è possibile farlo come di consueto scrivendo semplicemente
%nomeCampo%
Anche se non completa, spero che questa guida introduttiva vi potrà essere utile per usare
Shellmanager nei vostri progretti.
Se decidete di usare questo componente o compomenti generati da ShellManager ovviamente non
mi assumo nessuna responsabilità per eventuali difetti, malfunzionamenti, perdite di dati o
vulnerabilità legate al codice scritto.
Il componente è rilasciato in versione opensource per cui chi desidera partecipare al progetto è il
benvenuto.
Attualmente la maggiore necessità è quella di una traduzione in inglese e la produzione di
componenti legati a shellmanager.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
37
Un sistema di appuntamenti (v0.7)
Attenzione!!!
Questo tutorial è stato scritto per la versione 0,7 di ShellManager. Anche se alcuni
elementi sono cambiati i concetti base sono rimasti gli stessi per cui ho pensato che era
uno spreco non inserirlo nella guida.
Come primo componente creeremo un sistema per visualizzare degli appuntamenti (o eventi). Questo sarà molto semplice, ma presenterà tutto il necessario per iniziare a comprendere il funzionamento del sistema.
Andiamo su component->shellmanager e clicchiamo su NEW
Titolo: Appuntamenti
Icona : Clock
Tabella: Appuntamenti
Appena salvate non vorrete rimandati sull‟elenco dei componenti creati bensì all‟interno di un altro
form che serve per gestire alcuni parametri più avanzati. Per ora non tocchiamo nulla e premiamo
nuovamente su salva.
Il vostro componente è stato già creato, potete verificarlo andando sul menù components dove
sarà apparso il link ad appuntamenti così come sul lato utente è stato già creato una nuova voce di
menù per vedere come i dati verranno visualizzati lato utente.
Certo, ancora questo componente non fa nulla! Per prima cosa dovremo decidere la struttura del
database. Cosa vogliamo che abbia il nostro componente? Sicuramente un titolo, un testo, la
possibilità di catalogare gli articoli tramite categorie, il necessario per gestire la pubblicazione e poi
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
38
la data di inizio dell‟evento e la data di fine (in questo modo iniziamo a differenziarlo dagli articoli di
Joomla!).
3.1 Database
Creiamo una struttura del database identica a quella riportata nella figura sottostante, poi premi il
tasto Torna Indietro per tornare alla schermata iniziale.
Quando arrivate a creare il campo categoria questo come tipo di dati segna int(10) tuttavia dovrete
scegliere come tipo categoria!
Adesso che abbiamo costruito la nostra tabella iniziamo a vedere come gestirne i dati.
3.2 List
Ora creiamo l‟elenco di come verranno rappresentati i dati all‟interno del nostro nuovo
componente. Ricordatevi che stiamo ancora lavorando sul lato amministrazione quindi si tratta di
come vengono visualizzati i dati nel back end. Dentro list troverete un elenco molto simile a quello
che avete appena creato nel database, tuttavia ricordatevi che se aggiungete o rimuovete voci da
questo elenco questo non cambierà la struttura della tabella, ma solo le colonne che servono per
gestire i dati di appuntamenti. Altra nota prima di iniziare le modifiche: Non dovete mai creare due
colonne che puntano allo stesso campo.
Ora passiamo a vedere più nel dettaglio gli elenchi. Andate su titolo e premete modifica (oppure
cliccate sulla scritta titolo).
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
39
il Titolo è una colonna collegata al campo della tabella Titolo ed è formattato come campo di testo.
Quello che vogliamo aggiungere è che se clicco sul titolo mi si apra il form per modificare
l‟appuntamento. In fondo a destra trovate il fieldset parametri testo. Spuntate su Sì. Bene anche
qui abbiamo finito. Ora sul vostro nuovo componente il titolo degli elenchi è cliccabile. Ma qual è il
link che avete appena creato? In questo caso il link è generato in automatico ma se vogliamo
possiamo cambiarne i parametri a nostro piacere. Vediamo come:
option=%option%&view=%view%&task=edit&cid[0]=%id
All‟interno di ShellManager è possibile aggiungere delle variabili speciali comprese tra %. Queste
vengono poi sostituite o con i campi dei dati che si stanno estraendo oppure dalle variabili $_GET
e $POST (che in Joomla! sono estratte tramite JRegister::getVar($var)). Quindi %option% sarà il
nome del componente (com_appuntamenti), %view% la view corrente, task in questo caso è
sempre è „edit‟ e cid[0] sarà uguale all‟id dell‟appuntamento che si desidera modificare.
Uno degli elementi che dobbiamo invece aggiungere è una colonna che mostri se un articolo è
pubblicato o meno. Prima di tutto eliminiamo la riga associata al campo pubblicato (perché può
esistere solo una riga per ogni campo) e creiamone una nuova. Il campo pubblicato mostrerà la
tipica icona che definisce se un articolo è pubblicato, espirato o non pubblicato (come per gli
articoli classici di Joomla!).
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
40
Rimangono poi le date che potete fare da soli basta modificare i campi scegliendo come tipo
(Definisci come il campo deve essere formattato) data.
Per finire diamo un occhiata alle
categorie. La colonna categorie è
associata alla tabella nome_categoria,
voce che troviamo nell‟elenco dei
campi della tabella da collegare, ma è
un campo che noi non abbiamo mai
creato! Vediamo cosa è successo:
Quando abbiamo inserito nel database
la colonna categoria con tipo „categoria‟
ShellManager ha automaticamente
scritto una clausola della query nell‟estrazione dei dati di appuntamenti. Se torniamo sui parametri
di appuntamenti (dalla pagina principale di ShellManager cliccate su appuntamenti) vediamo che è
stata aggiunta una riga all‟interno delle clausole della query
Se premiamo su genera possiamo vederne i dettagli:
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
41
Qui bisogna avere almeno qualche nozione su come si generano le query. Una volta che avete
imparato i rudimenti (ma spero che già li sappiate) vediamo che quando abbiamo creato il nostro
campo categoria è stato aggiunta un istruzione LEFT JOIN il cui nome assegnato è
nome_categoria. Potete aggiungere altri left join o where per rendere la vostra query più
complessa aggiungendo fino a 5 modifiche.
Quando avrete finito di modificare la vosta List penso sia ora di iniziare a vedere il risultato di
quello che state realizzando. Andate sul menù components e cliccate su appuntamenti.
3.3 Il form
Con lo stesso criterio con cui si è creato l‟elenco tramite list si possono creare i form. L‟unica
differenza sta nel fatto che il modulo di inserimento è un po‟ più complesso. In generale i form sono
strutture di dati annidate. Tutti i campi devono sempre essere all‟interno di un fieldset ovvero un
box html che ne delimita le dimensioni. I fieldset si dividono in due tipi: Quelli che racchiudono
semplicemente i dati e quelli che accolgono i parametri. Questo secondo tipo si distingue dal primo
per avere un livello intermedio nell‟elenco in cui è definito il campo in cui raccogliere i parametri.
Comunque questa parte è più complicata e al momento non ci serve. Provate a costruire voi il form
senza ulteriori spiegazioni… la soluzione è alla pagina successiva.
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
42
3.4 Visualizziamo i dati
Finito di costruire il lato amministrativo del
nostro componente passiamo ora ad
esaminare le view. Il nostro componente
avrà una struttura molto semplice e
comprenderà la visualizzazione degli elenchi
o di un appuntamento singolo. Entriamo nei
parametri della view appuntamenti (i titoli
delle view devono sempre essere tutti
minuscoli, senza spazi o nomi ripetuti e
soprattutto senza caratteri strani). Come
tabella sceglieremo jos_appuntamenti il
campo della tabella accanto è invece la
chiave primaria che serve ad identificare
univocamente l‟articolo che stiamo
estraendo. Se si desidera avere delle url-
rewrite più leggibili si può scegliere di
estrarre i dati invece che per id per alias
purché si sia sicuri che gli alias siano campi
univoci non ripetuti, ma forse adesso sto
correndo un po‟ troppo. Filterstr1…5 serve
per aggiungere proprietà alle query. Come
per il lato amministrazione aggiungiamo un
left join per poter visualizzare i nomi delle
categorie:
www.dazo.it Shellmanager v0.9.6 2 agosto 2011
43
Scegli la finzione LEFT JOIN
Campo di destinazione jos_categories / id
Campo d’origine categoria
Campo da aggiungere jos_categories / title
Nuovo nome del campo nome_categoria
Poi aggiungiamo un altro filtro per mostrare soltanto i campi pubblicati
Scegli la finzione PUBLISH
Campo pubblicazione pubblicato
Campo d’origine categoria
Data inizio data_inizio_pubblicazione
Data fine data_fine_pubblicazione
La creazione delle view a partire dalla versione 0.95 è stato completamente riscritto per cui la parte
che seguiva da qui del tutorial non aveva più senso ripubblicarla in questa guida, ma a questo
punto penso che, se avete avuto la pazienza di arrivare fin qui, potete provare come esercizio a
generare le view da soli.
2 agosto 2011
Giulio Pandolfelli