Podręcznik referencyjny: Supplement

Wprowadzenie

Obiekt biznesowy typu Supplement może być użyty do rozszerzenia obiektu biznesowego innego typu o atrybuty biznesowe. Ten rozszerzony obiekt biznesowy jest zazwyczaj jednostką biznesową. Obiekt zależny może również zostać rozszerzony przez supplement, ale supplement nie może rozszerzyć supplementu.

Rozszerzenie jednostki biznesowej za pomocą supplementu w porównaniu z obiektem deweloperskim o typie Extension ma następujące zalety:

• brak technicznych zależności między jednostką biznesową a supplementem. Dzięki czemu zmniejsza się ilość zadań konfliktowych
• obiekty biznesowe aplikacji nie mogą być rozszerzane za pomocą obiektu deweloperskiego typu Extension, ale mogą być rozszerzane za pomocą supplementów.
• Suplement pozwala na wyprowadzenie danych, co skutkuje zmniejszeniem szerokości tabeli.

Supplement często pojawia się w interfejsie użytkownika i może być używany w rozszerzeniach wyszukiwania lub w filtrze obiektów w aplikacjach Eksport danych i Import danych. W tym celu dostępne są gotowe mechanizmy automatyzujące. Alternatywnie do supplementów można również użyć własny obiekt biznesowego.

W artykule Obiekt deweloperski: Business object znajduje się opis wprowadzania i edytowania obiektów biznesowych.

Typowym przypadkiem użycia dodatków jest dodanie atrybutu do istniejącej aplikacji dialogowej. W artykule opisano prosty przykład rozwoju, który pokazuje, jakie obiekty należy zarejestrować i w jaki sposób to zrobić.

Grupa docelowa

• Programiści

Tworzenie supplementu

Supplement tworzy się zawsze na podstawie obiektu biznesowego typu Business Entity lub Dependent, do którego supplement ma się odnosić. Aby utworzyć dodatek w aplikacji Obiekty deweloperskie, należy użyć akcji związanej z aplikacją Utwórz Dependent lub Supplement. Postępuj zgodnie z poniższymi instrukcjami.

Instrukcja:

1. Otworzyć aplikację Obiekty deweloperskie
2. W nagłówku należy wybrać w polu Typ opcję: Business Object, na zakładce Edytor w polu Typ wybrać jedną z opcji do której będzie tworzony dodatek:
   • Business entity
   • Dependent
3. Na standardowym pasku narzędzi należy wskazać zadanie deweloperskie, na podstawie którego zostanie utworzony dodatek.

1. Wybrać akcję Utwórz Dependent lub Supplement dostępną pod przyciskiem na pasku narzędzi [Utwórz dodatkowe obiekty].
2. Otwarte zostanie okno dialogowe Utwórz elementy zależne
3. Należy wybrać wartość Supplement w polu Typ. Odpowiednie dane są domyślnie ustawianie w polach Nazwa i Oznaczenie.
4. Jeśli suplement ma być używany w określonym interfejsie, należy go wprowadzić w polu Interfejs.
5. Wybrać przycisk [OK]. Okno dialogowe zostanie zamknięte, a obiekt biznesowy typu Supplement zostanie utworzony z wprowadzonymi danymi. Ma on status Nowy i jest przypisany do wcześniej wybranego zlecenia deweloperskiego. Ustawienia są przyjmowane przez jednostkę biznesową (lub Dependent), do którego supplement ma się odnosić.
6. Tworzona jest relacja _businessObject z jednostką biznesową.
7. Klucz podstawowy supplementu jest generowany zgodnie z kluczem podstawowym powiązanej jednostki biznesowej.
8. Należy wprowadzić atrybuty, które mają zostać dodane do encji biznesowej.
9. Wybrać przycisk [Zapisz] na standardowym pasku narzędzi. Suplement zostanie zapisany w wybranym zleceniu deweloperskim.

Tworzenie widoku obiektu

Z reguły atrybuty supplementu powinny być również edytowalne w interfejsie użytkownika w odpowiedniej aplikacji. Tryb projektowania jest dostępny dla modyfikowalnej aplikacji, której można użyć do dostosowania układu do własnych wymagań. Wymagany jest obiekt deweloperski typu Data view, aby można było dodać atrybuty do aplikacji w trybie projektowania. Konwencja nazewnictwa służy do tworzenia widoku obiektu, jak pokazano w poniższym przykładzie.

Aby otworzyć okno dokowane Tryb projektowania, należy:

1. Wejść w tryb projektowania rozwijając opcję Wybierz i organizuj widoki w wybranej aplikacji np. Artykuły
2. Na pasku zadań w menu użytkownika należy wybrać przycisk [Tryb projektowania]

Jeśli suplement i widok obiektu zostaną zapisane z identycznymi w pełni kwalifikowanymi nazwami z wyjątkiem komponentów obj i model, widok obiektu jest automatycznie oferowany do wyboru w trybie projektowania dostosowywanej aplikacji z jej atrybutami.

Widok obiektu nadal wymaga informacji o klasie implementującej. Można użyć m.inm. następującej nadklasy:

