Manuál implementácie tlačidla IMPORT

1. Účel integrácie

Hosťovský web môže obsahovať tlačidlo IMPORT do pasteToPrint. Po kliknutí sa otvorí pasteToPrint v novom okne a používateľovi sa ponúkne vloženie odoslaného obsahu.

Prenos prebieha iba v prehliadači pomocou štandardného API window.postMessage. Hosťovský server nepotrebuje prístup k serveru pasteToPrint, API kľúč ani CORS konfiguráciu.

1.1 Možnosti importu

Vyberte spôsob podľa obsahu a možností vášho webu alebo AI klienta.

1. Používateľ klikne na tlačidlo IMPORT.
2. Hosťovský web otvorí pasteToPrint.
3. Web odošle text alebo obrázok.
4. Používateľ import potvrdí.

2. Predpoklady

Implementátor hosťovského webu potrebuje:

• možnosť vložiť HTML a JavaScript na hosťovskú stránku,
• obsah, ktorý sa má odoslať: text, HTML alebo obrázok vo formáte data:image/...;base64,...,
• povolené otváranie nového okna po kliknutí používateľa.

3. Rýchla implementácia

Dlhá komunikačná logika je uložená na serveri pasteToPrint. Hosťovský web načíta verejné SDK a pri kliknutí zavolá iba funkciu PasteToPrint.import().

3.1 Vložte SDK do časti head

Tento riadok vložte medzi značky <head> a </head>. Na jednej stránke ho stačí vložiť raz.

<script src="https://www.pastetoprint.com/assets/js/import-button.js?v=1.5.0" defer></script>

3.2 Vložte tlačidlo a krátku obsluhu kliknutia

Nasledujúci blok vložte na miesto, kde sa má zobraziť tlačidlo IMPORT. V ukážke sa odosiela obyčajný text.

<button type="button" id="pasteToPrintImportBtn" data-pastetoprint-button>
  IMPORT do pasteToPrint
</button>

<script>
document
  .getElementById('pasteToPrintImportBtn')
  .addEventListener('click', async () => {
    try {
      await PasteToPrint.import({
        title: 'Poznamka z hostovskeho webu',
        items: [
          {
            kind: 'text',
            text: 'Tento text bol odoslany z hostovskeho webu.'
          }
        ]
      });
    } catch (error) {
      alert(error.message);
    }
  });
</script>

3.3 Voliteľné nastavenia SDK

Druhý parameter funkcie PasteToPrint.import() je určený pre lokálne testovanie alebo pre prísnejšie timeouty. V ostrej prevádzke ho zvyčajne netreba nastavovať.

await PasteToPrint.import(payload, {
  targetUrl: 'https://www.pastetoprint.com/',
  readyTimeoutMs: 20000,
  resultTimeoutMs: 120000,
  windowName: 'pasteToPrintImport'
});

4. Príklady použitia

4.1 Vygenerovaný QR kód z elementu canvas

Použite v prípade, že QR generátor vykreslí obrázok do <canvas>. Identifikátor qrCanvas nahraďte identifikátorom použitým vo vašom projekte.

const qrDataUrl = document
  .getElementById('qrCanvas')
  .toDataURL('image/png');

await PasteToPrint.import({
  title: 'QR kod',
  items: [
    {
      kind: 'image',
      mime: 'image/png',
      name: 'qr-code.png',
      alt: 'Vygenerovany QR kod',
      dataUrl: qrDataUrl
    }
  ]
});

4.2 Vygenerovaný QR kód z elementu img

Tento variant použite, ak existujúci generátor nastavuje src obrázka priamo na hodnotu data:image/png;base64,....

const qrDataUrl = document
  .getElementById('generatedQrImage')
  .src;

await PasteToPrint.import({
  title: 'QR kod',
  items: [
    {
      kind: 'image',
      mime: 'image/png',
      name: 'qr-code.png',
      alt: 'Vygenerovany QR kod',
      dataUrl: qrDataUrl
    }
  ]
});

4.3 Text

