officegen-dbb
Advanced tools
Modification of Ziv Barber's officegen, to provide a reasonable way to have line breaks in table cells.
This module can generate Office Open XML files for Microsoft Office 2007 and later. This module is not depend on any framework and you don't need to install Microsoft Office, so you can use it for any kind of javascript application. Also the output is a stream and not a file, not dependent on any output tool. This module should work on any environment that supports Node.js 0.10 or later including Linux, OSX and Windows.
This module generates Excel (.xlsx), PowerPoint (.pptx) and Word (.docx) documents. Officegen also supporting PowerPoint native charts objects with embedded data.
via Git:
$ git clone git://github.com/Ziv-Barber/officegen.git
via npm:
$ npm install officegen
If you are enthusiastic about using the latest that officegen has to offer (beware - may be unstable), you can install directly from the officegen repository using:
$ npm install Ziv-Barber/officegen#master
This module is depending on:
var officegen = require('officegen');
There are two ways to use the officegen returned function to create the document object:
var myDoc = officegen ( '<type of document to create>' );
var myDoc = officegen ({
'type': '<type of document to create>'
// More options here (if needed)
});
Generating PowerPoint 2007 object:
var pptx = officegen ( 'pptx' );
Generating Word 2007 object:
var docx = officegen ( 'docx' );
Generating Excel 2007 object:
var xlsx = officegen ( 'xlsx' );
General events of officegen:
Event examples:
pptx.on ( 'finalize', function ( written ) {
console.log ( 'Finish to create a PowerPoint file.\nTotal bytes created: ' + written + '\n' );
});
pptx.on ( 'error', function ( err ) {
console.log ( err );
});
Another way to register either 'finalize' or 'error' events:
var pptx = officegen ({
'type': 'pptx', // or 'xlsx', etc
'onend': function ( written ) {
console.log ( 'Finish to create a PowerPoint file.\nTotal bytes created: ' + written + '\n' );
},
'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.
Example with pptx:
var out = fs.createWriteStream ( 'out.pptx' );
pptx.generate ( out );
out.on ( 'close', function () {
console.log ( 'Finished to create the PPTX file!' );
});
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 (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 ) {
// ...
});
pptx.on ( 'error', function ( err ) {
// ...
});
// ... (fill pptx with data)
pptx.generate ( response );
}).listen ( 3000 );
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 ( '...' );
Creating a new slide:
slide = pptx.makeNewSlide ();
For creating a new slide using a layout:
slide = pptx.makeNewSlide ({
userLayout: 'title'
});
slide.setTitle ( 'The title' );
slide.setSubTitle ( 'Another text' ); // For either 'title' and 'secHead' only.
// for 'obj' layout use slide.setObjData ( ... ) to change the object element inside the slide.
userLayout can be:
Or more advance example:
slide = pptx.makeNewSlide ({
userLayout: 'title'
});
// Both setTitle and setSubTitle excepting all the parameters that you can pass to slide.addText - see below:
slide.setTitle ([
// This array is like a paragraph and you can use any settings that you pass for creating a paragraph,
// Each object here is like a call to addText:
{ text: 'Hello ', options: { font_size: 56 } },
{ text: 'World!', options: { font_size: 56, font_face: 'Arial', color: 'ffff00' } }
]);
The returned object from makeNewSlide representing a single slide. Use it to add objects into this slide. You must create at last one slide on your pptx/ppsx document.
Inside each slide you can place objects, for example: text box, shapes, images, etc.
Properties of the slide object itself:
The slide object supporting the following methods:
Read only methods:
Common properties that can be added to the options object for all the add based methods:
Font properties:
Text alignment properties:
Line/border extra properties (only effecting if the 'line' property exist):
The 'shape' property:
Normally every object is a rectangle but you can change that for every object using the shape property, or in case that you don't need to write any text inside that object, you can use the addShape method instead of addText. Use the shape property only if you want to use a shape other then the default and you also want to add text inside it.
Shapes list:
Please note that every color property can be either:
[{"position": 0, "color": '000000'}, {}, ...]Adding images:
Just pass the image file name as the first parameter to addImage and the 2nd parameter, which is optional, is normal options objects and you can use all the common properties ('cx', 'cy', 'y', 'x', etc).
Examples:
Changing the background color of a slide:
slide.back = '000088';
or:
slide.back = { type: 'solid', color: '008800' };
Examples how to put text inside the new slide:
// Change the background color:
slide.back = '000000';
// Declare the default color to use on this slide (default is black):
slide.color = 'ffffff';
// Basic way to add text string:
slide.addText ( 'This is a test' );
slide.addText ( 'Fast position', 0, 20 );
slide.addText ( 'Full line', 0, 40, '100%', 20 );
// Add text box with multi colors and fonts:
slide.addText ( [
{ text: 'Hello ', options: { font_size: 56 } },
{ text: 'World!', options: { font_size: 56, font_face: 'Arial', color: 'ffff00' } }
], { cx: '75%', cy: 66, y: 150 } );
// Please note that you can pass object as the text parameter to addText.
slide.addText ( 'Office generator', {
y: 66, x: 'c', cx: '50%', cy: 60, font_size: 48,
color: '0000ff' } );
slide.addText ( 'Big Red', {
y: 250, x: 10, cx: '70%',
font_face: 'Wide Latin', font_size: 54,
color: 'cc0000', bold: true, underline: true } );
PowerPoint slides can contain speaker notes, to do that use the setSpeakerNote method:
slide.setSpeakerNote ( 'This is a speaker note!' );
PowerPoint slides can contain charts with embedded data. To create a chart:
slide.addChart( chartInfo)
Where chartInfo object is an object that takes the following attributes:
data - an array of data, see examples belowrenderType - specifies base chart type, may be one of "bar", "pie", "group-bar", "column", "stacked-column", "line"title - chart title (default: none)valAxisTitle - value axis title (default: none)catAxisTitle - category axis title (default: none)valAxisMinValue - value axis min (default: none)valAxisMaxValue - vlaue axis max value (default: none)valAxisNumFmt - value axis format, e.g "$0" or "0%" (default: none)valAxisMajorGridlines - true|false (false)valAxisMinorGridlines - true|false (false)valAxisCrossAtMaxCategory - true|false (false)catAxisReverseOrder - true|false (false)fontSize - text size for chart, e.g. "1200" for 12pt typexml - optional XML overrides to <c:chart> as a Javascript object that is mixed inAlso, the overall chart and each data series take an an optional xml attribute, which specifies XML overrides to the <c:series> attribute.
xml argument for the chartInfo is mixed in to the c:chartSpace attribute.xml argument for the data series is mixed into the c:ser attribute.For instance, to specify the overall text size, you can specify the following on the chartInfo object.
The snippet below is what happens under the scenes when you specify fontSize: 1200
chartInfo = {
// ....
"xml": {
"c:txPr": {
"a:bodyPr": {},
"a:listStyle": {},
"a:p": {
"a:pPr": {
"a:defRPr": {
"@sz": "1200"
}
},
"a:endParaRPr": {
"@lang": "en-US"
}
}
}
}
Examples how to add chart into the slide:
// Column chart
slide = pptx.makeNewSlide();
slide.name = 'Chart slide';
slide.back = 'ffffff';
slide.addChart(
{ title: 'Column chart',
renderType: 'column',
valAxisTitle: 'Costs/Revenues ($)',
catAxisTitle: 'Category',
valAxisNumFmt: '$0',
valAxisMaxValue: 24,
data: [ // each item is one serie
{
name: 'Income',
labels: ['2005', '2006', '2007', '2008', '2009'],
values: [23.5, 26.2, 30.1, 29.5, 24.6],
color: 'ff0000' // optional
},
{
name: 'Expense',
labels: ['2005', '2006', '2007', '2008', '2009'],
values: [18.1, 22.8, 23.9, 25.1, 25],
color: '00ff00' // optional
}]
}
)
// Pie chart
slide = pptx.makeNewSlide();
slide.name = 'Pie Chart slide';
slide.back = 'ffff00';
slide.addChart(
{ title: 'My production',
renderType: 'pie',
data: [ // each item is one serie
{
name: 'Oil',
labels: ['Czech Republic', 'Ireland', 'Germany', 'Australia', 'Austria', 'UK', 'Belgium'],
values: [301, 201, 165, 139, 128, 99, 60],
colors: ['ff0000', '00ff00', '0000ff', 'ffff00', 'ff00ff', '00ffff', '000000'] // optional
}]
}
)
// Bar Chart
slide = pptx.makeNewSlide();
slide.name = 'Bar Chart slide';
slide.back = 'ff00ff';
slide.addChart(
{ title: 'Sample bar chart',
renderType: 'bar',
data: [ // each item is one serie
{
name: 'europe',
labels: ['Y2003', 'Y2004', 'Y2005'],
values: [2.5, 2.6, 2.8],
color: 'ff0000' // optional
},
{
name: 'namerica',
labels: ['Y2003', 'Y2004', 'Y2005'],
values: [2.5, 2.7, 2.9],
color: '00ff00' // optional
},
{
name: 'asia',
labels: ['Y2003', 'Y2004', 'Y2005'],
values: [2.1, 2.2, 2.4],
color: '0000ff' // optional
},
{
name: 'lamerica',
labels: ['Y2003', 'Y2004', 'Y2005'],
values: [0.3, 0.3, 0.3],
color: 'ffff00' // optional
},
{
name: 'meast',
labels: ['Y2003', 'Y2004', 'Y2005'],
values: [0.2, 0.3, 0.3],
color: 'ff00ff' // optional
},
{
name: 'africa',
labels: ['Y2003', 'Y2004', 'Y2005'],
values: [0.1, 0.1, 0.1],
color: '00ffff' // optional
}
]
}
)
// Line Chart
slide = pptx.makeNewSlide();
slide.name = 'Line Chart slide';
slide.back = 'ff00ff';
slide.addChart(
{ title: 'Sample line chart',
renderType: 'line',
data: [ // each item is one serie
{
name: 'europe',
labels: ['Y2003', 'Y2004', 'Y2005', 'Y2006'],
values: [2.5, 2.6, 2.8, 2.4],
color: 'ff0000' // optional
},
{
name: 'namerica',
labels: ['Y2003', 'Y2004', 'Y2005', 'Y2006'],
values: [2.5, 2.7, 2.9, 3.2],
color: '00ff00' // optional
},
{
name: 'asia',
labels: ['Y2003', 'Y2004', 'Y2005', 'Y2006'],
values: [2.1, 2.2, 2.4, 2.2],
color: '0000ff' // optional
}
]
}
)
Add a table to a PowerPoint slide:
var rows = [];
for (var i = 0; i < 12; i++) {
var row = [];
for (var j = 0; j < 5; j++) {
row.push("[" + i + "," + j + "]");
}
rows.push(row);
}
slide.addTable(rows, {});
Specific options for tables (in addition to standard : x, y, cx, cy, etc.) :
All the text data in Word is saved in paragraphs. To add a new paragraph:
var pObj = docx.createP ();
Paragraph options:
pObj.options.align = 'center'; // Also 'right' or 'jestify'.
Every list item is also a paragraph so:
var pObj = docx.createListOfDots ();
var pObj = docx.createListOfNumbers ();
Now you can fill the paragraph object with one or more text strings using the addText method:
pObj.addText ( 'Simple' );
pObj.addText ( ' with color', { color: '000088' } );
pObj.addText ( ' and back color.', { color: '00ffff', back: '000088' } );
pObj.addText ( 'Bold + underline', { bold: true, underline: true } );
pObj.addText ( 'Fonts face only.', { font_face: 'Arial' } );
pObj.addText ( ' Fonts face and size. ', { font_face: 'Arial', font_size: 40 } );
pObj.addText ( 'External link', { link: 'https://github.com' } );
// Hyperlinks to bookmarks also supported:
pObj.addText ( 'Internal link', { hyperlink: 'myBookmark' } );
// ...
// Start somewhere a bookmark:
pObj.startBookmark ( 'myBookmark' );
// ...
// You MUST close your bookmark:
pObj.endBookmark ();
Add an image to a paragraph:
var path = require('path');
pObj.addImage ( path.resolve(__dirname, 'myFile.png' ) ); pObj.addImage ( path.resolve(__dirname, 'myFile.png', { cx: 300, cy: 200 } ) );
To add a line break;
var pObj = docx.createP ();
pObj.addLineBreak ();
To add a page break:
docx.putPageBreak ();
To add a horizontal line:
var pObj = docx.createP ();
pObj.addHorizontalLine ();
To add a back line:
var pObj = docx.createP ({ backline: 'E0E0E0' });
pObj.addText ( 'Backline text1' );
pObj.addText ( ' text2' );
To add a table:
var table = [
[{
val: "No.",
opts: {
cellColWidth: 4261,
b:true,
sz: '48',
shd: {
fill: "7F7F7F",
themeFill: "text1",
"themeFillTint": "80"
},
fontFamily: "Avenir Book"
}
},{
val: "Title1",
opts: {
b:true,
color: "A00000",
align: "right",
shd: {
fill: "92CDDC",
themeFill: "text1",
"themeFillTint": "80"
}
}
},{
val: "Title2",
opts: {
align: "center",
vAlign: "center",
cellColWidth: 42,
b:true,
sz: '48',
shd: {
fill: "92CDDC",
themeFill: "text1",
"themeFillTint": "80"
}
}
}],
[1,'All grown-ups were once children',''],
[2,'there is no harm in putting off a piece of work until another day.',''],
[3,'But when it is a matter of baobabs, that always means a catastrophe.',''],
[4,'watch out for the baobabs!','END'],
]
var tableStyle = {
tableColWidth: 4261,
tableSize: 24,
tableColor: "ada",
tableAlign: "left",
tableFontFamily: "Comic Sans MS",
borders: true
}
docx.createTable (table, tableStyle);
Header and footer:
// Add a header:
var header = docx.getHeader ().createP ();
header.addText ( 'This is the header' );
// Please note that the object header here is a paragraph object so you can use ANY of the paragraph API methods also for header and footer.
// The getHeader () method excepting a string parameter:
// getHeader ( 'even' ) - change the header for even pages.
// getHeader ( 'first' ) - change the header for the first page only.
// to do all of that for the footer, use the getFooter instead of getHeader.
// and sorry, right now only createP is supported (so only creating a paragraph) so no tables, etc.
To Create Word Document by json:
var table = [
[{
val: "No.",
opts: {
cellColWidth: 4261,
b:true,
sz: '48',
shd: {
fill: "7F7F7F",
themeFill: "text1",
"themeFillTint": "80"
},
fontFamily: "Avenir Book"
}
},{
val: "Title1",
opts: {
b:true,
color: "A00000",
align: "right",
shd: {
fill: "92CDDC",
themeFill: "text1",
"themeFillTint": "80"
}
}
},{
val: "Title2",
opts: {
align: "center",
cellColWidth: 42,
b:true,
sz: '48',
shd: {
fill: "92CDDC",
themeFill: "text1",
"themeFillTint": "80"
}
}
}],
[1,'All grown-ups were once children',''],
[2,'there is no harm in putting off a piece of work until another day.',''],
[3,'But when it is a matter of baobabs, that always means a catastrophe.',''],
[4,'watch out for the baobabs!','END'],
]
var tableStyle = {
tableColWidth: 4261,
tableSize: 24,
tableColor: "ada",
tableAlign: "left",
tableFontFamily: "Comic Sans MS"
}
var data = [[{
type: "text",
val: "Simple"
}, {
type: "text",
val: " with color",
opt: { color: '000088' }
}, {
type: "text",
val: " and back color.",
opt: { color: '00ffff', back: '000088' }
}, {
type: "linebreak"
}, {
type: "text",
val: "Bold + underline",
opt: { bold: true, underline: true }
}], {
type: "horizontalline"
}, [{ backline: 'EDEDED' }, {
type: "text",
val: " backline text1.",
opt: { bold: true }
}, {
type: "text",
val: " backline text2.",
opt: { color: '000088' }
}], {
type: "text",
val: "Left this text.",
lopt: { align: 'left' }
}, {
type: "text",
val: "Center this text.",
lopt: { align: 'center' }
}, {
type: "text",
val: "Right this text.",
lopt: { align: 'right' }
}, {
type: "text",
val: "Fonts face only.",
opt: { font_face: 'Arial' }
}, {
type: "text",
val: "Fonts face and size.",
opt: { font_face: 'Arial', font_size: 40 }
}, {
type: "table",
val: table,
opt: tableStyle
}, [{ // arr[0] is common option.
align: 'right'
}, {
type: "image",
path: path.resolve(__dirname, 'images_for_examples/sword_001.png')
},{
type: "image",
path: path.resolve(__dirname, 'images_for_examples/sword_002.png')
}], {
type: "pagebreak"
}
]
docx.createByJson(data);
sheet = xlsx.makeNewSheet ();
sheet.name = 'My Excel Data';
Fill cells:
// Using setCell:
sheet.setCell ( 'E7', 340 );
sheet.setCell ( 'G102', 'Hello World!' );
// Direct way:
sheet.data[0] = [];
sheet.data[0][0] = 1;
sheet.data[0][1] = 2;
sheet.data[1] = [];
sheet.data[1][3] = 'abc';
You can check the jsdoc documentation:
grunt jsdoc
A basic test suite creates XLSX, PPTX, DOCX files and compares them to reference file located under test_files.
To run the tests, run the following at the command line within the project root:
npm test
If needed, you can activate some verbose messages (warning: this does not cover all part of the lib yet) with :
officegen.setVerboseMode(true);
Please visit the officegen Google Group:
Plans for the next release:
The Slack team:
Please check here:
(The MIT License)
Copyright (c) 2013-2017 Ziv Barber;
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the 'Software'), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED 'AS IS', WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
The original author is accepting tips through Gittip
FAQs
Modification of Ziv Barber's officegen, to provide a reasonable way to have line breaks in table cells.
The npm package officegen-dbb receives a total of 16 weekly downloads. As such, officegen-dbb popularity was classified as not popular.
We found that officegen-dbb demonstrated a not healthy version release cadence and project activity because the last version was released a year ago. It has 1 open source maintainer collaborating on the project.
Did you know?
Socket for GitHub automatically highlights issues in each pull request and monitors the health of all your open source dependencies. Discover the contents of your packages and block harmful activity before you install or update your dependencies.
Security News
Research
Socket researchers have discovered malicious npm packages targeting crypto developers, stealing credentials and wallet data using spyware delivered through typosquats of popular cryptographic libraries.
Security News
Socket's package search now displays weekly downloads for npm packages, helping developers quickly assess popularity and make more informed decisions.
Security News
A Stanford study reveals 9.5% of engineers contribute almost nothing, costing tech $90B annually, with remote work fueling the rise of "ghost engineers."