diff --git a/docs/SDKs/generate-docx-pptx-javascript.md b/docs/SDKs/generate-docx-pptx-javascript.md new file mode 100644 index 00000000..18b95516 --- /dev/null +++ b/docs/SDKs/generate-docx-pptx-javascript.md @@ -0,0 +1,172 @@ +--- +title: "JavaScript PPTX SDK: Generate PPTX and DOCX" +sidebar_position: 1 +sidebar_label: JavaScript +description: "Copy-paste Node.js example for the TurboDocx JavaScript SDK: fill a Word or PowerPoint template from JSON, then download the DOCX or PPTX and a PDF." +keywords: + - javascript pptx sdk + - javascript docx sdk + - node.js docx generation + - generate pptx javascript + - generate docx from json javascript + - turbodocx javascript example +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Generate DOCX and PPTX Files in JavaScript + +This example uses the official JavaScript SDK, `@turbodocx/sdk`, from a plain Node.js script. It reads a JSON file, fills a Word (.docx) or PowerPoint (.pptx) template that you uploaded to TurboDocx, and saves two files: the editable document and a PDF. + +The template keeps its fonts, styles and layout. TurboDocx does the rendering on its own servers, so you do not need Microsoft Office, LibreOffice or a document library on your machine. + +## Before you start + +- **A template.** Create the document in Word or PowerPoint and type a placeholder in curly braces wherever data should go, for example `{ClientName}`. Upload it under **Templates** in TurboDocx. +- **The template ID.** Turn on [Developer Mode](/docs/SDKs/developer-mode), open the template and click **Code**. The code panel shows the template ID and the template's real placeholder names. +- **An API key and your organization ID.** See [Get your credentials](/docs/SDKs#1-get-your-credentials). +- **Node.js 18 or later.** + +:::note Plans +Every plan can generate documents and download the PDF. Downloading the editable DOCX or PPTX file, and using PowerPoint templates, need a paid plan. On the free plan, remove the source-file download from the script and keep the PDF. +::: + +## 1. Install the SDK + + + + +```bash +npm install @turbodocx/sdk +``` + + + + +```bash +yarn add @turbodocx/sdk +``` + + + + +```bash +pnpm add @turbodocx/sdk +``` + + + + +## 2. Set your credentials + +Document generation needs only your API key, your organization ID and the template ID: + +```bash +export TURBODOCX_API_KEY=your_api_key +export TURBODOCX_ORG_ID=your_org_id +export TURBODOCX_TEMPLATE_ID=your_template_id +``` + +## 3. Add your data + +Save the data as `data.json` next to the script. Each top-level key matches a placeholder in the template, so `ClientName` fills `{ClientName}`. + +```json +{ + "ClientName": "Northwind Health", + "ProposalDate": "November 3, 2026", + "TotalPrice": "$48,000", + "ProjectLead": "Priya Shah", + "Scope": "" +} +``` + +Each placeholder takes one value, so keep the JSON flat. Plain values are sent as `text`. `Scope` holds an HTML list, so the script sends it as `html` and TurboDocx renders it as a real bulleted list in the document. + +## 4. Generate the document + +Save this as `generate.js`: + +```javascript +// generate.js +const fs = require("node:fs"); +const { Deliverable } = require("@turbodocx/sdk"); + +Deliverable.configure({ + apiKey: process.env.TURBODOCX_API_KEY, + orgId: process.env.TURBODOCX_ORG_ID, +}); + +// Use "pptx" when your template is a PowerPoint file +const SOURCE_EXT = "docx"; +// Keys whose values are HTML (lists, tables, bold text) +const HTML_KEYS = new Set(["Scope"]); + +async function main() { + const data = JSON.parse(fs.readFileSync("data.json", "utf8")); + + // One variable per key: "ClientName" fills {ClientName} in the template + const variables = Object.entries(data).map(([key, value]) => ({ + placeholder: `{${key}}`, + text: String(value), + mimeType: HTML_KEYS.has(key) ? "html" : "text", + })); + + const result = await Deliverable.generateDeliverable({ + name: `Proposal - ${data.ClientName}`, + templateId: process.env.TURBODOCX_TEMPLATE_ID, + variables, + }); + const deliverableId = result.results.deliverable.id; + console.log("Generated deliverable", deliverableId); + + // The editable file, in the same format as the template + const source = await Deliverable.downloadSourceFile(deliverableId); + fs.writeFileSync(`proposal.${SOURCE_EXT}`, Buffer.from(source)); + + // The PDF that TurboDocx renders alongside it + const pdf = await Deliverable.downloadPDF(deliverableId); + fs.writeFileSync("proposal.pdf", Buffer.from(pdf)); +} + +main().catch((err) => { + console.error(err); + process.exit(1); +}); +``` + +The script uses CommonJS `require` so it runs as-is with `node`. In an ES module project, `import { Deliverable } from "@turbodocx/sdk"` works too. Using TypeScript? See the [TypeScript example](./generate-docx-pptx-typescript.md). + +## 5. Run it + +```bash +node generate.js +``` + +The script prints the new deliverable ID and writes `proposal.docx` (or `proposal.pptx`) and `proposal.pdf` to the current folder. The generated document also appears under **Deliverables** in TurboDocx. + +`generateDeliverable` returns the new document under `result.results.deliverable`. Both download methods return an `ArrayBuffer`, which the script wraps in a `Buffer` before writing it to disk. + +## Other kinds of values + +The `mimeType` of each variable tells TurboDocx how to insert the value: + +| `mimeType` | Use it for | +| :-- | :-- | +| `text` | Plain values such as names, dates and amounts | +| `html` | Formatted content such as lists, tables and bold text | +| `markdown` | Content you already have as Markdown | +| `image` | An image URL or base64 image data | + +For repeating content, such as one table row per line item, use `variableStack` on a variable instead of flattening the rows yourself. See [Variable Types](/docs/SDKs/deliverable#variable-types) for examples of each. + +## Next steps + +- [Deliverable SDK reference](/docs/SDKs/deliverable?language=js): every method, option and error type, open on the JavaScript tab. +- [Send the generated document for signature](/docs/SDKs/turbosign#3-turbodocx-deliverable-id): pass the deliverable ID to TurboSign with the same API key. +- [Deliverable API](/docs/API/Deliverable-API): the REST endpoints behind the SDK, with cURL examples. +- [JavaScript SDK setup](/docs/SDKs/javascript): installation and configuration options. +- [Generate DOCX from JSON with JavaScript](https://www.turbodocx.com/guides/generate-docx-from-json-with-javascript): a longer walkthrough on turbodocx.com, with answers to common questions. + +The same example is also available in [TypeScript](./generate-docx-pptx-typescript.md), [Python](./generate-docx-pptx-python.md), [PHP](./generate-docx-pptx-php.md), [Ruby](./generate-docx-pptx-ruby.md). diff --git a/docs/SDKs/generate-docx-pptx-php.md b/docs/SDKs/generate-docx-pptx-php.md new file mode 100644 index 00000000..3a9136f7 --- /dev/null +++ b/docs/SDKs/generate-docx-pptx-php.md @@ -0,0 +1,143 @@ +--- +title: "PHP DOCX SDK Example: Word and PowerPoint" +sidebar_position: 4 +sidebar_label: PHP +description: "Copy-paste PHP example for the TurboDocx SDK: fill a Word or PowerPoint template from JSON with Composer, then save the DOCX or PPTX and a PDF." +keywords: + - php docx sdk + - php pptx sdk + - php generate word document + - php docx generation + - generate docx from json php + - turbodocx php example +--- + +# PHP DOCX and PPTX SDK Example + +This example uses the official PHP SDK, `turbodocx/sdk`, from a command-line script. It reads a JSON file, fills a Word (.docx) or PowerPoint (.pptx) template that you uploaded to TurboDocx, and writes the editable document and a PDF. The same calls work inside a Laravel or Symfony controller. + +The template keeps its fonts, styles and layout. TurboDocx does the rendering on its own servers, so you do not need Microsoft Office, LibreOffice or a document library on your machine. + +## Before you start + +- **A template.** Create the document in Word or PowerPoint and type a placeholder in curly braces wherever data should go, for example `{ClientName}`. Upload it under **Templates** in TurboDocx. +- **The template ID.** Turn on [Developer Mode](/docs/SDKs/developer-mode), open the template and click **Code**. The code panel shows the template ID and the template's real placeholder names. +- **An API key and your organization ID.** See [Get your credentials](/docs/SDKs#1-get-your-credentials). +- **PHP 8.1 or later with the `json` and `fileinfo` extensions, and Composer.** + +:::note Plans +Every plan can generate documents and download the PDF. Downloading the editable DOCX or PPTX file, and using PowerPoint templates, need a paid plan. On the free plan, remove the source-file download from the script and keep the PDF. +::: + +## 1. Install the SDK + +```bash +composer require turbodocx/sdk +``` + +## 2. Set your credentials + +Document generation needs only your API key, your organization ID and the template ID: + +```bash +export TURBODOCX_API_KEY=your_api_key +export TURBODOCX_ORG_ID=your_org_id +export TURBODOCX_TEMPLATE_ID=your_template_id +``` + +## 3. Add your data + +Save the data as `data.json` next to the script. Each top-level key matches a placeholder in the template, so `ClientName` fills `{ClientName}`. + +```json +{ + "ClientName": "Northwind Health", + "ProposalDate": "November 3, 2026", + "TotalPrice": "$48,000", + "ProjectLead": "Priya Shah", + "Scope": "" +} +``` + +Each placeholder takes one value, so keep the JSON flat. Plain values are sent as `text`. `Scope` holds an HTML list, so the script sends it as `html` and TurboDocx renders it as a real bulleted list in the document. + +## 4. Generate the document + +Save this as `generate.php`: + +```php + $value) { + $variables[] = [ + 'placeholder' => '{' . $key . '}', + 'text' => (string) $value, + 'mimeType' => in_array($key, HTML_KEYS, true) ? 'html' : 'text', + ]; +} + +$result = Deliverable::generateDeliverable([ + 'name' => 'Proposal - ' . $data['ClientName'], + 'templateId' => getenv('TURBODOCX_TEMPLATE_ID'), + 'variables' => $variables, +]); +$deliverableId = $result['results']['deliverable']['id']; +echo "Generated deliverable {$deliverableId}\n"; + +// The editable file, in the same format as the template +file_put_contents('proposal.' . SOURCE_EXT, Deliverable::downloadSourceFile($deliverableId)); + +// The PDF that TurboDocx renders alongside it +file_put_contents('proposal.pdf', Deliverable::downloadPDF($deliverableId)); +``` + +`DeliverableConfig::fromEnvironment()` reads `TURBODOCX_API_KEY` and `TURBODOCX_ORG_ID`. In a framework, you can build the config from your own settings instead: `new DeliverableConfig(apiKey: ..., orgId: ...)`. + +## 5. Run it + +```bash +php generate.php +``` + +The script prints the new deliverable ID and writes `proposal.docx` (or `proposal.pptx`) and `proposal.pdf` to the current folder. The generated document also appears under **Deliverables** in TurboDocx. + +`generateDeliverable` returns an array; the new document is at `$result['results']['deliverable']`. Both download methods return the raw file contents as a string, ready for `file_put_contents`. + +## Other kinds of values + +The `mimeType` of each variable tells TurboDocx how to insert the value: + +| `mimeType` | Use it for | +| :-- | :-- | +| `text` | Plain values such as names, dates and amounts | +| `html` | Formatted content such as lists, tables and bold text | +| `markdown` | Content you already have as Markdown | +| `image` | An image URL or base64 image data | + +For repeating content, such as one table row per line item, use `variableStack` on a variable instead of flattening the rows yourself. See [Variable Types](/docs/SDKs/deliverable#variable-types) for examples of each. + +## Next steps + +- [Deliverable SDK reference](/docs/SDKs/deliverable?language=php): every method, option and error type, open on the PHP tab. +- [Send the generated document for signature](/docs/SDKs/turbosign#3-turbodocx-deliverable-id): pass the deliverable ID to TurboSign with the same API key. +- [Deliverable API](/docs/API/Deliverable-API): the REST endpoints behind the SDK, with cURL examples. +- [PHP SDK setup](/docs/SDKs/php): installation and configuration options. + +The same example is also available in [JavaScript](./generate-docx-pptx-javascript.md), [TypeScript](./generate-docx-pptx-typescript.md), [Python](./generate-docx-pptx-python.md), [Ruby](./generate-docx-pptx-ruby.md). diff --git a/docs/SDKs/generate-docx-pptx-python.md b/docs/SDKs/generate-docx-pptx-python.md new file mode 100644 index 00000000..13a59216 --- /dev/null +++ b/docs/SDKs/generate-docx-pptx-python.md @@ -0,0 +1,172 @@ +--- +title: "Python DOCX Generation Example: Word and PPTX" +sidebar_position: 3 +sidebar_label: Python +description: "Copy-paste Python example for the TurboDocx SDK: fill a Word or PowerPoint template from JSON with async/await, then save the DOCX or PPTX and a PDF." +keywords: + - python docx generation + - python pptx generation + - generate docx python + - python word document from json + - python docx sdk + - turbodocx python example +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Python DOCX and PPTX Generation Example + +This example uses the official Python SDK, `turbodocx-sdk`. It reads a JSON file, fills a Word (.docx) or PowerPoint (.pptx) template that you uploaded to TurboDocx, and writes the editable document and a PDF. Unlike libraries such as python-docx, you do not build the document element by element in code: the layout lives in the template, and your script only supplies the data. + +The template keeps its fonts, styles and layout. TurboDocx does the rendering on its own servers, so you do not need Microsoft Office, LibreOffice or a document library on your machine. + +## Before you start + +- **A template.** Create the document in Word or PowerPoint and type a placeholder in curly braces wherever data should go, for example `{ClientName}`. Upload it under **Templates** in TurboDocx. +- **The template ID.** Turn on [Developer Mode](/docs/SDKs/developer-mode), open the template and click **Code**. The code panel shows the template ID and the template's real placeholder names. +- **An API key and your organization ID.** See [Get your credentials](/docs/SDKs#1-get-your-credentials). +- **Python 3.9 or later.** + +:::note Plans +Every plan can generate documents and download the PDF. Downloading the editable DOCX or PPTX file, and using PowerPoint templates, need a paid plan. On the free plan, remove the source-file download from the script and keep the PDF. +::: + +## 1. Install the SDK + + + + +```bash +pip install turbodocx-sdk +``` + + + + +```bash +poetry add turbodocx-sdk +``` + + + + +## 2. Set your credentials + +Document generation needs only your API key, your organization ID and the template ID: + +```bash +export TURBODOCX_API_KEY=your_api_key +export TURBODOCX_ORG_ID=your_org_id +export TURBODOCX_TEMPLATE_ID=your_template_id +``` + +## 3. Add your data + +Save the data as `data.json` next to the script. Each top-level key matches a placeholder in the template, so `ClientName` fills `{ClientName}`. + +```json +{ + "ClientName": "Northwind Health", + "ProposalDate": "November 3, 2026", + "TotalPrice": "$48,000", + "ProjectLead": "Priya Shah", + "Scope": "" +} +``` + +Each placeholder takes one value, so keep the JSON flat. Plain values are sent as `text`. `Scope` holds an HTML list, so the script sends it as `html` and TurboDocx renders it as a real bulleted list in the document. + +## 4. Generate the document + +Save this as `generate.py`: + +```python +# generate.py +import asyncio +import json +import os + +from turbodocx_sdk import Deliverable + +# Use "pptx" when your template is a PowerPoint file +SOURCE_EXT = "docx" +# Keys whose values are HTML (lists, tables, bold text) +HTML_KEYS = {"Scope"} + + +async def main(): + Deliverable.configure( + api_key=os.environ["TURBODOCX_API_KEY"], + org_id=os.environ["TURBODOCX_ORG_ID"], + ) + + with open("data.json", encoding="utf-8") as f: + data = json.load(f) + + # One variable per key: "ClientName" fills {ClientName} in the template + variables = [ + { + "placeholder": "{" + key + "}", + "text": str(value), + "mimeType": "html" if key in HTML_KEYS else "text", + } + for key, value in data.items() + ] + + result = await Deliverable.generate_deliverable( + name=f"Proposal - {data['ClientName']}", + template_id=os.environ["TURBODOCX_TEMPLATE_ID"], + variables=variables, + ) + deliverable_id = result["results"]["deliverable"]["id"] + print("Generated deliverable", deliverable_id) + + # The editable file, in the same format as the template + source = await Deliverable.download_source_file(deliverable_id) + with open(f"proposal.{SOURCE_EXT}", "wb") as f: + f.write(source) + + # The PDF that TurboDocx renders alongside it + pdf = await Deliverable.download_pdf(deliverable_id) + with open("proposal.pdf", "wb") as f: + f.write(pdf) + + +asyncio.run(main()) +``` + +The SDK is async, so the script runs inside `asyncio.run()`. In an async web framework such as FastAPI, `await` the same calls inside your request handler instead. Request keys inside each variable (`placeholder`, `text`, `mimeType`) are camelCase because they go to the API as written; the method arguments (`template_id`, `org_id`) are snake_case. + +## 5. Run it + +```bash +python generate.py +``` + +The script prints the new deliverable ID and writes `proposal.docx` (or `proposal.pptx`) and `proposal.pdf` to the current folder. The generated document also appears under **Deliverables** in TurboDocx. + +`generate_deliverable` returns a dict; the new document is at `result["results"]["deliverable"]`. Both download methods return `bytes`, so open the output files in binary mode (`"wb"`). + +## Other kinds of values + +The `mimeType` of each variable tells TurboDocx how to insert the value: + +| `mimeType` | Use it for | +| :-- | :-- | +| `text` | Plain values such as names, dates and amounts | +| `html` | Formatted content such as lists, tables and bold text | +| `markdown` | Content you already have as Markdown | +| `image` | An image URL or base64 image data | + +For repeating content, such as one table row per line item, use `variableStack` on a variable instead of flattening the rows yourself. See [Variable Types](/docs/SDKs/deliverable#variable-types) for examples of each. + +## Next steps + +- [Deliverable SDK reference](/docs/SDKs/deliverable?language=python): every method, option and error type, open on the Python tab. +- [Send the generated document for signature](/docs/SDKs/turbosign#3-turbodocx-deliverable-id): pass the deliverable ID to TurboSign with the same API key. +- [Deliverable API](/docs/API/Deliverable-API): the REST endpoints behind the SDK, with cURL examples. +- [Python SDK setup](/docs/SDKs/python): installation and configuration options. +- [Generate DOCX from JSON with Python](https://www.turbodocx.com/guides/generate-docx-from-json-with-python): a longer walkthrough on turbodocx.com, with answers to common questions. + +The same example is also available in [JavaScript](./generate-docx-pptx-javascript.md), [TypeScript](./generate-docx-pptx-typescript.md), [PHP](./generate-docx-pptx-php.md), [Ruby](./generate-docx-pptx-ruby.md). diff --git a/docs/SDKs/generate-docx-pptx-ruby.md b/docs/SDKs/generate-docx-pptx-ruby.md new file mode 100644 index 00000000..78902d3e --- /dev/null +++ b/docs/SDKs/generate-docx-pptx-ruby.md @@ -0,0 +1,159 @@ +--- +title: "Ruby DOCX Example: Word and PowerPoint" +sidebar_position: 5 +sidebar_label: Ruby +description: "Copy-paste Ruby example for the TurboDocx gem: fill a Word or PowerPoint template from JSON, then save the DOCX or PPTX and a PDF, in plain Ruby or Rails." +keywords: + - ruby docx example + - ruby pptx sdk + - ruby generate word document + - rails docx generation + - generate docx from json ruby + - turbodocx ruby example +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# Ruby DOCX and PPTX Example + +This example uses the official Ruby gem, `turbodocx-sdk`. It reads a JSON file, fills a Word (.docx) or PowerPoint (.pptx) template that you uploaded to TurboDocx, and writes the editable document and a PDF. In a Rails app, the same calls fit in a job or a service object. + +The template keeps its fonts, styles and layout. TurboDocx does the rendering on its own servers, so you do not need Microsoft Office, LibreOffice or a document library on your machine. + +## Before you start + +- **A template.** Create the document in Word or PowerPoint and type a placeholder in curly braces wherever data should go, for example `{ClientName}`. Upload it under **Templates** in TurboDocx. +- **The template ID.** Turn on [Developer Mode](/docs/SDKs/developer-mode), open the template and click **Code**. The code panel shows the template ID and the template's real placeholder names. +- **An API key and your organization ID.** See [Get your credentials](/docs/SDKs#1-get-your-credentials). +- **Ruby 2.7 or later (the gem has no runtime dependencies).** + +:::note Plans +Every plan can generate documents and download the PDF. Downloading the editable DOCX or PPTX file, and using PowerPoint templates, need a paid plan. On the free plan, remove the source-file download from the script and keep the PDF. +::: + +## 1. Install the SDK + + + + +```bash +gem install turbodocx-sdk +``` + + + + +```bash +bundle add turbodocx-sdk +``` + + + + +## 2. Set your credentials + +Document generation needs only your API key, your organization ID and the template ID: + +```bash +export TURBODOCX_API_KEY=your_api_key +export TURBODOCX_ORG_ID=your_org_id +export TURBODOCX_TEMPLATE_ID=your_template_id +``` + +## 3. Add your data + +Save the data as `data.json` next to the script. Each top-level key matches a placeholder in the template, so `ClientName` fills `{ClientName}`. + +```json +{ + "ClientName": "Northwind Health", + "ProposalDate": "November 3, 2026", + "TotalPrice": "$48,000", + "ProjectLead": "Priya Shah", + "Scope": "" +} +``` + +Each placeholder takes one value, so keep the JSON flat. Plain values are sent as `text`. `Scope` holds an HTML list, so the script sends it as `html` and TurboDocx renders it as a real bulleted list in the document. + +## 4. Generate the document + +Save this as `generate.rb`: + +```ruby +# generate.rb +require "json" +require "turbodocx_sdk" + +TurboDocxSdk::Deliverable.configure( + api_key: ENV.fetch("TURBODOCX_API_KEY"), + org_id: ENV.fetch("TURBODOCX_ORG_ID") +) + +# Use "pptx" when your template is a PowerPoint file +SOURCE_EXT = "docx" +# Keys whose values are HTML (lists, tables, bold text) +HTML_KEYS = ["Scope"].freeze + +data = JSON.parse(File.read("data.json")) + +# One variable per key: "ClientName" fills {ClientName} in the template. +# Request keys are camelCase strings; the SDK sends them to the API as written. +variables = data.map do |key, value| + { + "placeholder" => "{#{key}}", + "text" => value.to_s, + "mimeType" => HTML_KEYS.include?(key) ? "html" : "text" + } +end + +result = TurboDocxSdk::Deliverable.generate_deliverable( + "name" => "Proposal - #{data['ClientName']}", + "templateId" => ENV.fetch("TURBODOCX_TEMPLATE_ID"), + "variables" => variables +) +deliverable_id = result["results"]["deliverable"]["id"] +puts "Generated deliverable #{deliverable_id}" + +# The editable file, in the same format as the template +File.binwrite("proposal.#{SOURCE_EXT}", TurboDocxSdk::Deliverable.download_source_file(deliverable_id)) + +# The PDF that TurboDocx renders alongside it +File.binwrite("proposal.pdf", TurboDocxSdk::Deliverable.download_pdf(deliverable_id)) +``` + +The gem is synchronous and uses only the standard library's `net/http`. Request hashes use camelCase string keys (`"templateId"`, `"mimeType"`) because the gem sends them to the API as written; only the `configure` keyword arguments are snake_case. + +## 5. Run it + +```bash +ruby generate.rb +``` + +The script prints the new deliverable ID and writes `proposal.docx` (or `proposal.pptx`) and `proposal.pdf` to the current folder. The generated document also appears under **Deliverables** in TurboDocx. + +`generate_deliverable` returns a hash; the new document is at `result["results"]["deliverable"]`. Both download methods return the raw bytes, so write them with `File.binwrite`. + +## Other kinds of values + +The `mimeType` of each variable tells TurboDocx how to insert the value: + +| `mimeType` | Use it for | +| :-- | :-- | +| `text` | Plain values such as names, dates and amounts | +| `html` | Formatted content such as lists, tables and bold text | +| `markdown` | Content you already have as Markdown | +| `image` | An image URL or base64 image data | + +For repeating content, such as one table row per line item, use `variableStack` on a variable instead of flattening the rows yourself. See [Variable Types](/docs/SDKs/deliverable#variable-types) for examples of each. + +## Next steps + +- [Deliverable SDK reference](/docs/SDKs/deliverable?language=ruby): every method, option and error type, open on the Ruby tab. +- [Send the generated document for signature](/docs/SDKs/turbosign#3-turbodocx-deliverable-id): pass the deliverable ID to TurboSign with the same API key. +- [Deliverable API](/docs/API/Deliverable-API): the REST endpoints behind the SDK, with cURL examples. +- [Ruby SDK setup](/docs/SDKs/ruby): installation and configuration options. +- [Generate DOCX from JSON with Ruby](https://www.turbodocx.com/guides/generate-docx-from-json-with-ruby): a longer walkthrough on turbodocx.com, with answers to common questions. + +The same example is also available in [JavaScript](./generate-docx-pptx-javascript.md), [TypeScript](./generate-docx-pptx-typescript.md), [Python](./generate-docx-pptx-python.md), [PHP](./generate-docx-pptx-php.md). diff --git a/docs/SDKs/generate-docx-pptx-typescript.md b/docs/SDKs/generate-docx-pptx-typescript.md new file mode 100644 index 00000000..641f66d8 --- /dev/null +++ b/docs/SDKs/generate-docx-pptx-typescript.md @@ -0,0 +1,190 @@ +--- +title: "TypeScript DOCX Integration Example" +sidebar_position: 2 +sidebar_label: TypeScript +description: "TypeScript example for the TurboDocx SDK: map JSON to template variables, generate a Word or PowerPoint file, and download the DOCX or PPTX and a PDF." +keywords: + - typescript docx integration + - typescript pptx sdk + - typescript docx generation + - generate docx typescript + - node.js typescript document generation + - turbodocx typescript example +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +# TypeScript DOCX and PPTX Integration Example + +The TurboDocx SDK ships its own TypeScript types, so you get autocomplete and compile-time checks for every request. This example defines an interface for your JSON, turns it into typed `DeliverableVariable` objects, fills a Word (.docx) or PowerPoint (.pptx) template, and saves the editable document and a PDF. + +The template keeps its fonts, styles and layout. TurboDocx does the rendering on its own servers, so you do not need Microsoft Office, LibreOffice or a document library on your machine. + +## Before you start + +- **A template.** Create the document in Word or PowerPoint and type a placeholder in curly braces wherever data should go, for example `{ClientName}`. Upload it under **Templates** in TurboDocx. +- **The template ID.** Turn on [Developer Mode](/docs/SDKs/developer-mode), open the template and click **Code**. The code panel shows the template ID and the template's real placeholder names. +- **An API key and your organization ID.** See [Get your credentials](/docs/SDKs#1-get-your-credentials). +- **Node.js 18 or later.** The install step below adds TypeScript and the Node.js type definitions. + +:::note Plans +Every plan can generate documents and download the PDF. Downloading the editable DOCX or PPTX file, and using PowerPoint templates, need a paid plan. On the free plan, remove the source-file download from the script and keep the PDF. +::: + +## 1. Install the SDK + + + + +```bash +npm install @turbodocx/sdk +npm install --save-dev typescript @types/node +``` + + + + +```bash +yarn add @turbodocx/sdk +yarn add --dev typescript @types/node +``` + + + + +```bash +pnpm add @turbodocx/sdk +pnpm add --save-dev typescript @types/node +``` + + + + +## 2. Set your credentials + +Document generation needs only your API key, your organization ID and the template ID: + +```bash +export TURBODOCX_API_KEY=your_api_key +export TURBODOCX_ORG_ID=your_org_id +export TURBODOCX_TEMPLATE_ID=your_template_id +``` + +## 3. Add your data + +Save the data as `data.json` next to the script. Each top-level key matches a placeholder in the template, so `ClientName` fills `{ClientName}`. + +```json +{ + "ClientName": "Northwind Health", + "ProposalDate": "November 3, 2026", + "TotalPrice": "$48,000", + "ProjectLead": "Priya Shah", + "Scope": "" +} +``` + +Each placeholder takes one value, so keep the JSON flat. Plain values are sent as `text`. `Scope` holds an HTML list, so the script sends it as `html` and TurboDocx renders it as a real bulleted list in the document. + +## 4. Generate the document + +Save this as `generate.ts`: + +```typescript +// generate.ts +import { readFile, writeFile } from "node:fs/promises"; +import { Deliverable } from "@turbodocx/sdk"; +import type { DeliverableVariable } from "@turbodocx/sdk"; + +// The shape of your JSON. Each key matches a {placeholder} in the template. +interface ProposalData { + ClientName: string; + ProposalDate: string; + TotalPrice: string; + ProjectLead: string; + Scope: string; // HTML +} + +// Use "pptx" when your template is a PowerPoint file +const SOURCE_EXT: "docx" | "pptx" = "docx"; +const HTML_KEYS = new Set(["Scope"]); + +function requireEnv(name: string): string { + const value = process.env[name]; + if (!value) throw new Error(`Set the ${name} environment variable`); + return value; +} + +function toVariables(data: ProposalData): DeliverableVariable[] { + return (Object.keys(data) as (keyof ProposalData)[]).map((key) => ({ + placeholder: `{${key}}`, + text: data[key], + mimeType: HTML_KEYS.has(key) ? "html" : "text", + })); +} + +async function main(): Promise { + Deliverable.configure({ + apiKey: requireEnv("TURBODOCX_API_KEY"), + orgId: requireEnv("TURBODOCX_ORG_ID"), + }); + + const data = JSON.parse(await readFile("data.json", "utf8")) as ProposalData; + + const result = await Deliverable.generateDeliverable({ + name: `Proposal - ${data.ClientName}`, + templateId: requireEnv("TURBODOCX_TEMPLATE_ID"), + variables: toVariables(data), + }); + const deliverableId = result.results.deliverable.id; + console.log("Generated deliverable", deliverableId); + + const source = await Deliverable.downloadSourceFile(deliverableId); + await writeFile(`proposal.${SOURCE_EXT}`, Buffer.from(source)); + + const pdf = await Deliverable.downloadPDF(deliverableId); + await writeFile("proposal.pdf", Buffer.from(pdf)); +} + +main().catch((err) => { + console.error(err); + process.exit(1); +}); +``` + +`requireEnv` fails fast with a clear message when a variable is missing, and it also satisfies the compiler: `templateId` is a required `string`, so `process.env.TURBODOCX_TEMPLATE_ID` on its own (typed `string | undefined`) does not compile under `strict`. If your project already has a `tsconfig.json`, run the file with your usual build instead of the one-off `tsc` command. + +## 5. Run it + +```bash +npx tsc generate.ts --target es2022 --module commonjs --strict --types node +node generate.js +``` + +The script prints the new deliverable ID and writes `proposal.docx` (or `proposal.pptx`) and `proposal.pdf` to the current folder. The generated document also appears under **Deliverables** in TurboDocx. + +`generateDeliverable` returns a `CreateDeliverableResponse`; the new document is at `result.results.deliverable`. Both download methods return an `ArrayBuffer`. + +## Other kinds of values + +The `mimeType` of each variable tells TurboDocx how to insert the value: + +| `mimeType` | Use it for | +| :-- | :-- | +| `text` | Plain values such as names, dates and amounts | +| `html` | Formatted content such as lists, tables and bold text | +| `markdown` | Content you already have as Markdown | +| `image` | An image URL or base64 image data | + +For repeating content, such as one table row per line item, use `variableStack` on a variable instead of flattening the rows yourself. See [Variable Types](/docs/SDKs/deliverable#variable-types) for examples of each. + +## Next steps + +- [Deliverable SDK reference](/docs/SDKs/deliverable?language=js): every method, option and error type, open on the JavaScript / TypeScript tab. +- [Send the generated document for signature](/docs/SDKs/turbosign#3-turbodocx-deliverable-id): pass the deliverable ID to TurboSign with the same API key. +- [Deliverable API](/docs/API/Deliverable-API): the REST endpoints behind the SDK, with cURL examples. +- [JavaScript / TypeScript SDK setup](/docs/SDKs/javascript): installation and configuration options. +- [Generate DOCX from JSON with TypeScript](https://www.turbodocx.com/guides/generate-docx-from-json-with-typescript): a longer walkthrough on turbodocx.com, with answers to common questions. + +The same example is also available in [JavaScript](./generate-docx-pptx-javascript.md), [Python](./generate-docx-pptx-python.md), [PHP](./generate-docx-pptx-php.md), [Ruby](./generate-docx-pptx-ruby.md). diff --git a/docs/SDKs/index.md b/docs/SDKs/index.md index 70565a27..8987f209 100644 --- a/docs/SDKs/index.md +++ b/docs/SDKs/index.md @@ -86,6 +86,16 @@ Generate documents from templates with dynamic variable injection, download sour | **Java** | `com.turbodocx:turbodocx-sdk` | [Maven Central](https://search.maven.org/artifact/com.turbodocx/turbodocx-sdk) | [Docs](/docs/SDKs/deliverable?language=java) [GitHub](https://github.com/TurboDocx/SDK/tree/main/packages/java-sdk) | | **Ruby** | `turbodocx-sdk` | `gem install turbodocx-sdk` | [Docs](/docs/SDKs/deliverable?language=ruby) [GitHub](https://github.com/TurboDocx/SDK/tree/main/packages/ruby-sdk) | +### Generate DOCX / PPTX examples + +Complete, copy-paste scripts that fill a Word or PowerPoint template from JSON and save the DOCX or PPTX and a PDF: + +- [JavaScript (Node.js)](./generate-docx-pptx-javascript.md) +- [TypeScript](./generate-docx-pptx-typescript.md) +- [Python](./generate-docx-pptx-python.md) +- [PHP](./generate-docx-pptx-php.md) +- [Ruby](./generate-docx-pptx-ruby.md) + ## TurboQuote SDKs Build sales quotes and proposals programmatically: quotes and line items, a product/bundle catalog, price books, companies/contacts, and quote templates. diff --git a/sidebars.js b/sidebars.js index 7f867d4a..64dfc2fd 100644 --- a/sidebars.js +++ b/sidebars.js @@ -200,6 +200,38 @@ const sidebars = { }, ], }, + { + type: 'category', + label: 'Generate DOCX / PPTX examples', + collapsed: true, + items: [ + { + type: 'doc', + id: 'SDKs/generate-docx-pptx-javascript', + label: 'JavaScript', + }, + { + type: 'doc', + id: 'SDKs/generate-docx-pptx-typescript', + label: 'TypeScript', + }, + { + type: 'doc', + id: 'SDKs/generate-docx-pptx-python', + label: 'Python', + }, + { + type: 'doc', + id: 'SDKs/generate-docx-pptx-php', + label: 'PHP', + }, + { + type: 'doc', + id: 'SDKs/generate-docx-pptx-ruby', + label: 'Ruby', + }, + ], + }, { type: 'doc', id: 'SDKs/turbosign',