Skip to content

document‐generation‐lib

Jump to bottom
HlexNC edited this page May 6, 2024 · 3 revisions

1️⃣ API - Usage Guide

This document provides examples of how to use the Officegen API to create .docx documents with custom text. Future updates will include more complex document structures and styles.

Creating a Document with Text

To create a document containing simple text, send a POST request to the /api/create-document endpoint with a JSON payload containing the text.

Request

POST /api/create-document

Content-Type: application/json

{
  "elements": 
  [
    {
      "type": "title",
      "text": "Document Title"
    },
    {
      "type": "subtitle",
      "text": "Document Subtitle"
    },
    {
      "type": "paragraph",
      "text": "This is a simple paragraph."
    },
    {
      "type": "bullet",
      "items": [
        "Item 1",
        "Item 2",
        "Item 3"
      ]
    },
    {
      "type": "list",
      "items": [
        "Item 1",
        "Item 2",
        "Item 3"
      ]
    },
    {
      "type": "footnotes",
      "text": "This is document footnotes"
    }
  ],
  "styles": 
  {
    "textColor": "#000000",
    "fontFamily": 
    {
      "title": "Arial",
      "subtitle": "Times New Roman",
      "body": "Calibri"
    }
  }
}
Advanced example 
{
  "elements": [
    {
      "type": "title",
      "text": "Document Title"
    },
    {
      "type": "subtitle",
      "text": "Document Subtitle"
    },
    {
      "type": "paragraph",
      "text": "This is a simple paragraph."
    },
    {
      "type": "bullet",
      "items": [
        "Item 1",
        "Item 2",
        "Item 3"
      ]
    },
    {
      "type": "list",
      "items": [
        "Item 1",
        "Item 2",
        "Item 3"
      ]
    },
    {
      "type": "footnotes",
      "text": "This is document footnotes"
    },
    {
      "type": "codeBlock",
      "text": "function helloWorld() {\n  console.log('Hello, world!');\n}"
    },
    {
      "type": "table",
      "table": [
        [
          {
            "val": "Header 1",
            "opts": {
              "b": true,
              "color": "000000",
              "align": "center",
              "shd": {
                "fill": "92CDDC"
              }
            }
          },
          {
            "val": "Header 2",
            "opts": {
              "b": true,
              "color": "000000",
              "align": "center",
              "shd": {
                "fill": "92CDDC"
              }
            }
          }
        ],
        ["Row 1, Cell 1", "Row 1, Cell 2"],
        ["Row 2, Cell 1", "Row 2, Cell 2"]
      ],
      "tableStyle": {
        "tableColWidth": 4261,
        "tableSize": 24,
        "tableColor": "ada",
        "tableAlign": "left",
        "tableFontFamily": "Comic Sans MS"
      }
    }
  ],
  "styles": {
    "textColor": "#000000",
    "fontFamily": {
      "title": "Arial",
      "subtitle": "Times New Roman",
      "body": "Calibri"
    }
  }
}

Response

Upon successful document creation, the API will respond with a 201 status code and a JSON object containing the message and the path to the created document.

{
  "message": "Document created successfully",
  "path": "examples/document_123456789.docx"
}

Downloading the Document

Currently, the API returns the path to the created document. To download the document, you can access the file directly from the server using the provided path. Future versions of the API will include direct download links or streaming capabilities.

Error Handling

If the request fails due to missing text or other issues, the API will respond with an appropriate error message and status code.

Example Error Response

{
  "message": "Text is required"
}

Status code: 400

2️⃣ Library - Usage Guide

Introduction

The UNIC Document Generator Library is a powerful Node.js module that enables the creation of .docx documents from structured JSON inputs. Built on top of the officegen library, it offers a flexible way to generate documents with custom styles and various elements such as text, titles, subtitles, lists, bullets, and footnotes.

This guide details the setup, installation, and usage process of this NPM package within your projects.

Prerequisites

Ensure the following are installed before proceeding:

  • Node.js (v12.x or higher recommended)
  • npm (comes bundled with Node.js)

Installation

Since this package is hosted on the GitHub Packages registry associated with the UniversityOfNicosia organization, you'll need to authenticate to GitHub Packages to install the library. Configure your project to use GitHub Packages:

  1. Create or edit the .npmrc file in your project's root directory to include the following line: 
    @universityofnicosia:registry=https://npm.pkg.github.com
  2. Authenticate to GitHub Packages. You can use a personal access token (PAT) with read:packages permission. Configure the token in your global ~/.npmrc file (not the project's .npmrc to avoid committing sensitive information): 
    //npm.pkg.github.com/:_authToken=YOUR_PERSONAL_ACCESS_TOKEN
  3. Install the package using npm: 
    npm install @universityofnicosia/unic-document-gen-library --save

Setting Up Your Project

  1. Initialize a new Node.js project (if not already done) by executing npm init in your project directory and completing the setup prompts.

  2. Install the UNIC Document Gen Library using the command provided in the Installation section above.

Usage

Import the library into your Node.js application, configure your document structure and styles in JSON, and invoke the library function to create a document.

Basic Example

Here's a simple example demonstrating the library usage:

const documentLibrary = require('@universityofnicosia/unic-document-gen-library');

// Define your document structure and styles
const inputJson = {
  "elements": [
    { "type": "title", "text": "Document Title" },
    { "type": "subtitle", "text": "Subtitle Here" },
    { "type": "paragraph", "text": "This is a simple paragraph." },
    {
      "type": "list",
      "items": ["First item", "Second item", "Third item"]
    }
  ],
  "styles": {
    "fontFamily": {
      "title": "Arial",
      "body": "Calibri"
    },
    "textColor": "#000000"
  }
};

// Create the document
documentLibrary.createDocumentWithStructure(inputJson)
  .then((path) => console.log(`Document created at: ${path}`))
  .catch((error) => console.error('Error creating document:', error));
Clone this wiki locally