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

http://www.dazo.it/


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.


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


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


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”).


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.


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


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:


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).


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.


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


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); ?>


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.


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)


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


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.


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


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:


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.


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>


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


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


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


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.


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.


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


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.


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”.


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.


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


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.


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


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?


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'); } } }


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.


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.


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


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).


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!).


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:


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.


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:


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

shellmanager096

Technology