/docxtpl

a word document .docx template plugin to easily populate and generate word documents from templates

Primary LanguageDartBSD 3-Clause "New" or "Revised" LicenseBSD-3-Clause

docxtpl

A word document template plugin to easily populate and generate word documents from templates

screenshots

Generate From Asset template .docx Generate From Remote Template .docx Generate From Local Template .docx

Installation

  • add docxtpl plugin to your pubspec.yaml file
dependencies:
  flutter:
    sdk: flutter

  docxtpl: 

Motive

  • I tried looking for plugins where i can work with word documents and i wasn't lucky to find what i really needed. From my python background i found helpful packages that work around templating and i thought maybe i can do something like that in flutter
  • The idea is to first make an example of the document you want to generate with microsoft word as you want. Then as you are creating your .docx word document, you insert jinja2-like tags like {{my-tag-name}} for example. If you want to put a name placeholder to populate later using this plugin, do it like {{name}} directly in the document.
  • You then save the word document as .docx (xml formart) and this is your .docx template file (tpl)
  • Now you can use docxtpl plugin to generate as many word documents as you want from this tpl file and the fields you will provide

Template file before and after using docxtpl plugin

Before: word document template .docx After(with docxtpl plugin): template .docx

Usage

First import the docxtpl plugin in your dart file

import 'package:docxtpl/docxtpl.dart';

Make sure you have created your .docx template file and saved it either in your asset folder or remote or in your device local storage.

  • docxtpl can work with generated templates from asset folder, remote file and device storage file.

Example: Generate from .docx tpl in asset folder

Make sure you have added your .docx word tpl asset file in pubspec.yaml file

   final DocxTpl docxTpl = DocxTpl(
      docxTemplate: 'assets/invite.docx',  // path where tpl file is
      isAssetFile: true,      // flag to true for tpl file from asset
    );

   // fields corresponding to merge fields found to fill the template with
   var templateData = {
    'name': 'Dart | Flutter Developer',
    'event': 'DocxTpl Plugin Contribution',
    'venue': 'Github',
    'time': 'Anytime',
    'row': '1',
    'guest': 'Flutter',
    'sender': '@DonnC',
  };

   var response = await docxTpl.parseDocxTpl();

   print(response.mergeStatus);
   print(response.message);

    if(response.mergeStatus == MergeResponseStatus.Success) {
      // success, proceed
      // get merge fields extracted by the plugin to know which fields to fill
      var fields = docxTpl.getMergeFields();

      print('Template file fields found: ');
      print(fields);

      await docxTpl.writeMergeFields(data: templateData);

      var savedFile = await docxTpl.save('invitation.docx');
    }

Features & TODO

  • [✔] Simple templating
  • [❌] able to pick complex tags
  • [❌] add more complex tag formats
  • [❌] able to populate a table
  • [❌] ability to insert images
  • [❌] ability to add custom file formatting (rich-text)
  • and more ...

Api Changes

Api changes are available on CHANGELOG

Support

  • This plugin offers a very basic word-templating with simple tags
  • It was tested with a simple word document
  • I really appreciate more support on this, hopefully it can be the ultimate go-to for working with word documents in flutter
  • Contributions are welcome with open hands

references