OGGETTO CALENDARIO

Last updated on

Descrizione

consente di visualizzare un calendario modificabile dall’utente.

Questo oggetto è utilizzabile solo sulla piattaforma web.

Proprietà Specifiche

Oltre alle proprietà comuni sono disponibili le seguenti proprietà:

  • MostraSempreScalaTempi: se True viene sempre visualizzata la scala dei tempi, anche nelle visualizzazioni settimanali in orizzontale
  • SlotScalaTempi: dimensione della scala dei tempi in minuti. Valori validi sono 5, 10, 15, 30, 60. Se si specificano altri valori, viene utilizzato il valore fra quelli validi ad esso più vicino. (default=30).
  • NuovoLayout: se True viene utilizzato il layout aggiornato disponibile dalla versione 2021.07+11. Il default è True per gli oggetti creati con questa versione o successiva.
  • Timeline: se True il calendario è visualizzato con le ore sull’asse orizzontale anziché verticale
  • VistaDefault:  definisce il tipo di visualizzazione che verrà mostrata all’utente all’apertura del form.
  • Viste:  definisce i tipi di visualizzazioni abilitati, fra i quali l’utente potrà scegliere. Le possibili visualizzazioni sono: Day (giorno), Week (settimana), Month (mese), Workweek (settimana lavorativa), Agenda, Year (anno).

 

Eventi specifici

Sono disponibili i seguenti eventi:

  • EventoCambiaElemento: viene attivato quando l’utente sposta o ridimensiona un elemento. Nella variabile “Item” è contenuto l’elemento modificato. Se NewLayout=True, sono  disponibili l’array “Items” che contiene gli elementi modificati, che possono essere più di uno se si sono trascinati più elementi (in questo caso, la variabile “Item” contiene il primo elemento dell’array) e l’array “OldItems” che contiene le versioni degli elementi dell’array “Items” prima della modifica.
  • EventoClickElemento: viene attivato quando l’utente clicca su un elemento, selezionandolo. Nella variabile “Item” è contenuto l’elemento selezionato.
  • EventoEliminaElemento: viene attivato quando l’utente elimina un elemento, selezionandolo. Nella variabile “Item” è contenuto l’elemento eliminato.
  • EventoSelezionaCella: viene attivato quando l’utente seleziona una o più celle libere. Nelle variabili “StartDate” e “EndDate” sono contenuti data ed eventualmente ora dell’intervallo di celle selezionate. A partire dalla release 2021.07+8, nella variabile “Resource” è contenuto l’eventuale nome della risorsa del cui calendario è stata selezionata la cella.

Nota importante
Per motivi di performance legati alla struttura dell’oggetto, eventuali aggiornamenti di altri oggetti del form effettuati all’interno dei gestori di questi eventi (ad esempio l’assegnazione di un testo ad un’etichetta, oppure l’assegnazione di un valore ad un campo), non comporteranno l’aggiornamento grafico del form .
Per aggiornare anche visivamente questi oggetti è necessario inserirli in un Oggetto contenitore con la proprietà ContenitoreAggiornamento assegnata a true, e, nel gestore dell’evento, richiamare il metodo UpdateContainer dell’Oggetto form, specificando come parametro lo stesso contenitore.

Si raccomanda di specificare i corretti ancoraggi per l’oggetto e di utilizzare la proprietà Adatta allo spazio del form per consentire di visualizzare correttamente il calendario.

Consultare la pagina Eventi per maggiori informazioni sull’argomento.

 

