Skip to content
This repository has been archived by the owner on Sep 13, 2018. It is now read-only.

Latest commit

 

History

History
384 lines (313 loc) · 10.9 KB

README.md

File metadata and controls

384 lines (313 loc) · 10.9 KB
Raw

NPM version Build Status Dependency Status

A tool to create office documents (currently only Word Documents) with JS

This library is deprecated. A newer, more modern one is in development here!

Clippy in Microsoft Office

Table of Contents

Install

$ npm install --save office-clippy

Usage

var officeClippy = require('office-clippy');

// Used to create docx files
var docx = officeClippy.docx;

// Used to export the file into a .docx file
var exporter = officeClippy.exporter;

Create simple Word Document

var doc = docx.create();
var paragraph = docx.createParagraph("Some test");
doc.addParagraph(paragraph);

Document properties

You can add properties to the Word document by specifying options, for example:

var doc = docx.create({
    creator: 'Joe Bloggs',
    description: 'Some descriptive information here',
    title: 'My first word document'
});

Full list of options:

creator
description
title
subject
keywords
lastModifiedBy
revision

You can mix and match whatever properties you want, or provide no properties.

Create Paragraph

Every text block in OpenXML is organised in paragraphs. You can add more text to the paragraph by doing this:

var paragraph = docx.createParagraph();
var text = docx.createText("Lorem Ipsum Foo Bar");
var paragraph = docx.createParagraph();
paragraph.addText(text);
var paragraph = docx.createParagraph("Short hand notation for adding text.");

After you create the paragraph, you must add the paragraph into the document:

doc.addParagraph(paragraph);

Styles

Styles is a very important part of the look of a word document. At the moment, only headings and title is supported, but son the rest will be supported along with custom styles!

Word 2013 Styles menu

Heading1 - Heading5

paragraph.heading1();
paragraph.heading2();
paragraph.heading3();
paragraph.heading4();
paragraph.heading5();

Title

paragraph.title();

Text Alignment

To change the text alignment of a paragraph, for center, left, right or justified:

paragraph.center();
paragraph.left();
paragraph.right();
paragraph.justified();

Example

paragraph.heading1().center();

The above will create a heading 1 which is centered.

Thematic Break

To add a break in the page, simply add .thematicBreak() on a paragraph:

var paragraph = docx.createParagraph("Amazing Heading").heading1().thematicBreak();

The above example will create a heading with a page break directly under it.

Page Break

To move to a new page (insert a page break), simply add .pageBreak() on a paragraph:

var paragraph = docx.createParagraph("Amazing Heading").heading1().pageBreak();

The above example will create a heading and start a new page immediately afterwards.

Text

Paragraphs need text objects. To create text:

var text = docx.createText("My awesome text here for my university dissertation");
paragraph.addText(text);

Text objects have methods inside which changes the way the text is displayed.

Typographical Emphasis

More info here

Bold

text.bold();

Italics

text.italic();

Underline

text.underline();

Strike through

text.strike();

Double strike through

text.doubleStrike();

Superscript

text.superScript();

Subscript

text.subScript();

All Capitals

text.allCaps();

Small Capitals

text.smallCaps();

Break

Sometimes you would want to put text underneath another line of text but inside the same paragraph.

text.break();

Chaining

What if you want to create a paragraph which is bold and italic?

paragraph.bold().italic();

Bullet Points

To make a bullet point, simply make a paragraph into a bullet point:

var text = docx.createText("Bullet points");
var paragraph = docx.createParagraph(text).bullet();

var text2 = docx.createText("Are awesome");
var paragraph2 = docx.createParagraph(text2).bullet();

doc.addParagraph(paragraph);
doc.addParagraph(paragraph2);

This will produce:

  • Bullet points
  • Are awesome

Tab Stops

If you do not know why tab stops are useful, then I recommend you do a bit of research. It enables side by side text which is nicely laid out without the need for tables, or constantly pressing space bar.

Note: At the moment, the unit of measurement for a tab stop is counter intuitive for a human. It is using OpenXMLs own measuring system. For example, 2268 roughly translates to 3cm. Therefore in the future, I may consider changing it to percentages or even cm.

Word 2013 Tabs

How it works is that, you create a tabStop, then add it to the paragraph. Then just add a tab() method call to a text object. Adding multiple tabStops will mean you would have to chain tab() until the desired tabStop is selected. Example is shown below.

Left Tab Stop

var tabStop = docx.createLeftTabStop(2268);
paragraph.addTabStop();

2268 is the distance from the left side.

Center Tab Stop

var tabStop = docx.createCenterTabStop(2268);
paragraph.addTabStop();

2268 is the distance from the left side.

Right Tab Stop

var tabStop = docx.createRightTabStop(2268);
paragraph.addTabStop();

2268 is the distance from the left side.

Max Right Tab Stop

var tabStop = docx.createMaxRightTabStop();
paragraph.addTabStop();

This will create a tab stop on the very edge of the right hand side. Handy for right aligning and left aligning text on the same line.

Example

var tabStop = docx.createMaxRightTabStop();
var paragraph = docx.createParagraph().addTabStop(tabStop);
var leftText = docx.createText("Hey everyone").bold();
var rightText = docx.createText("11th November 2015").tab();
paragraph.addText(leftText);
paragraph.addText(rightText);

The example above will create a left aligned text, and a right aligned text on the same line. The laymans approach to this problem would be to either use text boxes or tables. YUK!

var tabStop = docx.createMaxRightTabStop();
var tabStop2 = docx.createLeftTabStop(1000);
var paragraph = docx.createParagraph();
paragraph.addTabStop(tabStop);
paragraph.addTabStop(tabStop2);
var text = docx.createText("Second tab stop here I come!").tab().tab();
paragraph.addText(text);

The above shows the use of two tab stops, and how to select/use it.

Exporting

I used the express exporter in my website. It's very useful, and is the preferred way if you want to make a downloadable file for a visitor. it is much better than generating a physical file on the server, and then passing a download link to that file.

Express

Simply use the exporter, and pass in the necessary parameters:

var officeClippy = require('office-clippy');
var docx = officeClippy.docx;
var exporter = officeClippy.exporter;

var doc = docx.create();
exporter.express(res, doc, 'My first word document');

where res is the response object obtained through the Express router. It is that simple. The file will begin downloading in the browser.

Standalone .docx file

var fs = require('fs');

var doc = docx.create();
var output = fs.createWriteStream(__dirname + '\\My first word document.docx');
exporter.local(output, doc);

Examples

In practice

I used this library in my personal portfolio/CV website. Click generate CV for a demonstration. http://www.dolan.bio

General

Simple paragraph

var doc = docx.create();
var output = fs.createWriteStream(__dirname + '\\example.docx');

var paragraph = docx.createParagraph("Hello World");
var institutionText = docx.createText("University College London").bold(),
var dateText = docx.createText("5th Dec 2015").tab().bold();
paragraph.addText(institutionText);
paragraph.addText(dateText);

doc.addParagraph(paragraph);
exporter.local(output, doc);

Or:

var doc = docx.create();
var output = fs.createWriteStream(__dirname + '\\example.docx');

var paragraph = docx.createParagraph("Hello World");
var institutionText = docx.createText("University College London").bold(),
var dateText = docx.createText("5th Dec 2015").tab().bold();
paragraph.addText(institutionText);
paragraph.addText(dateText);

doc.addParagraph(paragraph);
exporter.local(output, doc);

Would produce:

Hello World

Lorem Ipsum foo bar

License

MIT © Dolan Miu

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.