await PasteToPrint.import({
  title: 'Objednavka 2026-001',
  items: [
    {
      kind: 'text',
      text: [
        'Objednavka: 2026-001',
        'Suma: 24,90 EUR',
        'Variabilny symbol: 123456'
      ].join('\n')
    }
  ]
});

4.4 Formátovaný HTML obsah s CSS

HTML vložte do povinného poľa html a CSS do voliteľného poľa css tej istej položky. pasteToPrint bezpečné CSS aplikuje priamo na zodpovedajúce HTML elementy, aby sa zachovalo v editore, tlači aj PDF. Skripty, formuláre, vložené objekty, externé zdroje a nepovolené značky, selektory, atribúty alebo CSS vlastnosti odstráni.

CSS podporuje bezpečné selektory značiek, tried a ID, vnorené a priame potomstvo, farby, typografiu, rozostupy, orámovanie, rozmery, flex, grid a zalomenia strán. Pravidlá sa prevedú na inline štýly, aby zostali zachované v editore, pri tlači aj exporte PDF. @import, vzdialené URL, spustiteľný kód, transformácie a animácie sa odstránia.

await PasteToPrint.import({
  title: 'Rekapitulacia objednavky',
  items: [
    {
      kind: 'html',
      html: [
        '<div class="rekapitulacia">',
        '  <h2>Objednavka 2026-001</h2>',
        '  <p class="suma"><strong>Suma:</strong> 24,90 EUR</p>',
        '<ul>',
        '  <li>Polozka A</li>',
        '  <li>Polozka B</li>',
        '</ul>',
        '</div>'
      ].join(''),
      css: [
        '.rekapitulacia { padding: 16px; border: 1px solid #93c5fd; }',
        '.rekapitulacia h2 { color: #1d4ed8; font-size: 24px; }',
        '.rekapitulacia .suma { color: #166534; font-weight: 700; }'
      ].join('\n')
    }
  ]
});

4.5 Kombinácia textu a obrázka

const qrDataUrl = document
  .getElementById('qrCanvas')
  .toDataURL('image/png');

await PasteToPrint.import({
  title: 'Platobny QR kod',
  mode: 'append',
  items: [
    {
      kind: 'html',
      html: '<h2>Platobne udaje</h2><p>Suma: 24,90 EUR</p>'
    },
    {
      kind: 'image',
      mime: 'image/png',
      name: 'payment-qr.png',
      alt: 'Platobny QR kod',
      dataUrl: qrDataUrl
    }
  ]
});

5. Formát správy

Rozlišujte verejný vstup funkcie PasteToPrint.import() a internú správu window.postMessage. SDK verejný vstup overí, doplní technické polia a vytvorí správu protokolu v1.

5.1 Verejný vstup SDK

{
  title: 'Nazov dokumentu',
  mode: 'append',
  options: {
    imageScale: 100
  },
  layout: {
    marginsMm: { top: 10, right: 11, bottom: 10, left: 10 }
  },
  items: [
    {
      kind: 'text',
      text: 'Obsah dokumentu'
    }
  ]
}

Pre názov dokumentu odporúčame koreňové pole title. SDK z dôvodu spätnej kompatibility prijme aj options.title a do internej správy ho vždy uloží ako options.title.

5.2 Interná správa postMessage

Pri použití SDK ju nevytvárajte ručne. Hosťovský web odosiela objekt typu pasteToPrint.import s verziou 1.

{
  type: 'pasteToPrint.import',
  version: 1,
  nonce: 'jednorazovy-identifikator',
  mode: 'append',
  options: {
    title: 'Nazov dokumentu',
    imageScale: 100
  },
  layout: {
    marginsMm: { top: 10, right: 11, bottom: 10, left: 10 }
  },
  items: [
    {
      kind: 'image',
      mime: 'image/png',
      name: 'qr-code.png',
      alt: 'QR kod',
      dataUrl: 'data:image/png;base64,...'
    }
  ]
}

5.3 Polia internej správy

5.4 Podporované položky items

5.5 Limity protokolu v1

6. Priebeh komunikácie

