<apidoc:module name="OOXML Zip" category="ZIP Package" lib="ooxml" 
	xmlns:apidoc="http://marklogic.com/xdmp/apidoc" 
	xmlns="http://www.w3.org/1999/xhtml"
	bucket="XQuery Library Modules">
  <apidoc:summary>
      <p>The ZIP Package function module is installed as the following 
		  file:</p>
    <ul>
	    <li><code><em>install_dir</em>/Modules/MarkLogic/openxml/package.xqy</code></li>
    </ul>
    <p>where <code><em>install_dir</em></code> is the directory in which 
	    MarkLogic Server is installed.</p>
    <p>To use the <code>package.xqy</code> module in your own 
    XQuery modules, 
    include the following line in your XQuery prolog:</p>
    <pre xml:space="preserve">
import module namespace ooxml="http://marklogic.com/openxml" 
	    at "/MarkLogic/openxml/package.xqy";</pre>
    <p>The ZIP Package functions are used to unpack Microsoft Office
	    Open XML documents from their compressed ZIP format into an
	    expanded package with a directory structure, and then to 
	    insert each of those documents in a database.  You can use
	    these functions with any document that is a ZIP package,
	    including Office 2007 documents.
    </p>
  </apidoc:summary>
  <apidoc:function name="package-uris" lib="ooxml" 
	  category="ZIP Package"  bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the list of files in the
		  zip package.
	  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="package" type="node()">The zip package.</apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string*</apidoc:return>
        <apidoc:example><pre xml:space="preserve"><![CDATA[
xquery version "1.0-ml";
import module namespace ooxml= "http://marklogic.com/openxml" 
            at "/MarkLogic/openxml/package.xqy";

let $pkg := xdmp:document-get("c:/tmp/test.docx")
return
ooxml:package-uris($pkg)
=> The sequence comprising th list of documents in the archive, 
for example:
("[Content_Types].xml", "_rels/.rels", "word/_rels/document.xml.rels",
"word/document.xml", "word/footer3.xml", "word/footer2.xml", 
"word/footer1.xml", "word/endnotes.xml", "word/footnotes.xml", 
"word/_rels/header1.xml.rels", "word/header1.xml", 
"word/media/image1.wmf", "word/theme/theme1.xml", 
"word/_rels/settings.xml.rels", "word/settings.xml", 
"word/styles.xml", "customXml/itemProps1.xml", "word/numbering.xml",
"customXml/_rels/item1.xml.rels", "word/fontTable.xml", 
"docProps/app.xml", "docProps/core.xml", "customXml/item1.xml", 
"word/webSettings.xml", "docProps/custom.xml")


  ]]></pre>
  </apidoc:example>
  </apidoc:function>

    <apidoc:function name="package-parts" lib="ooxml" 
	  category="ZIP Package"  bucket="XQuery Library Modules">
	  <apidoc:summary>This function returns the documents within the
		  zip package.  Typically, the parts are returned as document 
		  nodes. They are returned in the order the package
		  uris are returned, which is the manifest order.
	  </apidoc:summary>
    <apidoc:params>
      <apidoc:param name="package" type="node()">The zip package.</apidoc:param>
    </apidoc:params>
    <apidoc:return>xs:string*</apidoc:return>
        <apidoc:example><pre xml:space="preserve"><![CDATA[
xquery version "1.0-ml";
import module namespace ooxml= "http://marklogic.com/openxml" 
          at "/MarkLogic/openxml/package.xqy";

let $pkg := xdmp:document-get("c:/tmp/test.docx")
return
ooxml:package-parts($pkg)[4]
=> The fourth document in the archive, which is the
word/document.xml part in this example.

  ]]></pre>
  </apidoc:example>
  </apidoc:function>

    <apidoc:function name="package-parts-insert" lib="ooxml" 
	  category="ZIP Package"  bucket="XQuery Library Modules">
	  <apidoc:summary>This function inserts one document in the database
		  for each part at the specified URI.  If a directory
		  is given, then all parts are inserted into documents in 
		  that directory, with the rest of the URI determined by
		  the $uris specified (typically from the manifest of a 
		  zip file or Office document).
	  </apidoc:summary>
    <apidoc:params>
	    <apidoc:param name="directory" type="xs:string?">The name
		    of the base directory to concatenate with each of the
		    $package-uris.  If this is the empty string, then the
		    URIs for each document are the $package-uris.  If the 
		    string does not end in a forward slash ( <code>/</code> ),
		    one is added (because directory URIs should end in a 
		    forward slash).
	    </apidoc:param>
	    <apidoc:param name="package-uris" type="xs:string*">The list
		    of URIs for the parts to insert, typically from the zip 
		    package manifest (or from <code>ooxml:package-uris</code>.)
		    The order must correspond to the order of $package-parts.
	    </apidoc:param>
	    <apidoc:param name="package-parts" type="node()*">The uncompressed
		    parts to insert, typically from the zip package
		    (or from <code>ooxml:package-parts</code>.) The order must
		    correspond to the order of $package-uris.
	    </apidoc:param>
	      <apidoc:param name="permissions" type="element(sec:permission)*" 
                optional="true">
    Security permission elements corresponding to the permissions
    for the document. If not supplied, the current user's default 
    permissions are applied.  The default value used for $permissions
    can be obtained by calling xdmp:default-permissions(). A document that is 
    created by a non-admin user (that is, by any user who does not have the 
    <code>admin</code> role) must have at least one update permission, 
    otherwise the creation will throw an <code>XDMP-MUSTHAVEUPDATE</code>
    exception.  
  </apidoc:param>
  <apidoc:param name="collections" type="xs:string*" optional="true">
    The collection URIs for collections to which this document 
    belongs.  If not supplied, the document is added to the current
    user's default collections.  For each collection that is protected, the 
    user must have permissions to update that collection or have the 
    <code>any-collection</code> privilege. For each unprotected collection, 
    the user must have the <code>unprotected-collections</code> privilege.
    The default value used for $collections can be obtained by calling 
    <code>xdmp:default-collections()</code>.
  </apidoc:param>
  <apidoc:param name="quality" type="xs:int?" optional="true">
    The quality of this document.  A positive value increases 
    the relevance score of the document in text search functions.  
    The converse is true for a negative value.  The default value is 0.
  </apidoc:param>
  <apidoc:param name="forest-ids" type="xs:unsignedLong*" optional="true">
    Specifies the ID of the forest in which this document is inserted.  
    If the document already exists in the database and if $forest-ids is
    not specified, it will remain in its existing forest.  If no such 
    forest exists or if no such forest is attached to the context database, 
    an error is raised.  If multiple forests are specified, the document 
    is inserted into one of the specifed forests.
  </apidoc:param>
    </apidoc:params>
    <apidoc:return>empty-sequence()</apidoc:return>
    <apidoc:usage>This function has similar semantics to 
	    <code>xdmp:document-insert</code>. If a document already exists 
	    at one of the specified URIs, the function replaces the contents 
	    of the existing documents with the specified content.  In addition 
	    to replacing the content, <code>ooxml:package-parts-insert</code> 
	    replaces any permissions, collections, and quality with the ones 
	    specified (or with the default 
  values for these parameters, if not explicitly specified).  Also, if a 
  properties document exists at the same URI, that properties document 
  (including any content it contains) is preserved.
    
    </apidoc:usage>
        <apidoc:example><pre xml:space="preserve"><![CDATA[
xquery version "1.0-ml";
import module namespace ooxml= "http://marklogic.com/openxml" 
               at "/MarkLogic/openxml/package.xqy";

let $dir := "/my/office/docs/"
let $pkg := xdmp:document-get("c:/tmp/test.docx")
let $uris := ooxml:package-uris($pkg)
let $parts := ooxml:package-parts($pkg)
return ooxml:package-parts-insert($dir, $uris, $parts)
=> The empty sequence.  The documents are inserted
into the database under the /my/office/docs/ directory.

  ]]></pre>
  </apidoc:example>
  </apidoc:function>
</apidoc:module>
