README-basic.md

How to create documents using officegen:

• Create an officegen object
• Fill the officegen object with data
• Generate the document itself into the given node.js streaming object

Creating an officegen object:

First, make sure to require the officegen module:

var officegen = require('officegen')

There are two ways to use the officegen returned function to create an officegen object:

var myDoc = officegen('<type of document to create>')

// or:

var myDoc = officegen({
  'type': '<type of document to create>'
  // More options here (if needed)
})

// Supported types:
// 'pptx' or 'ppsx' - Microsoft PowerPoint based document.
// 'docx' - Microsoft Word based document.
// 'xlsx' - Microsoft Excel based document.

Creating an empty Microsoft PowerPoint officegen object:

var pptx = officegen('pptx')

Creating an empty Microsoft Word officegen object:

var docx = officegen('docx')

Creating an empty Microsoft Excel officegen object:

var xlsx = officegen('xlsx')

Using officegen stream events:

Right now officegen sending error events to itself so you'll need to catch the 'error' events on the officegen object:

pptx.on('error', function (err) {
  console.log(err)
})

Another (old) way to register the 'error' event:

var pptx = officegen({
  'type': 'pptx', // or 'xlsx', etc
  'onerr': function (err) {
    console.log(err)
  }
})

If you are preferring to use callbacks instead of events you can pass your callbacks to the generate method (see below).

Now you should fill the object with data (we'll see below) and then you should call generate with an output stream to create the output Office document.

Except for the officegen 'error' event, you should receive all the other events from the output stream that you are using. Normally a node.js stream object is sending the following events:

'error' - error events. 'final' or 'close' (depending on the stream type) - end of creating the output document.

Example with pptx:

var out = fs.createWriteStream('out.pptx')

out.on('close', function () {
  console.log('Finished to create the PPTX file!')
})

pptx.generate(out)

Passing callbacks to generate:

var out = fs.createWriteStream('out.pptx')

pptx.generate(out, {
  'finalize': function (written) {
    console.log('Finish to create a PowerPoint file.\nTotal bytes created: ' + written + '\n')
  },
  'error': function (err) {
    console.log(err)
  }
})

Generating HTTP stream example (no file been created):

var http = require('http')
var officegen = require('officegen')

http.createServer(function (request, response) {
  response.writeHead (200, {
    'Content-Type': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
    'Content-disposition': 'attachment; filename=surprise.pptx'
  })

  var pptx = officegen('pptx')

  pptx.on('finalize', function (written) {
    // We don't really need it in this case.
  })

  pptx.on('error', function (err) {
    // Error handing...
  })

  // ... (fill pptx with data)

  // Generate the Powerpoint document and sent it to the client via http:
  pptx.generate(response)
}).listen(3000)

Put data inside the document object:

MS-Office document properties (for all document types):

The default Author of all the documents been created by officegen is 'officegen'. If you want to put anything else please use the 'creator' option when calling the officegen function:

var pptx = officegen({
  'type': 'pptx', // or 'xlsx', etc.
  'creator': '<your project name here>'
})

Change the document title (pptx,ppsx,docx):

var pptx = officegen({
  'type': 'pptx',
  'title': '<title>'
});

// or

pptx.setDocTitle('<title>')

For Word only:

var docx = officegen({
  'type': 'docx',
  'subject': '...',
  'keywords': '...',
  'description': '...'
});

// or

docx.setDocSubject('...')
docx.setDocKeywords('...')
docx.setDescription('...')

Debugging:

If needed, you can activate some verbose messages (warning: this does not cover all part of the lib yet) with :

officegen.setVerboseMode(true)