# Obiekty Worker i Extender

Obiekty `Worker` i `Extender` rozszerzają model danych o dodatkową logikę UI:
properties wyliczane, akcje w menu Czynności, dodatkowe pola na formularzu.
Oba korzystają z [Context](context.md) do pobierania parametrów.

## Obiekty Worker

Dodają dodatkowe properties wyliczane do obiektów, które mogą być stosowane w bindowaniu lub pozwalają na 
definiowanie pozycji w menu Czynności.

* Worker jest zawsze przypisany do obiektu danych. 
* W nazwie klasy powinno się stosować sufiks `Worker`
* Nazwa klasy worker powinna określać jego działanie.
* Może być inicjowany z context za pomocą `[Context]`
* Rejestracja za pomocą atrybutu assembly z dwoma parametrami `[Worker<WorkerType, DataType>]` - zalecana wersja generic

### Rejestracja worker

```csharp
// Rejestracja zalecana atrybutem generic
[assembly: Worker<NazwaKlasyWorker, DataType>]
```

```csharp
// Niezalecana rejestracja atrybutem z parametrami
[assembly: Worker(typeof(NazwaKlasyWorker), typeof(DataType))]
```

### Deklaracja klasy worker

```csharp

[assembly: Worker<WyliczenieStanMagazynuWorker, Towar>]

// Worker wyliczający stan magazynowy
public class WyliczenieStanMagazynuWorker
{
    [Context] 
    public Magazyn Magazyn { get; set; }
    
    [Context] 
    public Towar Towar { get; set; }
    
    public decimal StanMagazynu =>
        Magazyn != null
            ? Towar.GetStan(Magazyn)
            : Towar.GetStanCalkowity();
}
```

Można stosować publiczne metod kontrolujące zachowanie property w edytorze:
* `bool IsVisibleXxx()` - widoczność pola
* `bool IsReadOnlyXxx()` - disable pola
* `object GetListXxx()` - szczegóły edycji

### Bindowanie na UI form.xml (liście)

Bindowanie wg schematu: `{Workers.<NazwaTypuBezSufiksWorker>.NazwaProperty}`
* Za początku zawsze `Workers.`
* Nazwa typu bez sufiksu `Worker` z nazwy klasy worker (tutaj `WyliczenieStanMagazynu`)

```xml
<Grid Name="List">
    <Field CaptionHtml="Kod" Width="17" EditValue="{Kod}" />
    <Field CaptionHtml="Nazwa" Width="30" EditValue="{Nazwa}" />
    <Field CaptionHtml="Stan magazynu" Width="17" EditValue="{Workers.WyliczenieStanMagazynu.StanMagazynu}" />
</Grid>
```

### Worker dodający pozycje do menu Czynności w UI

Worker udostępnia metodę w menu Czynności za pomocą atrybutu `[Action("Tytuł")]`.

* Jeden worker może udostępniać wiele pozycji (metod) w menu Czynności.
* Metoda Action (w przykładzie metoda `SendEmails`) obiektu worker zwraca [action result](./action-result.md)
* Metoda `bool IsVisibleXxx()` (np `bool IsVisibleSendEmails()`) jest opcjonalna i kontroluje widoczność w menu
* Metoda `bool IsEnabledXxx()` (np `bool IsEnabledSendEmails()`) jest opcjonalna i kontroluje aktywność pozycji w menu
* Metoda `string GetNameXxx()` (np `string GetNameSendEmails()`) jest opcjonalna i kontroluje tytuł pozycji w menu
* Metoda `bool IsCheckedXxx()` (np `bool IsCheckedSendEmails()`) jest opcjonalna i kontroluje zaznaczenie pozycji w menu

#### Przykład akcji wykonywanej grupowo na liście kontrahentów

```csharp
[assembly: Worker<SendEmailsForKontrahentWorker, Kontrahent>]

public class SendEmailsForKontrahentWorker
{
    [Context]
    public Kontrahent[] Kontrahenci { get; set; }

    [Action("Wyślij email")]
    public object SendEmails()
    {
        int counter = 0;
        foreach (var k in Kontrahenci)
        {
            if (!string.IsNullOrEmpty(k.Email))
            {
                WyslijEmail(k.Email);
                ++counter;
            }
        }
        
        return "Wysłano {0} emaili.".TranslateFormat(counter);
    }
    
    public bool IsVisibleSendEmails() => Kontrahenci?.Length>0;
    public bool IsEnabledSendEmails() => Kontrahenci.All(k => k.Email!="");

    private void WyslijEmail(string email) { /* ... */ }
}
```

#### Przykład akcji wykonywanej pojedynczo na towarze

```csharp
[assembly: Worker<KodDuzymiLiteramiWorker, Towar>]

public class KodDuzymiLiteramiWorker
{
    [Context]
    public Towar Towar { get; set; }

    [Action("Kod towaru dużymi literami")]
    public void MakeUpperName()
    {
        Towar.Nazwa = Towar.Nazwa.ToUpper();
    }

    public bool IsVisibleMakeUpperName() => Towar != null;
    public bool IsEnabledMakeUpperName() => !Towar.Nazwa.IsNullOrEmpty();
}
```