Proprietà utilizzabili da codice lato Server (VB.NET/C#)

  • Enabled: se assegnato a False gli elementi contenuti nel calendario non sono modificabili dall’utente.
  • MinDate: data minima da visualizzare nel calendario.
  • MaxDate: data massima da visualizzare nel calendario.
  • StartHour: ora di inizio del periodo giornaliero da visualizzare sul calendario, in formato numerico che va da 0 a 24
  • EndHour: ora di fine del periodo giornaliero da visualizzare sul calendario, in formato numerico che va da 0 a 24
  • StartWorkHour: ora di inizio lavoro, in formato numerico che va da 0 a 24
  • EndWorkHour: ora di fine lavoro, in formato numerico che va da 0 a 24
  • TimelineCellWidth: larghezza in pixel della cella nella visualizzazione orizzontale (default: 15 pixel)
  • TimeScaleSlot: dimensione della scala dei tempi in minuti. Valori validi sono 5, 10, 15, 30, 60. Se si specificano altri valori, viene utilizzato il valore fra quelli validi ad esso più vicino.
  • VerticalRowHeight: altezza in pixel della riga nella visualizzazione verticale (default: 36 pixel; valore minimo: 19 pixel)
  • Visible: se True l’oggetto è visibile nel form, in caso contrario lo si assegna con False.
  • WeeksToShow: numero di settimane da mostrare nella vista settimanale (default: 1)

 

Metodi utilizzabili da codice lato Server (VB.NET/C#)

  • AddCategory(<Name>,<Color>,<FontColor>”): consente di aggiungere una categoria di elementi, specificandone il nome (parametro <Name>), il colore di sfondo (<Color>, nel formato utilizzato negli stili CSS) e il colore del font (<FontColor>). Le categorie verranno assegnate agli elementi e ne specificheranno il colore
  • ClearCategories(): cancella tutte le categorie inserite.
  • AddResource(<Name>): consente di aggiungere una risorsa. L’utilizzo di questo metodo non è indispensabile in quanto le risorse vengono aggiunte automaticamente quando vengono specificate nei metodi “AddItem” e “ModifyItem”.
  • ClearResources(): cancella tutte le risorse inserite.
  • AddItem(<ID>,<Subject>,<StartDate>,<EndDate>,<AllDay>,<Description>,<Category>,<Editable>,<Resource>): consente di inserire un elemento da visualizzare nel calendario, specificandone tutte le proprietà. <ID> è un numero intero maggiore di zero che identifica in modo univoco ciascun elemento. <Subject>è il titolo dell’elemento. <StartDate> and <EndDate> sono valori di tipo DateTime che specificano l’inizio e la fine dell’elemento. <AllDay>(opzionale) è un valore booleano che se assegnato a True definisce che l’elemento occupa tutta la giornata. <Description> (opzionale) è una descrizione estesa dell’elemento. <Category> (opzionale) definisce la categoria di appartenenza dell’elemento, che a sua volta ne definisce il colore. <Editable> (opzionale) è un valore booleano che, se posto a False, rende l’elemento non modificabile. <Resource> consente di specificare, opzionalmente, il nome di una risorsa cui è attribuito l’elemento. Nel caso in cui si specificassero le risorse, il calendario verrà suddiviso sulle risorse stesse.
  • ClearItems(): cancella tutti gli elementi definiti.
  • ModifyItem(<ID>,<Subject>,<StartDate>,<EndDate>,<AllDay>,<Description>,<Category>,<Editable>,<Resource>): consente di modificare un elemento esistente, identificato attraverso l’ID univoco, riassegnandone le proprietà.
  • ModifyItem(<Item>): consente di modificare un elemento esistente, sostituendolo con quello passato nel parametro Item, identificato dalla proprietà ID dello stesso.
  • DeleteItem(<ID>): consente di eliminare un elemento esistente, identificato attraverso l’ID univoco.
  • AddWorkHours(<Date>,<StartHour>,<EndHour>,<Resource>): consente di specificare nel dettaglio le ore lavorative per ciascuna data e, opzionalmente, per ciascuna risorsa. I parametri <StartHour> ed <EndHour> devono essere specificati nel formato “HHMM”. Se il calendario non prevede risorse, il parametro <Resource> si può omettere. Diversamente, è necessario specificare le ore lavorative per ogni risorsa.
  • ClearWorkHours(): cancella tutte le ore lavorative definite.
  • FilterResources(<fromResourceName>,<toResourceName>): filtra le risorse in base al nome. Vengono filtrate le risorse il cui nome è compreso fra i due inseriti. Per rimuovere il filtro, specificare Nothing in entrambi i parametri. Disponibile solo se NuovoLayout=true.
  • FilterResources(<filterPattern>): filtra le risorse in base al nome. Il filtro avviene in base al valore inserito, ed è possibile utilizzare il carattere “%” come wildcard. Per rimuovere il filtro, inserire Nothing nel parametro. Disponibile solo se NuovoLayout=true.
  • FilterResources(<resourcesToFilter>): filtra le risorse il cui nome è contenuto nell’oggetto DBArray passato nel parametro <resourcesToFilter>. Per rimuovere il filtro, inserire Nothing nel parametro. Disponibile solo se NuovoLayout=true.
  • GetAllItems(): Restituisce un array contenente tutti gli elementi del calendario
  • GetItems(<ID>,<Subject>,<StartDate>,<EndDate>,<Description>,<Category>,<Resource>): Restituisce un array contenente tutti gli elementi del calendario i cui valori delle proprietà corrispondono ai valori passati nei parametri che non sono Nothing. Fanno eccezione i parametri <StarDate> e <EndDate> che, se specificati, costituiscono la data inferiore e la data superiore che viene confrontata con le date di inizio e fine dell’evento.
  • GetItemsCount(): Restituisce il numero di elementi nel calendario
  • GetSelectedItem(): Restituisce l’elemento selezionato (l’ultimo sul quale l’utente ha cliccato)
  • GetSelectedDate(): Restituisce la data correntemente selezionata nel calendario. Può essere utile per aggiungere un nuovo elemento in una posizione scelta dall’utente.
  • SetSelectedDate(<date>): Assegna la data corrente.
  • GetSelectedView(): Restituisce la vista corrente: Day (giorno), Week (settimana), Month (mese), Workweek (settimana lavorativa), Agenda.
  • Refresh(): aggiorna solo i dati presenti nel calendario, senza quindi aggiornare tutto il layout. Disponibile solo se NuovoLayout=true.
  • ScrollToDate(<Date>,<optional HH:mm>): posiziona il calendario sulla data specificata un’ora nel formato HH:MM, all’ora specificata. Disponibile solo se NuovoLayout=true.
  • ScrollToResource(<ResourceName>): posiziona il calendario sulla risorsa specificata. Disponibile solo se NuovoLayout=true.
  • SetSelectedView(<view>): Assegna la vista corrente. I valori possibili per il parametro <view> sono: “Day” (giorno), “Week” (settimana), “Month” (mese), “Workweek” (settimana lavorativa), “Agenda”.
  • SetHolidays(<fromDate>,<toDate>): Aggiunge al calendario le festività contenute nel Calendario Giorni Non Lavorativi comprese fra le date specificate nei parametri <fromDate> e <toDate>.
  • ShowOverflowButton: se False eventuali elementi presenti nella stessa cella non vengono sovrapposti, ma visualizzati tutti per intero, provocando l’ingrandimento della cella stessa. Se True, viene visualizzato solo un elemento, e un pulsante che consente di visualizzare gli altri. Default: False.

Gli eventi e i metodi GetAllItems() e GetSelectedItem() ritornano array di oggetti o oggetti singoli che rappresentano gli elementi del calendario e hanno le seguenti proprietà:

  • ID: identificatore univoco dell’elemento
  • Subject: titolo dell’elemento
  • Description: descrizione estesa dell’elemento
  • StartDate: Data e ora di inizio
  • EndDate: Data e ora di fine
  • AllDay: se True l’elemento occupa tutto il giorno
  • Editable: se True l’elemento è modificabile
  • Category: nome della categoria, che ne determina il colore
  • Owner: il nome della risorsa cui è attribuito l’elemento (è quello che nel metodo “AddItem” corrisponde al parametro “<Resource>”)

 

Di seguito riportiamo alcuni esempi di utilizzo dei metodi sopra esposti.

Il seguente frammento di codice può essere utilizzato nell’EventoCarica del form per aggiungere gli elementi al calendario, comprese categorie e festività.

form.findcontrol("Schedule1").AddItem("1","Appuntamento 1",Now(),Dateadd(DateInterval.Hour,3,Now()),false,"Descrizione 1","Rossa",true, "Risorsa 1")
form.findcontrol("Schedule1").AddItem("2","Appuntamento a sola lettura",Now(),Dateadd(DateInterval.Hour,3,Now()),false,"Descrizione 2","Verde",false, "Risorsa 1")
form.findcontrol("Schedule1").AddItem("3","Appuntamento tutto il giorno",Now(),Dateadd(DateInterval.Hour,3,Now()),true,"Descrizione 3","Gialla",true, "Risorsa 2")

form.findcontrol("Schedule1").AddCategory("Rossa","Red","White")
form.findcontrol("Schedule1").AddCategory("Verde","Green","White")
form.findcontrol("Schedule1").AddCategory("Gialla","Yellow","Black")

form.findcontrol("Schedule1").SetHolidays(DateAdd(DateInterval.Month,-3,Today()),DateAdd(DateInterval.Month,3,Today()))

Il seguente frammento di codice può essere utilizzato per aggiungere un elemento al calendario nella posizione selezionata dall’utente.

dim ds as datetime=form.findcontrol("Schedule1").GetSelectedDate()
dim df as datetime=DateAdd(Dateinterval.hour,2,ds)
form.findcontrol("Schedule1").additem(4,"Aggiunto",ds,df,false,"","Rossa",true, "Risorsa 1")

Il seguente frammento di codice può essere utilizzato per visualizzare tutti gli elementi del calendario.

dim items as dbarray=form.findcontrol("Schedule1").GetAllItems()
dim i as integer

dim s as string=""
for i=1 to items.size
	s+=items(i).Subject+" "+dttoc(items(i).StartDate)+" "+dttoc(items(i).EndDate)+" "+items(i).owner+vbcr
next

form.alert(s)
 

 

Metodi utilizzabili da codice lato Client (Javascript)

  • show(): visualizza l’oggetto.
  • hide(): nasconde l’oggetto.
  • externalDrop(<handler>): consente di specificare la funzione che viene eseguita quando un oggetto esterno viene trascinato su una cella. Tale funzione accetta tre parametri:
    • Data: contiene data e ora cui fa riferimento la cella
    • Risorsa: è il nome della risorsa che fa riferimento alla cella
    • se la griglia ha NuovoLayout=false ui: è l’oggetto jQuery restituito dall’evento “drop” (per ulteriori dettagli vedere qui)
    • se la griglia ha NuovoLayout=true Dati: è un oggetto le cui proprietà corrispondono alle colonne della griglia, e i cui valori sono quello della riga trascinata

Esempio, da inserire nell’evento RenderClient del form per gestire il drop da una griglia con NuovoLayout=false (vedere qui per ulteriori dettagli):

$('#<Schedule1>').externalDrop(
  function(data,risorsa,ui) {
    $('#<SelectedDate>').setValue(data.toJSON())
    $('#<SelectedResource>').setValue(risorsa)
    $('#<ProcedureCode2>').ServerExecute()
  }
)

Il seguente esempio si applica se la griglia ha NuovoLayout=true:

$('#<Scheduler1>').externalDrop(
  function(data,risorsa,dati) {
    $('#<PianificaCommessa>').ServerExecute(data.toJSON(),risorsa,dati.Commessa)
  }
)