forked from HlexNC/Document-Conversion-Solutions
-
Notifications
You must be signed in to change notification settings - Fork 0
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
Merge pull request #4 from UniversityOfNicosia/feature/npm-package
Introduce NPM Package Functionality and Enhancements to Document Conversion API
- Loading branch information
Showing
10 changed files
with
360 additions
and
119 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,12 @@ | ||
{ | ||
"customizations": { | ||
"vscode": { | ||
"extensions": [ | ||
"ms-azuretools.vscode-docker", | ||
"github.vscode-github-actions", | ||
"mhutchie.git-graph" | ||
] | ||
} | ||
} | ||
} | ||
|
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,23 @@ | ||
name: Publish NPM Package | ||
|
||
on: | ||
push: | ||
branches: | ||
- main | ||
|
||
jobs: | ||
publish-npm: | ||
runs-on: ubuntu-latest | ||
steps: | ||
- uses: actions/checkout@v2 | ||
- uses: actions/setup-node@v2 | ||
with: | ||
node-version: '14' | ||
registry-url: 'https://npm.pkg.github.com' | ||
scope: '@universityofnicosia' | ||
- run: npm install | ||
working-directory: officegen-api/ | ||
- run: npm publish | ||
working-directory: officegen-api/ | ||
env: | ||
NODE_AUTH_TOKEN: ${{secrets.GITHUB_TOKEN}} |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,51 +1,89 @@ | ||
# Officegen API | ||
# Officegen API and Library for Document Conversion | ||
|
||
This directory contains a Node.js API for document conversion using the officegen library. The API supports creating `.docx` documents with structured elements and custom styles. | ||
The Officegen API and Library offer a powerful way to generate `.docx` documents from structured JSON inputs. This guide provides an overview of both the API and the Node.js library usage. | ||
|
||
## Features | ||
|
||
- Create `.docx` documents with a variety of elements (text, titles, subtitles, lists, bullets, footnotes). | ||
- Apply custom styles to document elements (font family, size, color). | ||
- Generate `.docx` documents with custom text, titles, subtitles, lists, bullets, and footnotes. | ||
- Easy integration into JavaScript and Node.js projects. | ||
- Flexible document structure and styling. | ||
|
||
## Setting Up the Development Environment | ||
## Getting Started | ||
|
||
### Prerequisites | ||
### API Usage | ||
|
||
- Node.js (v12.x or higher recommended) | ||
- npm (usually comes with Node.js) | ||
To create a document using the API, send a POST request to `/api/create-document` with your document structure and style defined in JSON. | ||
|
||
### Installing Dependencies | ||
**Example Request:** | ||
|
||
After navigating to the `officegen-api` directory, install the necessary dependencies using npm: | ||
```json | ||
POST /api/create-document | ||
Content-Type: application/json | ||
|
||
```shell | ||
npm install | ||
{ | ||
"elements": [ | ||
{"type": "title", "text": "Document Title"}, | ||
... | ||
], | ||
"styles": { | ||
"textColor": "#000000", | ||
"fontFamily": { | ||
"title": "Arial", | ||
... | ||
} | ||
} | ||
} | ||
``` | ||
|
||
## Running the API | ||
**Response:** | ||
|
||
To start the API server, run: | ||
The API responds with the path to the created document upon success. | ||
|
||
```shell | ||
npm start | ||
```json | ||
{ | ||
"message": "Document created successfully", | ||
"path": "examples/document_123456789.docx" | ||
} | ||
``` | ||
|
||
Access the API at `http://localhost:3000/api/create-document`. | ||
### Library Usage | ||
|
||
## Using the API | ||
The UNIC Document Conversion Library enables creation of documents via a Node.js module. Install the library from GitHub Packages, configure your `.npmrc` for authentication, and use the library in your projects. | ||
|
||
### Creating a Document | ||
**Installation:** | ||
|
||
Send a POST request to `/api/create-document` with `documentElements` and `documentStyles` in the JSON body. | ||
```bash | ||
npm install @universityofnicosia/unic-document-conversion-library --save | ||
``` | ||
|
||
**Example Usage:** | ||
|
||
```javascript | ||
const documentLibrary = require('@universityofnicosia/unic-document-conversion-library'); | ||
|
||
Example request using `curl`: | ||
const inputJson = { | ||
"elements": [...], | ||
"styles": {...} | ||
}; | ||
|
||
```shell | ||
curl -X POST http://localhost:3000/api/create-document \ | ||
-H "Content-Type: application/json" \ | ||
-d '{"documentElements": [{"type": "title", "text": "Hello World"}], "documentStyles": {"fontFamily": {"title": "Arial"}}}' | ||
documentLibrary.createDocumentWithStructure(inputJson) | ||
.then((path) => console.log(`Document created at: ${path}`)) | ||
.catch((error) => console.error('Error creating document:', error)); | ||
``` | ||
|
||
## Prerequisites | ||
|
||
- Node.js (v12.x or higher) | ||
- npm | ||
|
||
## Documentation | ||
|
||
For more detailed examples and error handling, please refer to the `api-usage.md` and `library-usage.md` files in the `examples` directory. | ||
|
||
## Contributing | ||
|
||
Contributions are welcome! Please refer to the main repository's CONTRIBUTING.md file for guidelines. | ||
Contributions are welcome! If you have suggestions or encounter issues, please file a report in the issues section. | ||
|
||
## License | ||
|
||
This project is provided under the [MIT License](https://opensource.org/licenses/MIT). |
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,89 @@ | ||
# UNIC Document Conversion Library - Usage Guide | ||
|
||
## Introduction | ||
|
||
The UNIC Document Conversion 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 covers the process of setting up, installing, and using this private NPM package within your projects. | ||
|
||
## Prerequisites | ||
|
||
Before you begin, ensure you have the following installed: | ||
- Node.js (v12.x or higher recommended) | ||
- npm (usually comes 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: | ||
```bash | ||
npm install @universityofnicosia/unic-document-conversion-library --save | ||
``` | ||
|
||
## Setting Up Your Project | ||
|
||
1. **Create a new Node.js project** (if you haven't already) by running `npm init` in your project directory and following the prompts. | ||
2. **Install the UNIC Document Conversion Library** using the command provided in the Installation section above. | ||
## Usage | ||
To use the library, you need to import it into your Node.js application, configure your document structure and styles in JSON format, and call the library function to create a document. | ||
### Basic Example | ||
Here's a basic example of how to use the library: | ||
|
||
```javascript | ||
const documentLibrary = require('@universityofnicosia/unic-document-conversion-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)); | ||
``` | ||
### Error Handling | ||
The library provides error handling mechanisms. Ensure your application properly catches and handles these errors, especially for invalid inputs or issues during document generation. | ||
## Advanced Usage | ||
For more complex documents, refer to the `officegen` documentation to understand all supported elements and styles. The UNIC Document Conversion Library supports these features as part of the `inputJson` configuration. | ||
## Contributing | ||
We welcome contributions! If you have suggestions for improvements or encounter any issues, please file a report in the repository's issues section. | ||
## License | ||
This library is provided under the [MIT License](https://opensource.org/licenses/MIT). Please review the license terms before using or contributing to the project. |
Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.
Oops, something went wrong.
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -1,17 +1,21 @@ | ||
{ | ||
"name": "officegen-api", | ||
"version": "1.0.0", | ||
"description": "API for document conversion using officegen", | ||
"main": "src/app.js", | ||
"name": "@universityofnicosia/unic-document-conversion-library", | ||
"version": "1.0.6", | ||
"description": "A library and API for document conversion using officegen", | ||
"main": "src/documentLibrary.js", | ||
"scripts": { | ||
"start": "node src/app.js", | ||
"test": "jest" | ||
}, | ||
"dependencies": { | ||
"express": "^4.19.2", | ||
"officegen": "^0.6.5" | ||
"officegen": "^0.6.5", | ||
"stream-buffers": "^3.0.2" | ||
}, | ||
"devDependencies": { | ||
"jest": "^29.7.0" | ||
}, | ||
"publishConfig": { | ||
"registry": "https://npm.pkg.github.com/@universityofnicosia" | ||
} | ||
} |
Oops, something went wrong.