[Intum](https://intum.fr/aide.md) / [Formularze](https://intum.fr/aide/formularze.md)

# [Widget Formularza na Stronę](https://intum.fr/aide/formularze/formularze-widget.md) | [API](#api)

## Do czego służy widget

Widget formularza pozwala osadzić formularz na dowolnej stronie internetowej — bez potrzeby tworzenia własnego kodu. Wklejasz gotowy skrypt na swoją stronę, a formularz automatycznie się załaduje i będzie zbierał dane od odwiedzających.

## Jak wstawić formularz na stronę

1. Otwórz formularz w panelu Intum
2. W sekcji **Skrypt formularza** znajdziesz gotowy kod do skopiowania
3. Kliknij w pole z kodem — tekst automatycznie się zaznaczy
4. Skopiuj kod i wklej go w HTML swojej strony, w miejscu gdzie formularz ma się wyświetlić

### Jak wygląda kod

Kod składa się z dwóch elementów:

- **Skrypt JavaScript** — ładuje silnik formularzy (wystarczy jeden raz na stronie, nawet jeśli masz kilka formularzy)
- **Element div** — kontener, w którym pojawi się formularz. Zawiera unikalny token identyfikujący Twój formularz

Możesz wstawić wiele formularzy na jednej stronie — każdy z osobnym elementem div.

## Domyślne wartości pól

Możesz przekazać domyślne wartości do pól formularza za pomocą atrybutów `data-field-*` na elemencie div. Dzięki temu formularz automatycznie wypełni wybrane pola przy ładowaniu.

### Jak to działa

1. W ustawieniach pola formularza ustaw **Kod pola** (np. `email`, `imie`, `firma`)
2. W kodzie embed dodaj atrybuty `data-field-{kod}` z wartościami:

```html
<script src="https://widgets.intum.net/widgets/intum-forms-widget.js"></script>
<div data-form="TOKEN"
     data-field-email="jan@example.com"
     data-field-imie="Jan"
     data-field-firma="Firma Sp. z o.o.">
</div>
```

Po załadowaniu formularza pola z kodem `email`, `imie` i `firma` zostaną automatycznie wypełnione podanymi wartościami.

### Zastosowania

- **Personalizacja** — wypełnij dane klienta, które już znasz (np. z CRM lub linku w mailu)
- **Kampanie marketingowe** — dodaj ukryte parametry identyfikujące źródło (np. `data-field-kampania="newsletter_03"`)
- **Integracje** — dynamicznie ustaw wartości z JavaScript na stronie

### Dynamiczne ustawianie wartości z JavaScript

```html
<script>
  // Ustaw wartości przed załadowaniem widgetu
  const formDiv = document.querySelector('[data-form="TOKEN"]');
  formDiv.dataset.fieldEmail = 'jan@example.com';
  formDiv.dataset.fieldImie = 'Jan';
</script>
```

## Jak to działa

Po załadowaniu strony:

1. Skrypt szuka na stronie wszystkich kontenerów z formularzami
2. Pobiera treść formularza z serwera (na podstawie tokenu)
3. Wyświetla formularz z polami, walidacją i przyciskiem wysłania
4. Po wygenerowaniu — wypełnia pola domyślnymi wartościami z atrybutów `data-field-*`
5. Po wypełnieniu i wysłaniu — dane trafiają do systemu, a użytkownik widzi potwierdzenie lub zostaje przekierowany

## Personalizacja wyglądu

Formularz ma domyślne style, ale możesz je dostosować:

- **Klasa CSS** — nadaj własną klasę i styluj formularz w CSS swojej strony
- **Style inline** — wpisz bezpośrednio style CSS w ustawieniach formularza
- **Klasa przycisku** — zmień wygląd przycisku wysyłania
- **Tekst przycisku** — zmień napis na przycisku (domyślnie "Wyślij")
- **Własny JavaScript** — dodaj dodatkowy kod JS do formularza

## Zwrotka po wysłaniu

Po wypełnieniu formularza użytkownik może:

- Zobaczyć **komunikat** — treść HTML wyświetlona w miejscu formularza (obsługuje szablony Liquid z danymi z formularza)
- Zostać **przekierowany** — na podany URL (np. strona z podziękowaniem)

## Zabezpieczenia

Widget ma wbudowane zabezpieczenia anti-spam chroniące przed botami i niechcianymi zgłoszeniami.

## Okres aktywności

Jeśli formularz ma ustawiony okres aktywności (data od–do), widget automatycznie wyświetli komunikat o nieaktywności formularza poza tym okresem.

## Wiele formularzy na jednej stronie

Możesz osadzić kilka formularzy na jednej stronie. Skrypt JavaScript wstawiasz tylko raz, a dla każdego formularza dodajesz osobny element div z właściwym tokenem.

## Powiązane

- [Formularze](formularze) — ogólny opis modułu i typy pól
- [Zgłoszenia](zgloszenia) — dane zebrane przez formularze

---

## API

### Ogólne API

# Intum API

Dokumentacja API platformy [Intum](https://intum.pl) - system operacyjny firmy.

## Host

Host jest zawsze taki sam jak adres konta: `xxxx.intum.com` lub `xxx.intum.pl` (w zależności od ustawień konta)

## Autoryzacja

Wszystkie requesty API wymagają `api_token`:
- header: `Authorization: Bearer TOKEN`

Token możesz wygenerować w **Ustawienia Konta** → **Tokeny API**

## Kod widgetu

Kod do wstawienia na stronę (dostępny w widoku formularza):

```html
<script src="https://widgets.intum.net/widgets/intum-forms-widget.js"></script>
<div data-form="TOKEN_FORMULARZA"></div>
```

- `TOKEN_FORMULARZA` — unikalny token przypisany do formularza
- Skrypt wystarczy wstawić raz na stronie, nawet przy wielu formularzach
- Każdy formularz wymaga osobnego `<div data-form="...">`

## Domyślne wartości pól

Aby przekazać domyślne wartości, dodaj atrybuty `data-field-{kod_pola}` na elemencie div:

```html
<div data-form="TOKEN"
     data-field-email="jan@example.com"
     data-field-imie="Jan"
     data-field-firma="Firma Sp. z o.o.">
</div>
```

### Mechanizm działania

1. Każde pole formularza ma **kod pola** (`fields["code"]`) — ustawiany w edycji pola. Jeśli nie ustawiony, domyślny to `field{id}`
2. Widget po załadowaniu HTML szuka atrybutów `data-field-*` na kontenerze
3. Dla każdego atrybutu znajduje input z `data-code="{kod}"` i ustawia jego wartość
4. Kody są sanityzowane — spacje i znaki specjalne zamieniane na `_`

### JavaScript API

```javascript
// Dynamiczne ustawianie wartości przed załadowaniem widgetu
const div = document.querySelector('[data-form="TOKEN"]');
div.dataset.fieldEmail = 'jan@example.com';
div.dataset.fieldImie = 'Jan';

// Uwaga: dataset konwertuje camelCase na kebab-case:
// div.dataset.fieldEmail → data-field-email
// div.dataset.fieldFirstName → data-field-first-name
```

### Obsługiwane typy pól

Domyślne wartości działają dla pól z inputami: `string`, `text`, `select`.

## Personalizacja przez API

### PATCH `/form/forms/:id.json`

Ustawienia wyglądu widgetu w polu `fields`:

| Klucz | Opis |
|-------|------|
| `submit_text` | Tekst przycisku wysłania |
| `form_class` | Klasa CSS formularza |
| `form_style` | Style CSS inline |
| `button_class` | Klasa CSS przycisku |
| `form_redirect` | URL przekierowania po wysłaniu |
| `form_response` | HTML/Liquid zwrotka po wysłaniu |
| `form_anonymous` | Ukryj dane IP/agent |
| `custom_js` | Własny JavaScript |
| `antispam` | Włącz honeypot (1/0) |

## Klasy CSS widgetu

Widget generuje klasy CSS z ID formularza:

- `.intum_form_{id}` — kontener formularza
- `.intum_button_{id}` — przycisk wysyłania
- `.intum_field_{id}_{kind}_{type}` — poszczególne pola

Możesz nadpisać te style w CSS swojej strony.

## Hosting widgetu

HTML formularza jest automatycznie generowany i hostowany na S3. Po każdym zapisie formularza widget jest aktualizowany. URL widgetu zapisany w `config.s3_url`.