#### Przykład akcji otwierającej formularz kontrahenta dla dokumentu

```csharp
[assembly: Worker<PokazKontrahentaDokumentuWorker, DokumentHandlowy>]

public class PokazKontrahentaDokumentuWorker
{
    [Context]
    public DokumentHandlowy Dokument { get; set; }

    [Action("Kontrahent dokumentu")]
    public Kontrahent Pokaz()
    {
        return Dokument.Kontrahent;
    }
    
    public bool IsEnabledPokaz() => Dokument.Kontrahent != null;
    
    public string GetNamePokaz() => "Pokaż kontrahenta: {0}".TranslateFormat(Dokument.Kontrahent?.Nazwa);
}
```

## Obiekty Extender

Pozwalają na bindowanie logiki interface-owej do formularzy. Można bindować methods i properties z obiektu extender.

* Extender nie jest przypisany do danych
* W nazwie klasy powinno się stosować sufiks `Extender`
* Może być inicjowany z context za pomocą `[Context]`
* Rejestracja za pomocą atrybutu assembly z jednym parametrem `[Worker<ExtenderType>]` - zalecana wersja generic

Można stosować publiczne metod kontrolujące zachowanie property w edytorze:
* `bool IsVisibleXxx()` - widoczność pola
* `bool IsReadOnlyXxx()` - disable pola
* `object GetListXxx()` - szczegóły edycji

### Rejestracja extender

```csharp
// Rejestracja zalecana atrybutem generic
[assembly: Worker<NazwaKlasyExtender>]
```

```csharp
// Niezalecana rejestracja atrybutem z parametrami
[assembly: Worker(typeof(NazwaKlasyExtender))]
```

### Deklaracja klasy extender

```csharp
[assembly: Worker<UpperNazwaExtender>]

// Extender pokazujący nazwę dużymi literami
public class UpperNazwaExtender
{
    [Context] 
    public Towar Towar { get; set; }
    
    public string UpperNazwa 
    {
        get => Towar.Nazwa.ToUpper();
        set => Towar.Nazwa = value.ToUpper();
    }
    
    public bool IsReadOnlyUpperNazwa() => string.IsNullOrEmpty(Towar.Nazwa);
    
    public string PokazNazwe() => "Oryginalna nazwa towaru: {0}".TranslateFormat(Towar.Nazwa); 
}
```

### Bindowanie na UI pageform.xml (formularz)

Bindowanie wg schematu: `{new <NazwaTypuZSufixExtender>.NazwaProperty}`
* Za początku zawsze `new `
* Nazwa typu z sufiksem `Extender` z nazwy klasy extender (tutaj `UpperNazwaExtender`)
* Podobnie do property, możemy bindować metody: `{new <NazwaTypuZSufixExtender>.NazwaMetody()}`

```xml
<Page CaptionHtml="Nazwa zakładki">
    <Group CaptionHtml="Identyfikacja towaru">
        <Field CaptionHtml="Kod" Width="17" EditValue="{Kod}" />
        <Field CaptionHtml="Nazwa" Width="30" EditValue="{new UpperNazwaExtender.UpperNazwa}" />
        <Command CaptionHtml="Oryginalna nazwa" DataContext="{new UpperNazwaExtender}" MethodName="PokazNazwe" />
    </Group>
</Page>
```

## Pobieranie parametrów z context - atrybut [Context]

Worker (i extender) może pobierać parametry z context automatycznie.

```csharp
public class MojWorker
{
    [Context]  // Pobierane z context
    public Magazyn Magazyn { get; set; }
    
    [Context]  // Jeśli brak w context - okno parametrów
    public Kontrahent Kontrahent { get; set; }
}
```

## Pełny przykład - Worker z context

```csharp
[assembly: Worker<Soneta.Towary.StanTowaruWorker, Towar>]

namespace Soneta.Towary;

public class TowarExtenderParams(Context context) : ContextBase(context)
{
    [Accessor(AutoChange = true)]
    [Caption("Magazyn filtrowania")]
    public Magazyn MagazynFiltra { get; set; }
}

public class StanTowaruWorker
{
    [Context]
    public TowarExtenderParams Params { get; set; }

    [Context]
    public Towar Towar { get; set; }

    public decimal StanWMagazynie => 
        Params.MagazynFiltra != null
            ? PoliczStanMagazynu(Towar, Params.MagazynFiltra) 
            : PoliczStanMagazynu(Towar);

    private decimal PoliczStanMagazynu(Towar towar, Magazyn magazyn)
    {
        // Wyliczyć stan we wskazanym magazynie
        return 0;
    }

    private decimal PoliczStanMagazynu(Towar towar)
    {
        // Wyliczyć stan w całej firmie
        return 0;
    }
}
```

## Dobre praktyki

1. **Używaj [Context]** w obiektach worker i extender dla parametrów inicjowanych z context
2. **Dziedzicz z ContextBase** dla własnych klas parametrów (patrz [contextbase.md](contextbase.md))
3. **Metody Action zwracają [action result](./action-result.md)** - nie wywołuj UI bezpośrednio
4. **`CommitUI()` zamiast `Commit()`** - w workerach/extenderach uruchamianych z UI używaj `CommitUI()`