<?xml version="1.0" encoding="UTF-8"?>
<!--
  ~ ModeShape (http://www.modeshape.org)
  ~
  ~ See the COPYRIGHT.txt file distributed with this work for information
  ~ regarding copyright ownership.  Some portions may be licensed
  ~ to Red Hat, Inc. under one or more contributor license agreements.
  ~ See the AUTHORS.txt file in the distribution for a full listing of 
  ~ individual contributors.
  ~
  ~ ModeShape is free software. Unless otherwise indicated, all code in ModeShape
  ~ is licensed to you under the terms of the GNU Lesser General Public License as
  ~ published by the Free Software Foundation; either version 2.1 of
  ~ the License, or (at your option) any later version.
  ~
  ~ ModeShape is distributed in the hope that it will be useful,
  ~ but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
  ~ or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Lesser General Public License
  ~ for more details.
  ~
  ~ You should have received a copy of the GNU Lesser General Public License
  ~ along with this distribution; if not, write to:
  ~ Free Software Foundation, Inc.
  ~ 51 Franklin Street, Fifth Floor
  ~ Boston, MA  02110-1301  USA
  -->
<!DOCTYPE preface PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"	[
<!ENTITY % CustomDTD SYSTEM "../../custom.dtd">
%CustomDTD;
]>
<chapter id="msoffice-sequencer">
  <title><trademark class='registered'>Microsoft Office</trademark> Document Sequencer</title>
   <para>
   	This sequencer is included in ModeShape and processes Microsoft Office documents, including Word documents, Excel spreadsheets,
	and PowerPoint presentations.  With documents, the sequencer attempts to infer the internal structure from the heading styles.
	With presentations, the sequencer extracts the slides, titles, text and slide thumbnails.
	With spreadsheets, the sequencer extracts the names of the sheets.  And, the sequencer extracts for all the files the
	general file information, including the name of the author, title, keywords, subject, comments, and various dates.
   </para>
      <sect1>
        <title>Example</title>
	    <para>This sequencer generates a simple graph structure containing a variety of metadata from the Office document.
	    The example below provides example output (in the JCR document view) from a Word document sequenced into /document.  
	    </para>
	    <programlisting language="XML" role="XML"><![CDATA[
<document jcr:primaryType="msoffice:metadata"
          jcr:mixinTypes="mode:derived"
          mode:derivedAt="2011-05-13T13:12:03.925Z"
          mode:derivedFrom="/files/docForReferenceGuide.xml"
          msoffice:title="My Word Document"
          msoffice:subject="My Subject"
          msoffice:author="James Joyce"
          msoffice:keywords="essay english term paper"
          msoffice:comment="This is my English 101 term paper"
          msoffice:template="term_paper.dot"
          msoffice:last_saved_by="jjoyce"
          msoffice:revision="42"
          msoffice:total_editing_time="1023"
          msoffice:last_printed="2011-05-12T14:33Z"
          msoffice:created="2011-05-10T20:07Z"
          msoffice:saved="2011-05-12T14:32Z"
          msoffice:pages="14"
          msoffice:words="3025"
          msoffice:characters="12420"
          msoffice:creating_application="MSWORD.EXE"
          msoffice:thumbnail="..." />
]]></programlisting>
    <para>
       As indicated in the CND below, sequencing Excel spreadsheets also populates the <code>msoffice:full_content</code> 
       property with all text in the document and the <code>msoffice:sheets</code> multi-valued string property with one
       value for each worksheet name.  Sequencing PowerPoint presentations adds a child node for each slide containing the title
       (<code>msoffice:title</code>), slide text (<code>msoffice:text</code>), and thumbnail image (<code>msoffice:thumbnail)</code>
       for each slide.
    </para>
    <programlisting><![CDATA[
[msoffice:metadata] > nt:unstructured, mix:mimeType
  - msoffice:title (string)
  - msoffice:subject (string)
  - msoffice:author (string)
  - msoffice:keywords (string)
  - msoffice:comment (string)
  - msoffice:template (string)
  - msoffice:last_saved_by (string)
  - msoffice:revision (string)
  - msoffice:total_editing_time (long)
  - msoffice:last_printed (date)
  - msoffice:created (date)
  - msoffice:saved (date)
  - msoffice:pages (long)
  - msoffice:words (long)
  - msoffice:characters (long)
  - msoffice:creating_application (string)
  - msoffice:thumbnail (binary)

// PowerPoint specific data
  + msoffice:slide (msoffice:pptslide) sns

// Excel specific data
  - msoffice:full_content (string)
  - msoffice:sheet_name (string) multiple

[msoffice:pptslide]
  - msoffice:title (string)
  - msoffice:text (string)
  - msoffice:thumbnail (binary)    
]]></programlisting>
   
<para>
	To use this sequencer, simply include the <code>modeshape-sequencer-msoffice</code> JAR and all of the
	<ulink url="http://poi.apache.org/">POI</ulink> JARs
	in your application and configure the &JcrConfiguration; to use this sequencer using something similar to:
   </para>
  <programlisting language="JAVA" role="JAVA"><![CDATA[
JcrConfiguration config = ...

config.sequencer("Microsoft Office Document Sequencer")
      .usingClass("org.modeshape.sequencer.msoffice.MSOfficeMetadataSequencer")
      .loadedFromClasspath()
      .setDescription("Sequences MS Office documents, including spreadsheets and presentations")
      .sequencingFrom("//(*.(*.(doc|docx|ppt|pps|xls)[*])/jcr:content[@jcr:data]")
      .andOutputtingTo("/msoffice/$1");	
]]></programlisting>
  </sect1>
</chapter>
