|
| 1 | +import {ReferenceEntityTemplateSchema} from '@shopify/generate-docs'; |
| 2 | + |
| 3 | +const data: ReferenceEntityTemplateSchema = { |
| 4 | + name: 'Embed', |
| 5 | + description: |
| 6 | + 'The `Embed` component displays a preview of printable content from a specified source URL. Use it to show users what will be printed before triggering the actual print operation.\n\n`Embed` works in conjunction with the Print API to provide complete print functionality from preview to execution.\n\nSupported document types:\n\n- **HTML documents** (`.html`, `.htm`) - Best printing experience with full CSS styling, embedded images, and complex layouts. Use for receipts, invoices, and formatted reports.\n\n- **Text files** (`.txt`, `.csv`) - Plain text with basic content and tabular data support. Use for simple receipts and data exports.\n\n- **Image files** (`.png`, `.jpg`, `.jpeg`, `.gif`, `.bmp`, `.webp`) - Common web formats with format-specific optimizations. Use for logos, charts, QR codes, and barcodes.\n\n- **PDF files** (`.pdf`) - Behavior varies by platform: prints directly on iOS/desktop, but downloads to external viewer on Android. Use for complex documents and compliance requirements.\n\n[Learn how to build a print extension in POS](/docs/apps/build/pos/build-print-extension).', |
| 7 | + isVisualComponent: true, |
| 8 | + type: 'component', |
| 9 | + thumbnail: 'embed-thumbnail.png', |
| 10 | + definitions: [ |
| 11 | + { |
| 12 | + title: 'Properties', |
| 13 | + description: |
| 14 | + 'Configure the following properties on the `Embed` component. This component must be a direct child of the Screen component.', |
| 15 | + type: 'EmbedProps', |
| 16 | + }, |
| 17 | + ], |
| 18 | + category: 'UI components', |
| 19 | + subCategory: 'Navigation and content', |
| 20 | + related: [], |
| 21 | + defaultExample: { |
| 22 | + image: 'embed-default.png', |
| 23 | + description: |
| 24 | + 'Display a preview of printable content before triggering the print operation. This example shows how to use Embed with HTML documents, PDFs, images, or text files, supporting various document formats with proper rendering for receipts, invoices, and formatted reports.', |
| 25 | + codeblock: { |
| 26 | + title: 'Preview printable content', |
| 27 | + tabs: [{code: './examples/embed.html', language: 'html'}], |
| 28 | + }, |
| 29 | + }, |
| 30 | + |
| 31 | + subSections: [ |
| 32 | + { |
| 33 | + type: 'Generic', |
| 34 | + anchorLink: 'best-practices', |
| 35 | + title: 'Best practices', |
| 36 | + sectionContent: `\n- **Design print-optimized content:** Structure your printable content with print-specific CSS media queries, appropriate page breaks, and formatting that works well on physical paper. Consider printer capabilities and paper sizes commonly used in POS environments.\n- **Implement proper error handling:** Handle cases where the source URL is unavailable, the document format is unsupported, or network issues prevent content loading. Provide clear feedback to users when preview or printing fails.\n- **Consider platform-specific limitations:** Be aware that PDF files on Android devices require external applications for printing. Design your workflow to handle this gracefully, potentially offering alternative formats or clear instructions for Android users.\n- **Optimize source URL management:** Use relative paths when possible for internal app resources to simplify URL management and improve performance. Reserve full URLs for external resources or when you need complete control over the endpoint.\n- **Provide clear print workflows:** Combine \`Embed\` with appropriate UI controls like print buttons, allowing users to review content before committing to print. Consider implementing print confirmation dialogs for important or expensive print operations.\n`, |
| 37 | + }, |
| 38 | + { |
| 39 | + type: 'Generic', |
| 40 | + anchorLink: 'limitations', |
| 41 | + title: 'Limitations', |
| 42 | + sectionContent: `\n- \`Embed\` must be a direct child of the \`Screen\` component and can't be nested inside any other component—this structural requirement ensures proper preview rendering and print functionality.\n- The component requires network access to fetch content from the specified source URL—offline functionality isn't supported for remote content.\n- Content is displayed as-is from the source—real-time content modification or editing within the preview isn't supported.\n- PDF printing on Android devices requires external applications—the component can't handle PDF printing natively on all platforms, which may affect user experience consistency across different POS devices.\n`, |
| 43 | + }, |
| 44 | + ], |
| 45 | +}; |
| 46 | + |
| 47 | +export default data; |
0 commit comments