Definicja gadżetu przechowywana jest w pliku XML. Poniżej znajduje się opis, w jaki sposób daną definicję przygotować.
Struktura
Deklaracja jest plikiem XML. W pliku tym ustawiamy takie parametry jak tytuł, nazwa, miniaturka oraz ustawienia gadżetu.
Nazwa | Wymagany | Opis |
---|---|---|
name | ![]() | I18N. Nazwa gadżetu, która widoczna będzie w wyszukiwarce. |
url | ![]() | Adres, pod którym powinno zostać zwrócone ciało gadżetu (strona HTML wraz z skryptami JS). Link ten jest relatywny do wtyczki. |
description | I18N. Opis tego gadżetu. Opis widoczny jest podczas dodawania nowego gadżetu. | |
thumbnail | Obrazek ( w dowolnym formacie, obsługiwanym przez tag <img/>), który przedstawia wygląd działającego gadżetu. Jest on widoczny podczas wyszukiwania gadżetu. Zalecane wymiary: 120x100 px. Gadżet bez miniaturki będzie miał ustawione jako zdjęcie logo Suncode. |
Podstawowa definicja:
<?xml version="1.0" encoding="UTF-8"?> <gadget> <name>gadget.test.name</name> <url>/gadget/test</url> <description>gadget.test.desc</description> <thumbnail>/resources/thumb.png</thumbnail> </gadget>
Konfiguracja gadżetu
Każdy gadżet ma zdefiniowany własny zestaw właściwości. Właściwości te pozwalają użytkownikowi na dostosowanie gadżetu do swoich potrzeb.
Właściwości gadżetów są zalecaną metodą przechowywania danych na potrzeby gadżetów.
Właściwości przechowywane są w formie tekstowej (schemat bazy danych) , dlatego bardziej skomplikowane obiekty możemy serializować np. do formatu JSON.
Właściwości gadżetu stosowane są zazwyczaj do:
- zapis wyświetlanego raportu/widoku etc.
- konfiguracji ilości wyświetlanych wyników
- konfiguracji czasu odświeżania gadżetu
- wyboru konkretniej skórki gadżetu
Definiowanie właściwości
<?xml version="1.0" encoding="UTF-8"?> <gadget> <!-- Pola podstawowe --> <!-- Opis konfiguracji gadżetu --> <configuration> <!--Definicja właściwości --> <properties> <property name="textproperty" type="text" /> <property name="numberproperty" type="number" /> <property name="booleanproperty" type="boolean" value="false" /> </properties> <!-- Skrypt budujący formularz --> <build-script> <![CDATA[ // skrypt JavaScript odpowiedzialny za budowę formularza właściwości gadżetu ]]> </build-script> </configuration> </gadget>
Element property
Element property tworzy właściwość, która zostanie stworzona po dodaniu gadżetu do dashboardu.
Nazwa | Wymagany | Opis |
---|---|---|
name | ![]() | Nazwa, która jednoznacznie identyfikuje właściwość gadżetu ( do 100 znaków ) |
type | Typ właściwości (domyślnie text). Określa, jakie wartości mogą być zapisane w podanym polu. Ustawienie odpowiedniego typu ułatwia pracę z tymi właściwościami z poziomu Javy. | |
value | Wartość domyślna właściwości. |
Typy właściwości
Każda właściwość gadżetu implementuje interfejs: com.suncode.plugin.dashboard.gadget.Property<T>.
Właściwości przechowują wartość jako konkretny obiekt. Jeżeli nie znamy typu właściwości, możemy odczytywać i zmieniać jej wartość tylko używając tekstu (metody getRawValue(), setRawValue(String rawValue) )
Text - tekstowa
Właściwość typu text przechowuje wartość jako java.lang.String.
<property name="textproperty" type="text" />
TextProperty property = gadget.getProperty("textproperty", TextProperty.class);
Number - liczbowa
Właściwość typu text przechowuje wartość jako java.lang.Number ( java.lang.Long lub java.lang.Double, w zależności czy wartość zawiera separator dziesiętny .(kropka) ).
<property name="numberproperty" type="number" />
NumberProperty property = gadget.getProperty("numberproperty", NumberProperty.class); // pobieranie wartości liczbowych property.getValue(); property.getValueAsDouble(); property.getValueAsInteger(); property.getValueAsLong();
Boolean - logiczna
Właściwość typu boolean przechowuje wartość jako java.lang.Boolean.
<property name="booleanproperty" type="boolean" />
BooleanProperty property = gadget.getProperty("booleanproperty", BooleanProperty.class);
Budowa formularza ustawień
Konfiguracja gadżetów może ograniczać się do kilku pól, które muszą być uzupełnione przez użytkownika. Mogą jednak istnieć przypadki, gdy konfiguracja jest bardziej dynamiczna ( np. gadżet raportów jasper wymaga wygenerowania dynamicznych pól, w zależności, który raport zostanie wybrany), dlatego twórca gadżetu musi sam zbudować cały formularz, korzystając z udostępnionego API.
Formularz w całości bazuje na ExtJS 3. Wszystkie pola dodane znajdują się w obiekcie Ext.form.FieldSet.
Poniższy skrypt zbuduje formularz z 2 takimi samymi polami:
<!-- Skrypt budujący formularz --> <build-script> <![CDATA[ // dodanie pola tekstowego Properties.add( Properties.text('nazwa', '#I18N#gadget.label#') ); // dodanie takiego samego pola używając ExtJS api Properties.add({ xtype: 'textfield', name: 'nazwa', fieldLabel: '#I18N#gadget.label#', value: Properties.value('nazwa') // opcjonalne, wartość pola ustawiana automatycznie }); ]]> </build-script>
Tłumaczenia skryptu
Możliwe jest tłumaczenie skryptu (np. labeli, tooltip'ów). Tłumaczenia pobierane są ze standardowego mechanizmu wtyczek - modułu I18N (TODO: link do modułu)
Jeżeli skrypt zawiera token #I18N#{messagekey}# gdzie {messageKey} to klucz wiadomości zdefiniowany w pliku *.properties, to token ten jest zamieniany na odpowiadającą mu przetłumaczoną wiadomość.
Properties.add({ xtype: 'numberfield', fieldLabel: '#I18N#number.label#', tooltip: '#I18N#number.tooltip#' }); // zostanie zamienione na Properties.add({ xtype: 'numberfield', fieldLabel: 'Numer', tooltip: 'Number tooltip' });
Obiekt Properties
W skrypcie budowania formularza dostępny jest obiekt Properties, który umożliwia pobranie obiektu formularza i udostępnia zestaw metod do pobierania właściwości gadżetu, dodawania standardowych pól etc.
Metoda | Opis |
---|---|
getForm | Zwraca obiekt formularza Ext.form.FormPanel. |
getFieldSet | Zwraca kontener Ext.form.FieldSet, do którego powinniśmy dodawać wszystkie pola. Dzięki temu wszystkie gadżety mają zunifikowany wygląd. |
add(fields)
| Skrót do getFieldSet().add(components). Dodaje do kontenera podany komponent. |
insert(index, field)
| Skrót do getFieldSet().insert(index, component). Dodaje do kontenera podany komponent na określonym miejscu. |
remove(field)
| Skrót do getFieldSet().remove(component). Usuwa z kontenera podane pole. Możliwe jest także podanie identyfikatora komponentu. |
removeAll | Skrót do getFieldSet().removeAll(). Usuwa z kontenera wszystkie komponenty (pola). |
getPluginUrl(url)
| Zwraca absolutny adres URL do wtyczki, z podanego relatywnego URL. Absolutny adres url ma budowę: <contextPath>/plugin/<pluginKey>/<url> |
getAbosluteUrl(url)
| Zwraca absolutny adres URL, dodając do podanego adresu context path. (Analogicznie do Suncode.getAbsolutePath(url)) |
getProperty(name)
| Zwraca właściwość o podanej nazwie. Zwrócona właściwość: { name: 'nazwa', value: 'wartość', type: 'text' } |
value(name)
| Skrót do getProperty(name).value. Zwraca wartość właściwości o podanej nazwie lub undefined, jeżeli nie ma takiej właściwości |
refreshLayout | Odświeża layout formularza oraz całego dashboardu. Funkcja powinna być użyta, jeżeli np. dodajemy dynamicznie pola już po wyrenderowania formularza. |
Metody pomocnicze do tworzenia pól formularza W przypadku użycia tych metod, wartość pól jest automatycznie ustawiana na podstawie właściwości gadżetu o tej samej nazwie.
| |
hidden(name, config)
| Tworzy pole ukryte (xtype: hidden) o podanej nazwie. Pole ukryte może być wykorzystywane do zapisywania bardziej skomplikowanych lub dynamicznych pól. Np. jeżeli liczba pól jest dynamiczna, pole ukryte może służyć do przechowywania definicji tych pól w formacie JSON. |
text(name, label, config)
| Tworzy pole tekstowe (xtype: textfield) o podanej nazwie, labelu.
|
number(name, label, config)
| Tworzy pole liczbowe (xtype: numberfield) o podanej nazwie, labelu. |
list(name, label, data, config)
| Tworzy statyczną listę rozwijaną (xtype: combo), o podanych wartościach. Pierwsza wartość jest wybierana automatycznie. |
dynamicList(name, label, data, config)
| Tworzy dynamiczną listę rozwijaną (xtype: numberfield), która zawiera dane zwrócone przez określony servlet. Servlet musi zwrócić dane w określonym formacie ( możemy użyć klasy pomocniczej com.suncode.plugin.dashboard.web.support.DynamicListResult) Format danych { records: [{ name: <nazwa>, value: <wartość> }, { name: <nazwa>, value: <wartość> }] } Przykład servletu @Controller public class TestController { @ResponseBody @RequestMapping( value = "/list", method = RequestMethod.GET ) public DynamicListResult getList() { DynamicListResult views = new DynamicListResult(); views.addEntry( "pierwszy", 1 ); views.addEntry( "drugi", 2 ); return views; } } |
Przykład rozbudowanego formularza właściwości
Budowany formularz właściwości nie musi być prosty. Możemy stworzyć dowolny formularz, mając do dyspozycji obiekt formularza i listenery.
Rozbudowany formularz wymagany był w gadżecie wyświetlającym raporty Jasper. Dla każdego raportu zdefiniowane były pola, które mógł uzupełnić użytkownik aby zmienić jego wygląd. Wymagane było pobieranie raportu wraz z definicjami jego właściwości, i dynamiczne dodawanie odpowiednich pól. Wartości z tych pól zapisywane były w formacie JSON do pola ukrytego.
<properties> <!-- Wybrany raport --> <property name="report" type="number" /> <!-- Parametry widoku --> <property name="params" type="text" /> <!-- Częstotliwość odświeżania raportu --> <property name="refreshInterval" type="number" value="60"/> </properties>
Poniżej przedstawiono cały skrypt gadżetu raportów Jasper:
0 Comments