Further XQdoc and comments

git-svn-id: https://seewhatithink.svn.sourceforge.net/svnroot/seewhatithink/trunk@52 4bd0fe05-8733-449a-9ecc-25b3248bf382
jocrow · Sep 12, 2011 · 34d9b39 · 34d9b39
1 parent eac343e
commit 34d9b39
Show file tree

Hide file tree

Showing 3 changed files with 226 additions and 9 deletions.
diff --git a/applications/whatithink.com/db/xmlss/whatithink.com/format-xml-as-html.xslt b/applications/whatithink.com/db/xmlss/whatithink.com/format-xml-as-html.xslt
@@ -1 +1,30 @@
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0"><xsl:output method="xhtml" version="1.1" media-type="text/html" encoding="UTF-8" indent="yes" omit-xml-declaration="no"/><xsl:include href="xml-to-html.xslt"/><xsl:template match="/"><xsl:apply-templates select="." mode="xml-to-html"/></xsl:template></xsl:stylesheet>
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="2.0">
+    <!--
+        Copyright 2011 Adam Retter
+        
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+        http://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+    -->
+
+    <!--
+        This module converts an XML document into XHTML for display purposes
+        
+        @author Adam Retter <adam.retter@googlemail.com>
+        @version 201109122029
+    -->
+    <xsl:output method="xhtml" version="1.1" media-type="text/html" encoding="UTF-8" indent="yes" omit-xml-declaration="no"/>
+    <xsl:include href="xml-to-html.xslt"/>
+    <xsl:template match="/">
+        <xsl:apply-templates select="." mode="xml-to-html"/>
+    </xsl:template>
+</xsl:stylesheet>
diff --git a/applications/whatithink.com/db/xmlss/whatithink.com/mylist-to-fo.xslt b/applications/whatithink.com/db/xmlss/whatithink.com/mylist-to-fo.xslt
@@ -1,4 +1,79 @@
-<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:xd="http://www.oxygenxml.com/ns/doc/xsl" exclude-result-prefixes="xs" version="2.0"><xd:doc scope="stylesheet"><xd:desc><xd:p><xd:b>Created on:</xd:b> June 2, 2011</xd:p><xd:p><xd:b>Author:</xd:b> Adam Retter</xd:p><xd:p>adam.retter@google.com</xd:p><xd:p>http://www.adamretter.org.uk</xd:p></xd:desc></xd:doc><xsl:param name="logoUri"/><xsl:param name="bgUri"/><xsl:output indent="yes"/><xsl:template match="atom:feed"><fo:root font-size="12pt"><fo:layout-master-set><fo:simple-page-master master-name="A4" page-width="297mm" page-height="210mm" margin-top="1cm" margin-bottom="1cm" margin-left="1cm" margin-right="1cm"><fo:region-body margin-top="5.2cm" margin-left="1cm" margin-bottom="1cm" margin-right="1cm"/><fo:region-before extent="4.2cm"/><fo:region-after extent="1cm"/><fo:region-start extent="1cm"/><fo:region-end extent="1cm"/></fo:simple-page-master></fo:layout-master-set><fo:page-sequence master-reference="A4"><fo:static-content flow-name="xsl-region-before"><fo:block text-align="center" vertical-align="top"><fo:block background-image="url({$bgUri})" background-repeat="repeat-x"><fo:external-graphic src="url({$logoUri})" content-height="scale-to-fit" content-width="scale-to-fit" scaling="uniform" height="40mm"/>
-                            <!-- fo:external-graphic src="url({$logoUri})" content-height="scale-to-fit" content-width="scale-to-fit" scaling="uniform" height="18mm"/ --></fo:block></fo:block><fo:block text-align="left" margin-top="0.2cm" font-size="12pt" border-bottom-width="thin" border-bottom-style="solid" border-bottom-color="black"><xsl:value-of select="/atom:feed/atom:author/atom:name"/>'s List
-                    </fo:block></fo:static-content><fo:static-content flow-name="xsl-region-after"><fo:block font-family="verdana" font-size="8pt" color="grey" text-align="center">
-                        Page <fo:page-number/></fo:block></fo:static-content><fo:flow flow-name="xsl-region-body"><xsl:apply-templates select="atom:entry"/></fo:flow></fo:page-sequence></fo:root></xsl:template><xsl:template match="atom:entry"><fo:block margin-top="0.25cm"><xsl:apply-templates/></fo:block></xsl:template><xsl:template match="atom:title"><fo:block font-size="10pt" color="blue" font-weight="bold"><xsl:value-of select="."/></fo:block></xsl:template><xsl:template match="atom:summary"><fo:block font-size="9pt" font-family="verdana"><xsl:value-of select="."/></fo:block></xsl:template><xsl:template match="atom:id"/><xsl:template match="atom:updated"/></xsl:stylesheet>
+<?xml version="1.0" encoding="UTF-8"?>
+<xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" xmlns:atom="http://www.w3.org/2005/Atom" xmlns:xs="http://www.w3.org/2001/XMLSchema" xmlns:fo="http://www.w3.org/1999/XSL/Format" xmlns:xd="http://www.oxygenxml.com/ns/doc/xsl" exclude-result-prefixes="xs" version="2.0">
+    <!--
+        Copyright 2011 Adam Retter
+        
+        Licensed under the Apache License, Version 2.0 (the "License");
+        you may not use this file except in compliance with the License.
+        You may obtain a copy of the License at
+        
+        http://www.apache.org/licenses/LICENSE-2.0
+        
+        Unless required by applicable law or agreed to in writing, software
+        distributed under the License is distributed on an "AS IS" BASIS,
+        WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+        See the License for the specific language governing permissions and
+        limitations under the License.
+    -->
+
+    <!--
+        This module converts a users list of atom entries into FO for render to PDF.
+        
+        @author Adam Retter <adam.retter@googlemail.com>
+        @version 201109122029
+    -->
+    <xsl:param name="logoUri"/>
+    <xsl:param name="bgUri"/>
+    <xsl:output indent="yes"/>
+    <xsl:template match="atom:feed">
+        <fo:root font-size="12pt">
+            <fo:layout-master-set>
+                <fo:simple-page-master master-name="A4" page-width="297mm" page-height="210mm" margin-top="1cm" margin-bottom="1cm" margin-left="1cm" margin-right="1cm">
+                    <fo:region-body margin-top="5.2cm" margin-left="1cm" margin-bottom="1cm" margin-right="1cm"/>
+                    <fo:region-before extent="4.2cm"/>
+                    <fo:region-after extent="1cm"/>
+                    <fo:region-start extent="1cm"/>
+                    <fo:region-end extent="1cm"/>
+                </fo:simple-page-master>
+            </fo:layout-master-set>
+            <fo:page-sequence master-reference="A4">
+                <fo:static-content flow-name="xsl-region-before">
+                    <fo:block text-align="center" vertical-align="top">
+                        <fo:block background-image="url({$bgUri})" background-repeat="repeat-x">
+                            <fo:external-graphic src="url({$logoUri})" content-height="scale-to-fit" content-width="scale-to-fit" scaling="uniform" height="40mm"/>
+                            <!-- fo:external-graphic src="url({$logoUri})" content-height="scale-to-fit" content-width="scale-to-fit" scaling="uniform" height="18mm"/ -->
+                        </fo:block>
+                    </fo:block>
+                    <fo:block text-align="left" margin-top="0.2cm" font-size="12pt" border-bottom-width="thin" border-bottom-style="solid" border-bottom-color="black">
+                        <xsl:value-of select="/atom:feed/atom:author/atom:name"/>'s List
+                    </fo:block>
+                </fo:static-content>
+                <fo:static-content flow-name="xsl-region-after">
+                    <fo:block font-family="verdana" font-size="8pt" color="grey" text-align="center">
+                        Page <fo:page-number/>
+                    </fo:block>
+                </fo:static-content>
+                <fo:flow flow-name="xsl-region-body">
+                    <xsl:apply-templates select="atom:entry"/>
+                </fo:flow>
+            </fo:page-sequence>
+        </fo:root>
+    </xsl:template>
+    <xsl:template match="atom:entry">
+        <fo:block margin-top="0.25cm">
+            <xsl:apply-templates/>
+        </fo:block>
+    </xsl:template>
+    <xsl:template match="atom:title">
+        <fo:block font-size="10pt" color="blue" font-weight="bold">
+            <xsl:value-of select="."/>
+        </fo:block>
+    </xsl:template>
+    <xsl:template match="atom:summary">
+        <fo:block font-size="9pt" font-family="verdana">
+            <xsl:value-of select="."/>
+        </fo:block>
+    </xsl:template>
+    <xsl:template match="atom:id"/>
+    <xsl:template match="atom:updated"/>
+</xsl:stylesheet>
diff --git a/applications/whatithink.com/db/xmlss/whatithink.com/mylist.xqm b/applications/whatithink.com/db/xmlss/whatithink.com/mylist.xqm
@@ -1,3 +1,27 @@
+(:
+ Copyright 2011 Adam Retter
+
+ Licensed under the Apache License, Version 2.0 (the "License");
+ you may not use this file except in compliance with the License.
+ You may obtain a copy of the License at
+
+     http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing, software
+ distributed under the License is distributed on an "AS IS" BASIS,
+ WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ See the License for the specific language governing permissions and
+ limitations under the License.
+:)
+
+(:~
+: This module manages a logged in Users list of
+: atom entries that they want to order as a book
+: and/or send to the printers
+:
+: @author Adam Retter <adam.retter@googlemail.com>
+: @version 201109122029
+:)
 xquery version "1.0";
 
 module namespace mylist = "http://whatithink.com/xquery/mylist";