com.cisag.pgm.base.DataSupplement

W konstruktorze można jako „parent” wskazać widok obiektu, który zostanie w ten sposób skutecznie rozszerzony, jednocześnie wykluczając inne widoki. Dzięki temu widoki obiektów dziedziczą ustawienia z określonego widoku głównego.

Na przykład, jeśli główny widok nie jest edytowalny w określonych warunkach, to warunek ten automatycznie dotyczy również widoku obiektu suplementu. W zależności od wymagań projektu może być również zasadne użycie jako DataObject standardowego obiektu danych pgm.

Więcej informacji na temat widoków obiektów można znaleźć w artykule Obiekt deweloperski: Data view.

Przestrzeganie konwencji nazewnictwa lub zintegrowanie suplementu za pomocą hooków powoduje, że widok obiektu staje się dostępny w trybie projektowania aplikacji.

Jest on widoczny zgodnie z następującym wzorcem nazewnictwa (przy wcześniejszych przykładowych danych):<prefiks_deweloperski>_ItemSupplement.

Implementacja

• applyDefaults
• validate

DataObject

Aby móc zarejestrować widok obiektu, potrzebny jest obiekt DataObject. W najprostszym przypadku implementacja wygląda następująco:

public class ItemSupplementDataObject extends DataSupplement<ItemSupplement, ItemView> {

public ItemSupplementDataObject(ItemSupplement obj, ItemView parentView) {

super(obj, parentView);

}

}

Hooki

Hook Contract

<?xml version="1.0" encoding="UTF-16"?>
<HookContract xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="HookXMLSchema.xsd">

<!– Don’t change this line and the lines above! –>

<HOOK_IMPLEMENTATION>
<contract>
<hook>
<interface>
com.cisag.app.general.item.hook.log.ItemApplyDefaultsHook
</interface>
<implementation>
com.<development prefix>.app.general.ItemHookImpl
</implementation>.
</hook>
<hook>
<interface>
com.cisag.app.general.item.hook.log.hook.ItemValidateHook
</interface>
<implementation>
com.<development prefix>.app.general.ItemHookImpl
</implementation>.
</hook>.
</kontrakt>
</HOOK_IMPLEMENTATION>
</HookContract>

Poniżej znajduje się przykładowa implementacja hooka applyDefaults.

import com.cisag.pgm.base.Path;

public class ItemHookImpl implements ItemApplyDefaultsHook<Item, ItemAccess.Full>{

public void applyDefaults(Full full, ItemView itemView){

ItemSupplement suppObj = ItemSupplement.newTransientInstance();

suppObj.setYourAttribute(...) // twój atrybut

byte[] org = Company.getCompanyGuid();

CisObjectInitialiser.getInstance(ItemSupplement.class).init(suppObj, org);

ItemSupplementDataObject itemSupplementDataObject =

        new ItemSupplementDataObject(suppObj, itemView);

CisDataViewManager dvm = CisEnviron-ment.getInstance().getDataViewManager();

ItemSupplementAccess access = dvm.create(ItemSupplementView.class, itemSupplementDataObject);

Path suppPath = Path.getSupplementInstance(ItemView.class, ItemSupple-mentView.class);

full.setValue(suppPath, access);

}

}

validate

Poniżej znajduje się przykładowa implementacja hooka validate:

import com.cisag.pgm.base.Path;

public class ItemHookImpl implements ItemValidateHook<Item, ItemAccess.Full>

public void validate(ItemView itemView){

Path suppPath = Path.getSupplementInstance(ItemView.class, ItemSupple-mentView.class);

Path append = supp-Path.append(ItemSupplementView.Attribute.$yourAttribute);

ItemSupplementView value = itemView.getValue(suppPath);

CisMessageManager mm = CisEnvironment.getInstance().getMessageManager();

mm.setProgramMessagePath(suppPath);

if (value.getYourAttribute()!=null){

// insert validation here

}

}

Interfejs programistyczny

Trwałość (Persistence)

Skutki

Jeśli zostanie zachowana konwencja nazewnictwa suplementów, jak opisano powyżej, suplement lub widok obiektu na nim oparty będzie dostępny w trybie projektowania.

Dostępne są również następujące funkcje automatyczne:

• w aplikacjach Import danych i Eksport danych supplement jest automatycznie dostępny. Nie ma potrzeby rozszerzania kontrolera. Jeśli supplement zostanie nazwany zgodnie z przykładem ItemSupplement i będzie należał do obiektu biznesowego Item, w filtrze dla obiektu biznesowego Item pojawi się relacja do supplementu. Nazwa relacji to <Prefiks deweloperski>_ItemSupplement, analogicznie do trybu projektowania. Tutaj <Prefiks deweloperski> to prefiks deweloperski systemu.
• w ten sam sposób supplement jest dostępny w konfigurowalnych wyszukiwaniach i aplikacjach typu lista.
• mie jest wymagane ręczne programowanie wsparcia dla języków (NLS). Jeśli w supplemencie znajduje się atrybut obsługujący NLS, to dzięki standardowej implementacji zostanie on automatycznie obsłużony.