fix(documentation): Updated project description and enhanced documentation in package.json and README
This commit is contained in:
parent
406db92ac1
commit
d0d4671d41
@ -1,5 +1,13 @@
|
||||
# Changelog
|
||||
|
||||
## 2024-12-02 - 1.3.1 - fix(documentation)
|
||||
Updated project description and enhanced documentation in package.json and README
|
||||
|
||||
- The package description in package.json was updated to include more features.
|
||||
- Added more details about setting up and using the PdfService.
|
||||
- Included comprehensive examples for initializing and generating PDFs.
|
||||
- Expanded sections covering advanced features, modular components, interactive documents, and localization support.
|
||||
|
||||
## 2024-12-02 - 1.3.0 - feat(translation)
|
||||
Add multi-language support for document translations.
|
||||
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
"githost": "code.foss.global",
|
||||
"gitscope": "designestate/private",
|
||||
"gitrepo": "dedocument-catalog",
|
||||
"description": "A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.",
|
||||
"description": "A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.",
|
||||
"npmPackagename": "@designestate_private/dedocument-catalog",
|
||||
"license": "MIT",
|
||||
"projectDomain": "design.estate",
|
||||
@ -24,7 +24,11 @@
|
||||
"responsive design",
|
||||
"QR code",
|
||||
"modular architecture",
|
||||
"automated workflows"
|
||||
"automated workflows",
|
||||
"localization",
|
||||
"digital signatures",
|
||||
"security",
|
||||
"interactive documents"
|
||||
]
|
||||
}
|
||||
},
|
||||
|
||||
10
package.json
10
package.json
@ -2,7 +2,7 @@
|
||||
"name": "@design.estate/dees-document",
|
||||
"version": "1.3.0",
|
||||
"private": false,
|
||||
"description": "A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.",
|
||||
"description": "A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.",
|
||||
"main": "dist_ts_web/index.js",
|
||||
"typings": "dist_ts_web/index.d.ts",
|
||||
"exports": {
|
||||
@ -11,7 +11,7 @@
|
||||
},
|
||||
"scripts": {
|
||||
"test": "npm run build && tstest test/",
|
||||
"build": "tsbuild --allowimplicitany && tsbuild element --allowimplicitany && tsbundle element --production",
|
||||
"build": "tsbuild tsfolders --allowimplicitany && tsbuild element --allowimplicitany && tsbundle element --production",
|
||||
"watch": "tswatch element",
|
||||
"buildDocs": "tsdoc"
|
||||
},
|
||||
@ -78,6 +78,10 @@
|
||||
"responsive design",
|
||||
"QR code",
|
||||
"modular architecture",
|
||||
"automated workflows"
|
||||
"automated workflows",
|
||||
"localization",
|
||||
"digital signatures",
|
||||
"security",
|
||||
"interactive documents"
|
||||
]
|
||||
}
|
||||
269
readme.md
269
readme.md
@ -1,7 +1,6 @@
|
||||
```markdown
|
||||
# @design.estate/dees-document
|
||||
|
||||
A versatile tool for dynamically generating and rendering business documents, such as invoices, using modern web technologies and elements.
|
||||
A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.
|
||||
|
||||
## Install
|
||||
|
||||
@ -15,18 +14,20 @@ This command will install the package and add it to your project's dependencies,
|
||||
|
||||
## 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.
|
||||
The `@design.estate/dees-document` package serves as a robust framework to facilitate the generation of business documents, such as invoices, contracts, and reports. Leveraging modern web technologies, this package integrates seamlessly with TypeScript and ES modules, offering a type-safe environment conducive to efficient, dynamic document creation.
|
||||
|
||||
### Getting Started
|
||||
Below, we provide a detailed guide for utilizing this package, from initializing your environment to generating complete PDF documents.
|
||||
|
||||
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.
|
||||
### Setting Up the Environment
|
||||
|
||||
Before diving into document creation, ensure your environment is properly configured. Make sure to import necessary dependencies and setup configurations:
|
||||
|
||||
```typescript
|
||||
import { PdfService, IPdfServiceConstructorOptions } from '@design.estate/dees-document';
|
||||
|
||||
async function setupPdfService() {
|
||||
const options: IPdfServiceConstructorOptions = {
|
||||
// configure your options here
|
||||
// Configure your options here
|
||||
};
|
||||
|
||||
const pdfService = await PdfService.createAndStart(options);
|
||||
@ -35,138 +36,142 @@ async function setupPdfService() {
|
||||
}
|
||||
```
|
||||
|
||||
The above code initializes the `PdfService`. Tailor the configuration options to suit your specific requirements.
|
||||
In this setup snippet, you set up the `PdfService` which is the core component for PDF generation. The configuration options should be adjusted to fit your needs, especially considering options such as file paths, languages, and template directories.
|
||||
|
||||
### Creating Documents
|
||||
### Creating a Document Template
|
||||
|
||||
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.
|
||||
To create documents, particularly invoices, you'll first need to define a template. This template describes the structure of your document:
|
||||
|
||||
#### Step-by-Step: Create an Invoice
|
||||
```typescript
|
||||
import { ILetter } from '@design.estate/dees-document';
|
||||
|
||||
1. **Define the Data Structure**: Construct the details of the invoice, including the sender, recipient information, and the details of the items being invoiced.
|
||||
|
||||
```typescript
|
||||
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.
|
||||
|
||||
2. **Generate the PDF**: Convert the invoice details into a PDF file.
|
||||
|
||||
```typescript
|
||||
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.
|
||||
|
||||
3. **Integrate It All**: The following script ties together the PDF service and generates the invoice with the described data.
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
1. **Custom Styling**: Alter the visual styles of various elements within your documents, like headers, footers, and more through CSS or inline styles.
|
||||
|
||||
```typescript
|
||||
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.
|
||||
|
||||
2. **Interactive Document Elements**: Integrate interactive UI components, like buttons or input fields, fitting seamlessly into your documents.
|
||||
|
||||
3. **Multi-page Document Generation**: Handle content overflow elegantly through automatic page creation, keeping headers and footers intact.
|
||||
|
||||
```typescript
|
||||
pdfService.adjustDePageScaling();
|
||||
```
|
||||
|
||||
Adapt between print and digital formats, managing scaling effectively.
|
||||
|
||||
4. **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.
|
||||
const invoiceTemplate: 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 `invoiceTemplate` object utilizes the `ILetter` interface which specifies the structure for invoice data, including sender and recipient details, itemization, and pricing.
|
||||
|
||||
### Generating the Document
|
||||
|
||||
Once a template is established, the next step is generating a PDF:
|
||||
|
||||
```typescript
|
||||
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.
|
||||
}
|
||||
```
|
||||
|
||||
In this function, the `createPdfFromLetterObject` method converts your invoice data into a `Buffer` containing the PDF. This `Buffer` can subsequently be saved as a file or sent over HTTP.
|
||||
|
||||
### Comprehensive Example
|
||||
|
||||
Below is an example integrating all previous steps into a single coherent script:
|
||||
|
||||
```typescript
|
||||
async function main() {
|
||||
const pdfService = await setupPdfService();
|
||||
const invoiceData: ILetter = {
|
||||
// Populate your invoice object
|
||||
};
|
||||
await generateInvoice(pdfService, invoiceData);
|
||||
}
|
||||
|
||||
main().then(() => console.log('Invoice generation process completed.'));
|
||||
```
|
||||
|
||||
This script encompasses initializing services and generating a PDF in a streamlined, efficient workflow.
|
||||
|
||||
### Advanced Features
|
||||
|
||||
`@design.estate/dees-document` provides several advanced functionalities, enabling rich document creation:
|
||||
|
||||
1. **Custom Templates & Styling**
|
||||
- Customize the styling through CSS or using inline styles in TypeScript.
|
||||
- Templates can be adjusted to present different document types (e.g., contracts, reports).
|
||||
|
||||
2. **Modular Components and Reuse**
|
||||
- Utilize modular components to create reusable parts across different documents, enhancing maintainability and reducing redundancy.
|
||||
|
||||
3. **Interactive Documents**
|
||||
- Integrate interactivities like forms, buttons, and interactive charts within your documents.
|
||||
|
||||
4. **Localization Support**
|
||||
- Documents can be localized to support multiple languages, enhancing accessibility and usability.
|
||||
|
||||
5. **Responsive and Adaptive Designs**
|
||||
- Create documents that adjust layout dynamically depending on print or digital medium, maintaining consistency across platforms.
|
||||
|
||||
6. **Security Features**
|
||||
- Apply digital signatures and encrypt sensitive documents to ensure secure and authentic document distribution.
|
||||
|
||||
7. **Complex Business Logic**
|
||||
- Implement complex logic for feature-rich documents such as inventory systems, automatic tax calculations, or real-time pricing adjustments.
|
||||
|
||||
### Utilize Translation for Localization
|
||||
|
||||
The package offers a translation mechanism to adapt your documents for international clients:
|
||||
|
||||
```typescript
|
||||
import { translate } from '@design.estate/dees-document/shared';
|
||||
|
||||
const languageCode: 'DE' | 'EN' | 'ES' = 'EN'; // Set required language code
|
||||
console.log(translate(languageCode, 'invoice', 'Invoice')); // Translated output
|
||||
```
|
||||
|
||||
Different language settings can be applied, enabling the seamless presentation of document contents tailored to regional and linguistic preferences.
|
||||
|
||||
### Conclusion
|
||||
|
||||
The `@design.estate/dees-document` package is a versatile and powerful solution for businesses seeking to automate and streamline their document generation processes using modern web technologies. By integrating seamlessly with TypeScript, it offers robust capabilities for creating complex, customizable, and interactive documents that can meet a variety of business needs.
|
||||
|
||||
From custom templates to localization and advanced security features, this module provides the flexibility and power to create polished and professional documents efficiently. Whether you're generating invoices, contracts, or detailed reports, `@design.estate/dees-document` has the tools to support your enterprise workflows with ease and precision.
|
||||
|
||||
## License and Legal Information
|
||||
|
||||
|
||||
@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@design.estate/dees-document',
|
||||
version: '1.3.0',
|
||||
description: 'A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.'
|
||||
version: '1.3.1',
|
||||
description: 'A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.'
|
||||
}
|
||||
|
||||
@ -3,6 +3,6 @@
|
||||
*/
|
||||
export const commitinfo = {
|
||||
name: '@design.estate/dees-document',
|
||||
version: '1.3.0',
|
||||
description: 'A comprehensive tool for dynamically generating and rendering business documents like invoices using modern web technologies.'
|
||||
version: '1.3.1',
|
||||
description: 'A sophisticated framework for dynamically generating and rendering business documents like invoices with modern web technologies, featuring PDF creation, templating, and automation.'
|
||||
}
|
||||
|
||||
Loading…
Reference in New Issue
Block a user