@@ -18,6 +42,15 @@ import module namespace security = "http://whatithink.com/xquery/security" at "s
 
 declare variable $mylist:mylist-filename := "mylist.xml";
 
+(:~
+: Adds an atom entry to the users list
+:
+: @param entry
+:   The atom entry to add to the list
+:
+: @return
+:   true() if the entry was added to the list, false() otherwise
+:)
 declare function mylist:add($entry as document-node()) as xs:boolean {
     let $mylist := mylist:get-or-create() return
         if($mylist/mylist:list/mylist:entry/@ref = $entry/atom:entry/atom:id/text())then
@@ -28,6 +61,13 @@ declare function mylist:add($entry as document-node()) as xs:boolean {
         )
 };
 
+(:~
+: Generates an XHTML list of the current logged in users atom entries
+:
+: @return
+:   An XHTML list of the current logged in users atom entries,
+:   complete with hyperlinks to retrieve each entry
+:)
 declare function mylist:browse-all-entries() as element(xh:ul) {
     <xh:ul id="myEntryList">
     {
@@ -37,14 +77,22 @@ declare function mylist:browse-all-entries() as element(xh:ul) {
     </xh:ul>
 };
 
+(:~
+: Gets the current logged in users atom:entries from their list
+:
+: @return
+:   The current logged in users atom:entries from their list
+:)
 declare function mylist:get-entries() as element(atom:entry)* {
     for $list-entry in mylist:get-or-create()/mylist:list/mylist:entry return
         entry:get-entry-from-id($list-entry/@ref)/atom:entry
 };
 
-(:
-TODO - 
-    declare function mylist:as-atom-feed() as document-node(element(atom:feed))
+(:~
+: Gets the current logged in users list of atom:entries as an atom feed
+:
+: @return
+:   An atom feed of the currently logged in users atom:entries
 :)
 declare function mylist:as-atom-feed() as document-node() {
     document {
@@ -63,6 +111,13 @@ declare function mylist:as-atom-feed() as document-node() {
     }
 };
 
+(:~
+: Gets the document that holds the currently logged in users list.
+: If the document does not exist it will be created.
+:
+: @return
+:   The document which holds the users personal list of atom entries
+:)
 declare function mylist:get-or-create() as document-node() {
 
     let $mylist-uri := fn:concat(security:get-user-collection-path(), "/", $mylist:mylist-filename) return
@@ -75,15 +130,41 @@ declare function mylist:get-or-create() as document-node() {
                 fn:doc($mylist-uri)
 };
 
+(:~
+: Clears all entries from the currently logged in users list
+:)
 declare function mylist:clear() as empty() {
     let $mylist := mylist:get-or-create() return
         update delete $mylist/mylist:list/mylist:entry
 };
 
+(:~
+: Places an order with the Printers for
+: the contents of a list
+:
+: The list is uploaded by an admin
+: whom specifies the user. The list is
+: then ordered for that user.
+:
+: @param order-upload
+:   The Order wrapped in an order-upload element,
+:   with the following format - 
+:       <order-upload>
+:           <file xsi:type="xsd:base64Binary" filename="" media-type=""/>
+:               <for>
+:                   <username/>
+:               </for>
+:       </order-upload>
+:
+: @return
+:   true() if we could order the list, false() otherwise
+:)
 declare function mylist:order-from-xml($order-upload as element(order-upload)) as xs:boolean {
 
     (: decode the base64 uploaded file :)
     let $order := util:parse(util:base64-decode($order-upload/file)),
+
+    (: get the username of whom this order is for :)
     $for-username := $order-upload/for/username return
 
        let $order-for-user := mylist:replace-element($order/order:Order, <order:RequestId>{$for-username}</order:RequestId>) return
@@ -92,6 +173,23 @@ declare function mylist:order-from-xml($order-upload as element(order-upload)) a
 
 };
 
+(:~
+: Replaces one element with another.
+:
+: The function looks at the given $src element
+: and all child elements recursively
+: if the QName of the $replacement element
+: matches the element under comparisson then
+: it is replaced.
+:
+: @param src
+:   The element to replace or a container of the element to replace
+:
+: @param replacement
+:   The element to substitute
+:
+: @return the src with any replacements made
+:)
 declare function mylist:replace-element($src as element(), $replacement as element()) as element() {
     if(node-name($src) eq node-name($replacement))then
         $replacement
@@ -105,6 +203,15 @@ declare function mylist:replace-element($src as element(), $replacement as eleme
         }
 };
 
+(:~
+: Sends an Order to the Printers via REST
+:
+: @param order
+:   The order to send to the printers
+:
+: @return
+:   true() if the order was sent, false() otherwise
+:)
 declare function mylist:order($order as element(order:Order)) as xs:boolean {
     let $result := httpclient:post(
         $config:printer-webapp-restful-order-uri,
@@ -117,7 +224,13 @@ declare function mylist:order($order as element(order:Order)) as xs:boolean {
         $result/@statusCode eq "200"
 };
 
-declare function mylist:browse-all-orders() as element(xh:table) {
+(:~
+: Gets a list of all Orders for the currently logged in user
+: via REST from the Printers.
+:
+: @return an XHTML snippet describing the Orders from the Printers
+:)
+declare function mylist:browse-all-orders() as element() {
     let $my-orders := httpclient:get(
         xs:anyURI(fn:concat($config:printer-webapp-restful-order-status-uri, "?requestId=", security:get-username())),
         false(),