1. Hosťovský web vytvorí jednorazový identifikátor nonce.
2. Po kliknutí používateľa otvorí https://www.pastetoprint.com/?externalImport=1&nonce=...&sourceOrigin=....
3. SDK opakovane odošle správu pasteToPrint.connect, kým sa cieľové okno nenačíta.
4. pasteToPrint odpovie správou pasteToPrint.ready.
5. SDK overí event.origin, event.source a nonce, potom odošle pasteToPrint.import.
6. pasteToPrint zobrazí používateľovi náhľad a vyžiada potvrdenie.
7. pasteToPrint odošle výsledok pasteToPrint.result.

6.1 Odpoveď po úspešnom importe

{
  type: 'pasteToPrint.result',
  version: 1,
  nonce: 'rovnaky-jednorazovy-identifikator',
  status: 'accepted'
}

Pri zrušení používateľom je hodnota status nastavená na cancelled. Pri chybe sa použije error a voliteľné pole message.

Promise vrátený funkciou PasteToPrint.import() sa vyrieši iba pri stave accepted. Stavy cancelled a error prejdú do catch. Od SDK 1.2.1 je pôvodná odpoveď dostupná aj ako error.result a stav ako error.status.

try {
  const result = await PasteToPrint.import(payload);
  console.log(result.status); // accepted
} catch (error) {
  if (error.status === 'cancelled') {
    console.log('Pouzivatel import zrusil.');
  } else {
    console.error(error.message, error.result);
  }
}

7. Bezpečnostné pravidlá

• Okno pasteToPrint otvárajte iba po priamom kliknutí používateľa. Inak ho prehliadač môže zablokovať.
• Pri postMessage vždy použite presný cieľ https://www.pastetoprint.com. Nepoužívajte *.
• Pri prijímaní odpovede overte event.origin, event.source aj nonce. Ukážkový kód to už robí.
• Neodosielajte heslá, prístupové tokeny ani iné citlivé údaje.
• Pre obrázky používajte iba data:image/.... Neposielajte vzdialené URL.
• V produkcii smerujte import iba na https://www.pastetoprint.com/, nie na jazykovú alebo SEO podstránku.
• Odporúčaná maximálna dĺžka jedného dataUrl je 1 400 000 znakov. Prijímač odmietne hodnotu nad 1 500 000 znakov.

8. Testovanie

Pred odovzdaním integrácie overte nasledujúce scenáre:

1. Po kliknutí sa otvorí nové okno pasteToPrint.
2. pasteToPrint zobrazí dialóg s náhľadom importovaného obsahu.
3. Po potvrdení sa text alebo QR kód zobrazí v editore a v náhľade tlače.
4. Pri zrušení sa obsah dokumentu nezmení.
5. Ak používateľ zablokuje vyskakovacie okná, hosťovský web zobrazí zrozumiteľnú chybu.
6. Príliš veľký obrázok je odmietnutý so zrozumiteľnou správou.
7. Funkčnosť je overená aspoň v aktuálnych verziách Chrome, Edge, Firefox a Safari.

8.1 Minimálny test integrácie

Pri teste hostiteľského webu proti produkcii použite presnú kanonickú adresu. Pri lokálnom teste prijímača nastavte targetUrl na lokálny súbor index.html obsluhovaný cez http://localhost alebo http://127.0.0.1. Integrácia nefunguje cez file://.

<script src="http://localhost/pasteToPrint/assets/js/import-button.js?v=1.5.0" defer></script>

<button type="button" id="localImportBtn" data-pastetoprint-button>
  Otestovať lokálny import
</button>

<script>
window.addEventListener('DOMContentLoaded', () => {
  document.getElementById('localImportBtn').addEventListener('click', async () => {
    try {
      const result = await PasteToPrint.import({
        title: 'Lokálny test',
        items: [{ kind: 'text', text: 'Testovací text' }]
      }, {
        targetUrl: 'http://localhost/pasteToPrint/index.html'
      });
      console.log(result.status);
    } catch (error) {
      if (error.status !== 'cancelled') alert(error.message);
    }
  });
});
</script>

Ukážku hostite cez lokálny HTTP server. Ak sa projekt nachádza v inom priečinku alebo na inom porte, upravte adresu SDK aj targetUrl.

9. Riešenie problémov