| Oracle® Retail POS Suite Implementation Guide, Volume 1 – Implementation Solutions Release 14.1 E54475-02 |
|
 Previous |
 Next |
| Oracle® Retail POS Suite Implementation Guide, Volume 1 – Implementation Solutions Release 14.1 E54475-02 |
|
Previous |
Next |
Receipt Builder is a tool that is used to maintain receipt formatting and content. Instead of the construction of receipt output existing in Java code, which requires Java programming knowledge to change, the construction of the receipt output is defined within easily edited XML files. The XML files can be displayed graphically and edited within the Receipt Builder editor or edited as plain text in any other editor. This externalizes the receipts in a way that is easily configurable and that does not require layers of code extensions. The XML contains a combination of static receipt elements that always print the same and other receipt elements that are dynamic. The dynamic elements print values obtained from Java objects that exist in memory at runtime. The XML also allows for a wide range of formatting of the obtained values in order to make them suitable for printing.
The Receipt Builder editor requires serialized (that is, persisted) sample data objects for the construction of new receipts. The data objects allow a developer to choose which Java methods are executed in order to obtain the data to print for a particular element. At Point-of-Service runtime, the object resides in memory and the new receipt printing framework executes the specified methods against the printing framework based upon the XML instructions. These serialized object files can be generated at Point-of-Service runtime.
Instructions on how to format the information into the fixed-width receipt printers is kept in XML blueprint files (also known as templates). These XML files are read at runtime and combined with the runtime in-memory objects to produce printable output. The Point-of-Service client caches the XML once it is read. Only if the client detects that the blueprint file has a newer timestamp or if a new blueprint is sent from Central Office does the client reread the XML.
|
Note: For more information, see the Oracle Retail Point-of-Service Receipt Builder Tool User Guide.This document is available through My Oracle Support. Access My Oracle Support at the following URL: Oracle Retail Point-of-Service Receipt Builder Tool User Guide (Doc ID: 1595733.1) |
The XML blueprints are installed at <source_directory>\applications\pos\deploy\client\receipts.
The Point-of-Service client caches all blueprints once read. Upon further printing, if the blueprint file's timestamp has changed to a newer timestamp, the XML is reread. Additionally, if the client receives new blueprints using FileTransfer then the cache is also cleared.
The following file is an example of an XML blueprint file that uses data from an object called "com.demo.Person". Various lines are printed to the receipt such as "Name:" and "Birth Date:"
Example 12-1 Example.bpt
<?xml version="1.0" encoding="UTF-8"?>
<blueprint id="receipt.bpt" copies="1">
<report name="Report" id="1">
<group id="99401936">
<line id="32962587">
<imageElement fileName="ReceiptLogo.jpg" idePath="/demo/bin/ReceiptLogo.jpg" id="25483246" justified="1" />
</line>
<line id="15081425">
<dateTimeElement formatter="Date.SHORT" prefix="(" suffix=")" id="4536570" />
<element text=" " id="24559530" stretch="true" />
<dateTimeElement formatter="Time.SHORT" id="6253254" />
</line>
</group>
<group id="1">
<line id="24595355">
<element text="Id手:" id="25255986" />
<methodElement id="10602994">
<method returns="String" name="getId" class="com.demo.Person" />
</methodElement>
<element text="Name:" id="1" justified="2" stretch="true" />
<methodElement id="26482774">
<method returns="String" name="getName" class="com.demo.Person" />
</methodElement>
</line>
<line id="17089909">
<element text="Height:" id="18455598" />
<methodElement id="6311384">
<method returns="double" name="getHeight" class="com.demo.Person" />
</methodElement>
<methodElement id="13946325">
<method returns="String" name="getLocalizedSalutation" class="com.demo.Person" param="Locale" />
</methodElement>
</line>
<line id="4171180">
<element text="Age:" id="19840829" />
<methodElement formatter="0#New|1#Printed|2#Partial|3#Filled|4#Canceled|5#Completed|6#Voided" id="32596007" escapeSequence="\|bC\|iC">
<method returns="int" name="getAge" class="com.demo.Person" />
</methodElement>
<methodElement formatter="#0;(#0)" id="16747213">
<method returns="BigDecimal" name="getBigNumber" class="com.demo.Person" />
</methodElement>
</line>
<line id="9818046">
<element text="Sex:" id="14253732" fillChar="." stretch="true" />
<methodElement valuePrintedWhenFalse="female" valuePrintedWhenTrue="male" id="6446153" stretch="true">
<method returns="boolean" name="isSex" class="com.demo.Person" />
</methodElement>
</line>
<line id="24763620">
<element text="Salary:" id="15358832" />
<methodElement id="25586725">
<method returns="CurrencyDecimal" name="getSalary" class="com.demo.Person" />
</methodElement>
</line>
<line id="26542488">
<element text="Nick name:" id="19086511" />
<methodElement prefix=""" suffix=""" id="27541747">
<method returns="String" name="getNickname" class="com.demo.Person" />
</methodElement>
</line>
<line id="26980954">
<element text="Birth Date:" id="26154958" />
<methodElement formatter="Date.MEDIUM" id="12290792">
<method returns="Date" name="getBirthDate" class="com.demo.Person" />
</methodElement>
</line>
<line id="14314484">
<element text="Spouse:" id="16920240" />
<methodElement fixedWidth="20" id="15369072" fillChar="%" justified="2">
<method returns="Person" name="getSpouse" class="com.demo.Person">
<method returns="String" name="getName" class="com.demo.Person" />
</method>
</methodElement>
</line>
<line id="31820984">
<element text="" id="5367480" fillChar="_" stretch="true" />
</line>
<line id="24744797" />
<line id="12182618">
<element text="Relatives" id="4387753" />
</line>
<line id="4126736">
<element text="" id="19625657" fillChar="-" stretch="true" />
</line>
</group>
<group id="18541827">
<line id="21925102" dependsOnPresenceOf="28217713">
<element text=" Name:" id="8930268" />
<methodElement id="28217713">
<method returns="List<Person>" name="getRelatives" class="com.demo.Person">
<method returns="java.lang.Object[]" name="toArray" class="java.util.List">
<method returns="String" name="getName" class="com.demo.Person" />
</method>
</method>
</methodElement>
</line>
<line id="421988">
<element text=" Age:" id="20121217" dependsOnPresenceOf="28007313" />
<methodElement fixedWidth="4" formatter="##0.##E0" printedWhenValueZero="false" id="28007313">
<method returns="List<Person>" name="getRelatives" class="com.demo.Person">
<method returns="java.lang.Object[]" name="toArray" class="java.util.List">
<method returns="int" name="getAge" class="com.demo.Person" />
</method>
</method>
</methodElement>
</line>
</group>
<group id="3818530">
<line id="9949215">
<element text=" " id="4513709" />
</line>
<line id="14721926">
<element text="Should not print on the third copy" id="19625657" dependsOnPresenceOf="23450220" />
</line>
<line id="1043272">
<methodElement fixedWidth="42" id="19570995" printedAsBarcode="true" justified="1">
<method returns="int" name="hashCode" class="java.lang.Object" />
</methodElement>
</line>
</group>
<dependsOn returns="boolean" name="isSex" class="com.demo.Person" />
</report>
<linkReport documentType="footer" idePath="/demo/receipts/footer.bpt" id="12856042" />
</blueprint>
The following XSD defines the structure of the XML blueprints:
Example 12-2 Receipt Builder XSD
<?xml version="1.0" encoding="UTF-8"?>
<schema xmlns="http://www.w3.org/2001/XMLSchema"
targetNamespace="http://www.example.org/receipt"
xmlns:tns="http://www.example.org/receipt"
elementFormDefault="qualified">
<element name="blueprint" type="tns:blueprintType" />
<complexType name="blueprintType">
<annotation><documentation>
This element represents the a single receipt blueprint. A blueprint
is the instructions for single transactional interaction with the
Point-of-Service printer. A blueprint can consist of one to many reports.
</documentation></annotation>
<choice>
<element name="report" type="tns:reportType" minOccurs="0" maxOccurs="unbounded" />
<element name="linkReport" type="tns:linkReportType" minOccurs="0" maxOccurs="unbounded" />
</choice>
<attribute name="id" type="string" use="required" />
</complexType>
<complexType name="abstractReportType">
<annotation><documentation>
This is a super type for generic reports or linkReports. There can
be one or many reports for a single receipt blueprint. The receipt
paper is cut after the report depending on the attribute cutPaper.
A report can be repeated for multiple copies depending on the
attribute copies. It is possible for an entire report to not be
printed based upon if the results of the dependsOn element are null
or false.
</documentation></annotation>
<sequence>
<element name="dependsOn" type="tns:methodType" minOccurs="1" maxOccurs="1"/>
</sequence>
<attribute name="id" type="string" use="required" />
<attribute name="copies" type="int" default="1" />
<attribute name="cutPaper" type="boolean" default="true" />
</complexType>
<complexType name="reportType">
<annotation><documentation>
A report is a collection of receipt groups where usually the receipt
paper is cut after the report. The name of the report is currently
only for informational purposes.
</documentation></annotation>
<complexContent>
<extension base="tns:abstractReportType">
<sequence>
<element name="group" type="tns:groupType" minOccurs="1" maxOccurs="unbounded" />
</sequence>
<attribute name="name" type="string" />
</extension>
</complexContent>
</complexType>
<complexType name="linkReportType">
<annotation><documentation>
A "link report" is meant as a signal to print an external blueprint
that can be identified by the documentType. It does not contain
groups.
</documentation></annotation>
<complexContent>
<extension base="tns:abstractReportType">
<attribute name="documentType" type="string" use="required" />
</extension>
</complexContent>
</complexType>
<complexType name="groupType">
<annotation><documentation>
A group is a logical collection of receipt lines that can be
repeated if they contain an iteration or array. The group contains
lines that are printed in order. If one of the lines contains a
method stack from a methodElement and that method stack has a method
call which executes on an array or collection then the entire group
of lines will be repeated for the length or size of the iteration.
NOTE: including method stacks which contain different arrays does
not make sense and will not work as expected. MethodElements within
the group should reference the same array or collection.
Sub-iterations, i.e. arrays within arrays can be handled, but only
the line that contains the sub-array will be repeated for the length
of that array. The the entire group will repeat for the outer array.
</documentation></annotation>
<choice>
<element name="line" type="tns:lineType" />
</choice>
<attribute name="id" type="string" use="required" />
</complexType>
<complexType name="lineType">
<annotation><documentation>
A line is a collection of elements that ends with a carriage return.
Lines will be repeated (even within a repeating group) if they
contain a methodElement which executes on an array within an array.
It is possible for an entire line including the carriage return to
not be printed based upon if the results of the dependsOnPresenceof
methodElement are null or false. The value is the id of a
methodElement in this group.
</documentation></annotation>
<choice>
<element name="element" type="tns:elementType" />
<element name="copyElement" type="tns:copyElementType" />
<element name="imageElement" type="tns:imageElementType" />
<element name="methodElement" type="tns:methodElementType" />
<element name="dateTimeElement" type="tns:dateTimeElementType" />
</choice>
<attribute name="id" type="string" use="required" />
<attribute name="dependsOnPresenceof" type="string" />
</complexType>
<!-- Parent type for all elements. -->
<complexType name="abstractElementType">
<annotation><documentation>
Provides a super type for attributes that are the same between all
elements. An element's output can be affected by the JPOS
escapeSequence attribute. An element can be printed as a bar code
for scanning depending on the printedAsBarCode attribute. The
attribute justify controls whether the text in the element is
justified left "0", center "1", or right "2" in its space.
It is possible for an element to not be printed based upon if the
results of the dependsOnPresenceof attribute are true or false. The
value is the id of a methodElement in this group.
</documentation></annotation>
<attribute name="id" type="string" use="required" />
<attribute name="dependsOnPresenceof" type="string" />
<attribute name="escapeSequence" type="string" />
<attribute name="printedAsBarCode" type="boolean" default="false" />
<attribute name="justified" type="int" />
</complexType>
<!-- Type for static text elements. -->
<complexType name="elementType">
<annotation><documentation>
Represents an element in the receipt report that can display static
text and its width can be stretched to take up extra space.
</documentation></annotation>
<complexContent>
<extension base="tns:abstractElementType">
<attribute name="text" type="string" use="required" />
<attribute name="stretch" type="boolean" default="false" />
</extension>
</complexContent>
</complexType>
<!-- Type for text elements that change for each copy of a report. -->
<complexType name="copyElementType">
<annotation><documentation>
Represents an element in the receipt report that can display text
that changes based upon the index of the current report being
printed and its width can be stretched to take up extra space.
</documentation></annotation>
<complexContent>
<extension base="tns:abstractElementType">
<sequence>
<element name="copyText" type="string" minOccurs="1" maxOccurs="unbounded" />
</sequence>
<attribute name="stretch" type="boolean" default="false" />
</extension>
</complexContent>
</complexType>
<!-- A static element that displays an image. -->
<complexType name="imageElementType">
<annotation><documentation>
Represents an element in the receipt report that can display an
image. The image file is expected to be in the present working
directory of the application, e.g. bin/. The image will be centered
in its line and will be the only element in its line. The idePath
specified is only useful to the Receipt Builder plug-in for finding
the file in Eclipse.
</documentation></annotation>
<complexContent>
<extension base="tns:abstractElementType">
<attribute name="fileName" type="string" use="required" />
<attribute name="idePath" type="string"/>
</extension>
</complexContent>
</complexType>
<!-- Parent type for object and method elements. -->
<complexType name="javaElementType">
<annotation><documentation>
Represents an element in the receipt report that displays text based
upon the value of a Java object. The output can be formatted with a
space, prefix and suffix, given a fixed width padded by spaces or
given a format pattern string that conforms to Java types:
java.text.SimpleDateFormat, java.text.DecimalFormat,
java.swing.text.MaskFormatter, or java.text.ChoiceFormat.
</documentation></annotation>
<complexContent>
<extension base="tns:abstractElementType">
<attribute name="precededBySpace" type="boolean" default="true" />
<attribute name="fixedWidth" type="int" />
<attribute name="formatter" type="string" />
<attribute name="prefix" type="string" />
<attribute name="suffix" type="string" />
</extension>
</complexContent>
</complexType>
<!-- An element that specifies the printing of the current date/time. -->
<complexType name="dateTimeElementType">
<annotation><documentation>
Represents an element in the receipt report that displays the
current date or time. The output can be formatted by
java.text.SimpleDateFormat.
</documentation></annotation>
<complexContent>
<extension base="tns:javaElementType"/>
</complexContent>
</complexType>
<!-- An element that contains the execution of of a stack of methods. -->
<complexType name="methodElementType">
<annotation><documentation>
Represents an element in the receipt report that displays the
value of a method call. If the method returns a boolean, then
specific values can be printed instead of "true" or "false". If the
element should not be printed when the output is null or empty
string, then printedWhenLengthZero should be false. If the output is
a number that should not be printed when it is zero, then
printedWhenValueZero should be false.
</documentation></annotation>
<complexContent>
<extension base="tns:javaElementType">
<sequence>
<element name="method" type="tns:methodType" minOccurs="1" maxOccurs="1"/>
</sequence>
<attribute name="valuePrintedWhenFalse" type="string" default="false" />
<attribute name="valuePrintedWhenTrue" type="string" default="true" />
<attribute name="printedWhenValueZero" type="boolean" default="true" />
<attribute name="printedWhenLengthZero" type="boolean" default="false" />
</extension>
</complexContent>
</complexType>
<!-- Information of a method call. -->
<complexType name="methodType">
<annotation><documentation>
This is a method in a method call stack. It can have a child method.
</documentation></annotation>
<sequence>
<element name="method" type="tns:methodType" minOccurs="1" maxOccurs="1"/>
</sequence>
<attribute name="returns" type="string" use="required" />
<attribute name="name" type="string" use="required" />
<attribute name="param" type="string" use="optional" />
<attribute name="class" type="string" use="required" />
</complexType>
</schema>
The following information aids in configuring the receipt builder application.
In <source_directory>\applications\pos\deploy\client\config\conduit\ClientConduit.xml, the manager for PrintableDocumentManager should be set to BlueprintedDocumentManager.
<MANAGER name="PrintableDocumentManager"
package="oracle.retail.stores.pos.receipt.blueprint"
class="BlueprintedDocumentManager">
<PROPERTY propname="configScript"
propvalue="classpath://config/manager/BlueprintedDocumentManager.xml" />
</MANAGER>
|
Note: Ensure<source_directory>\applications\pos\deploy\client\config\manager\BlueprintedDocumentManager.xml is present and configured. |
The BlueprintedDocumentManager takes a configuration file location as a property value. The default value is specified above. This configuration file can specify the flag of whether the beans are persisted at print time. The other property is the directory the receipt blueprints can be found in. This is the same directory in which the persisted beans are placed.
In this configuration file, the base blueprint file name is mapped to the document type, enabling a different blueprint file to be printed for the specified document type. For example, if a different sale receipt is to be printed other than the released version, a different file name such as MySaleReceipt.bpt can be specified. Note that the locale-specific naming convention still takes place. This means that on an American English Point-of-Service client, the file SaleReceipt_en.bpt is searched first, followed by SaleReceipt_en.bpt, and then SaleReceipt.bpt.
<RECEIPT type="OrderReceipt" fileName="OrderReceipt.bpt" />
<RECEIPT type="RedeemReceipt" fileName="RedeemReceipt.bpt" />
<RECEIPT type="SaleReceipt" fileName="SaleReceipt.bpt" />
<RECEIPT type="SendGiftReceipt" fileName="SendGiftReceipt.bpt" />
The implementation of BlueprintedReceipt is set by Spring. Changing this class can change how the blueprint instructions are used to create printer output.
This setting can be found in the ApplicationContext.xml file found in the pos/config/context directory.
<!-- Blueprint receipt printing. Class must extend oracle.retail.stores.pos.receipt.blueprint.BlueprintedReceipt -->
<bean id="application_BlueprintedReceipt" class= "oracle.retail.stores.pos.receipt.blueprint.BlueprintedReceipt"
lazy-init="true"/>
The following information describes updating messages on receipts.
There are two ways to update the legal statement of liability. One is to simply change the text "Legal statement of liability" to that which is desired. However, if the text is changed to "New legal statement of liability" the results would be as follows:
Sale New legal statement of liability
Return New legal statement of liability
Layaway New legal statement of liability
Exchange New legal statement of liability
Note how Sale, Return, Layaway and Exchange seem to be hard-coded. Plus, they all share the same text. Below is a snippet of how CreditSignatureSlipReceipt_en.bpt would look for the above:
<line id="12894866">
<methodElement formatter="1#Sale|2#Return|5#Exchange|18#House Account Payment|19#Layaway" id="31782456">
<method returns="int" name="getTransactionType" class="oracle.retail.stores.pos.receipt.ReceiptParameterBeanIfc" />
</methodElement>
<element text=" New legal statement of liability" id="29789630" />
</line>
The second way to change the text is to add the new text in place of Sale, Return, Layaway, Exchange, and so forth, as shown in the following example:
<line id="12894866">
<methodElement formatter="1#Sale Sig Slip Legal Statement|2#Return Sig Slip Legal Statement|5#Exchange Sig Slip Legal Statement|18#House Account Sig Slip Legal Statement|19#Layaway Sig Slip Legal Statement" id="31782456">
<method returns="int" name="getTransactionType" class="oracle.retail.stores.pos.receipt.ReceiptParameterBeanIfc" />
</methodElement>
<element text="" id="29789630" />
</line>
Note that the original element text in this example has been replaced by just "" (this element can be removed entirely). The advantage to this method is that the user can specify custom text for each transaction type, as well as eliminate the words Sale, Return, Exchange, and so forth, in the statement if they so desire.
Item Level Receipt Messages (ILRM) informs the cashier or the customer about the item in the Sell Item screen. This utility facilitates Item level messages on the screen, providing information to the cashier and the customer about the product or about certain attributes associated with the item. It also provides a facility to print the Item messages on the receipt either below the item or at the footer. Different messages can be configured for different types of receipts, or depending on whether the item is being sold or returned.
A rebate receipt is printed only if a rebate message exists for a given item. The blueprint is called RebateReceipt.bpt. If the item message exists, the XML Receipt Framework invokes the getItemMessage() method from PLUItem object and displays the rebate message. The item related information invokes the same methods as invoked by the item information Group in SaleReceipt.bpt.
