dees-document/readme.md at 4c9b2671a91c515d059f248811c8f78588c14f3b

Philipp Kunz 4c9b2671a9 feat(core): Enhance document generation capabilities with improved modular structure and extended translation support.

2024-12-01 23:04:28 +01:00

8.1 KiB

Raw Blame History

# @design.estate/dees-document

A versatile tool for dynamically generating and rendering business documents, such as invoices, using modern web technologies and elements.

## Install

To incorporate `@design.estate/dees-document` into your project, execute the following command in your terminal:

```shell
npm install @design.estate/dees-document --save

This command will install the package and add it to your project's dependencies, thus making all the necessary modules available within your node_modules directory.

Usage

The @design.estate/dees-document package serves as a robust framework to facilitate the generation of business documents, such as invoices and contracts. Leveraging modern web technologies, this package integrates seamlessly with TypeScript and ES modules, offering a type-safe environment conducive to efficient, dynamic document creation. Presented here is a comprehensive guide to utilizing this package, ranging from initializing your environment to generating complete PDF documents.

Getting Started

To embark on a document creation journey, initiate the document service. This service constitutes the core of this package and is typically started at the application's outset.

import { PdfService, IPdfServiceConstructorOptions } from '@design.estate/dees-document';

async function setupPdfService() {
  const options: IPdfServiceConstructorOptions = {
    // configure your options here
  };
  
  const pdfService = await PdfService.createAndStart(options);
  console.log('PDF Service started successfully.');
  return pdfService;
}

The above code initializes the PdfService. Tailor the configuration options to suit your specific requirements.

Creating Documents

With the PDF service initialized, you can now proceed to generate your documents. In the following section, you will find a detailed walkthrough for creating an invoice. This method can be adapted to other document types with necessary modifications.

Step-by-Step: Create an Invoice

Define the Data Structure: Construct the details of the invoice, including the sender, recipient information, and the details of the items being invoiced.

import { ILetter } from '@design.estate/dees-document';

const invoiceData: ILetter = {
  from: {
    name: "Your Company Name",
    address: {
      streetName: "Your Street",
      houseNumber: "123",
      city: "Your City",
      country: "Your Country",
      postalCode: "12345",
    },
    email: "your-email@example.com",
    phone: "123-456-7890",
  },
  to: {
    name: "Recipient Company Name",
    address: {
      streetName: "Recipient Street",
      houseNumber: "456",
      city: "Recipient City",
      country: "Recipient Country",
      postalCode: "67890",
    },
    email: "recipient-email@example.com",
    phone: "098-765-4321",
  },
  content: {
    invoiceData: {
      items: [
        {
          name: "Service or Product Name",
          unitQuantity: 2,
          unitNetPrice: 100.00,
          unitType: 'service',
          vatPercentage: 19,
          currency: 'EUR',
        }
      ]
    }
  },
  subject: "Invoice for Services Rendered",
  date: new Date().getTime(),
  versionInfo: {
    type: "final",
    version: "1.0.0"
  },
};

The ILetter interface captures all the components of an invoice, including both the sender (from) and recipient (to) information, alongside the details of the invoiced items.

Generate the PDF: Convert the invoice details into a PDF file.

async function generateInvoice(pdfService: PdfService, invoiceData: ILetter) {
  const pdfBuffer = await pdfService.createPdfFromLetterObject(invoiceData);
  console.log('Invoice PDF generated successfully.');

  // Here you could save the PDF to your filesystem, send it via email, etc.
}

The createPdfFromLetterObject function returns a Buffer that contains the generated PDF, enabling you to save it to a file, send it to clients, or store it for record-keeping.

Integrate It All: The following script ties together the PDF service and generates the invoice with the described data.
```
async function main() {
  const pdfService = await setupPdfService();
  await generateInvoice(pdfService, invoiceData);
}

main().then(() => console.log('Invoice generation process completed.'));
```
This example initiates the PDF service and utilizes it to generate a PDF invoice with specified parameters.

Advanced Document Features

The package is designed to create a broad range of documents, far beyond simple invoices. Utilize the modular architecture to customize documents to your specific business requirements.

Advanced Scenarios

Custom Styling: Alter the visual styles of various elements within your documents, like headers, footers, and more through CSS or inline styles.

import { DeDocumentViewer } from '@design.estate/dees-element';

const customStyledViewer = new DeDocumentViewer();
customStyledViewer.style.setProperty('--main-bg-color', 'lightblue');
document.body.appendChild(customStyledViewer);

Adjust styles either with standard CSS or via dynamic TypeScript changes.

Interactive Document Elements: Integrate interactive UI components, like buttons or input fields, fitting seamlessly into your documents.
Multi-page Document Generation: Handle content overflow elegantly through automatic page creation, keeping headers and footers intact.
```
pdfService.adjustDePageScaling();
```
Adapt between print and digital formats, managing scaling effectively.
Embedding Images and Logos: Enhance your document's appearance with company logos, graphics, and other auxiliary content.

Additional Capabilities

Beyond basic functionality, this package offers a range of advanced features:

Document Management: Manage multiple document templates, maintain version control, and append annotations or notes.
Dynamic Rendering: Utilize templating engines to render dynamic content based on input variables.
Responsive Design for Digital Documents: Ensure your documents are consistently displayed across various devices.

Concluding Remarks

The @design.estate/dees-document package presents a powerful solution within the modern document generation realm. From basic invoices to intricate templates, this package provides the essential tools for businesses to streamline their document workflows and enhance their presentation quality and accuracy. Explore further depth by consulting the package’s detailed documentation or by reviewing the examples included within the module.



## License and Legal Information

This repository contains open-source code that is licensed under the MIT License. A copy of the MIT License can be found in the [license](license) file within this repository. 

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH and are not included within the scope of the MIT license granted herein. Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines, and any usage must be approved in writing by Task Venture Capital GmbH.

### Company Information

Task Venture Capital GmbH  
Registered at District court Bremen HRB 35230 HB, Germany

For any legal inquiries or if you require further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

8.1 KiB Raw Blame History Unescape Escape