<sect1 id="mail-merge"><title>Mail Merge</title>
<para>&kword; has the ability to use data from an outside database (or internal database) to <emphasis>personalize</emphasis> your 
documents for individual members/clients/friends.</para>
<para>This section of the manual will cover all aspects of creating, merging and printing documents that are specific to &kword;.  This 
manual will not cover:</para>
<itemizedlist>
<listitem><para>Creating an external database.</para></listitem>
<listitem><para>Security issues regarding databases.</para></listitem>
<listitem><para>Detailed instructions on SQL.  It is assumed you have some knowledge regarding SQL if you are using a 
SQL database for your data source.</para></listitem>
<listitem><para>Accessing the network or internet.</para></listitem>
</itemizedlist>

<para>For answers to these questions, other documentation is available on the internet that is specific to the software you have chosen.</para>

<para>If you want to use the internal database of &kword;, click <link linkend="mail-merge-internal">here</link>.</para>

<sect2 id="mail-merge-sql">
<title>Using an outside database (SQL) to create documents</title>
<para>&kword; has the ability to use several of the most popular open source databases as a source of data for personalized documents.</para>
<note><para>In order to access an outside database using SQL, your machine needs to have the appropriate database module compiled 
into your copy of QT.</para>
<para>For more information see the <link linkend="installation">installation section of this documentation</link>.</para></note>
<para>The database can be located on the same machine as &kword;, or on any computer which is accessable through your computer 
network or the internet.</para>
<para>In order to use the database, you must know the following information:</para>
<itemizedlist>
<listitem><para>Name of the database</para></listitem>
<listitem><para>Host name/IP address of the computer the database is located on</para></listitem>
<listitem><para>The port address on the specified computer granting SQL access</para></listitem>
<listitem><para>A valid user name for the database</para></listitem>
<listitem><para>A valid password for the user name</para></listitem>
</itemizedlist>

<para>If you have all this information at your finger tips, you are ready to proceed.</para>
<para>Using an outside database to create personalized documents is a three step process:</para>
<orderedlist>
<listitem><para><link linkend="mail-merge-sql-data">Connect to the database and select your query.</link></para></listitem>
<listitem><para><link linkend="mail-merge-fields">Insert the merge fields</link> to tell &kword;
where to insert the database information</para></listitem>
<listitem><para><link linkend="mail-merge-print">Print</link> the personalized documents.</para></listitem>
</orderedlist>

<sect3 id="mail-merge-sql-data">
<title>Locate the database and query the records.</title>
<para>To begin, select <menuchoice>
<guimenu>Tools</guimenu><guimenuitem>Configure Mail Merge...</guimenuitem></menuchoice> from
the menubar. A dialog box will appear.</para>

<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="mmerge1.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Click on <guibutton>Open Existing...</guibutton>.  Another small dialog will appear.</para>
<para>There is currently only one option in this dialog box (<guilabel>QT-SQL source</guilabel>). Click on
<guibutton>OK</guibutton>.  A new dialog box will appear.<anchor id="mail-merge-login"/></para>

<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="mmergesql1.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Enter the URL or IP address of the computer that holds the database in the text box labeled <guilabel>Hostname:</guilabel>.</para>
<para>Select the correct driver from the dropdown box labeled <guilabel>Driver:</guilabel>.  </para>
<para>Enter the database name you were provided in the text box labeled <guilabel>Database name:</guilabel> and a
user name in the text box labeled <guilabel>Username:</guilabel>.</para>
<para>If the database access is through a port other than the default port enter that port number in the text box labeled 
<guilabel>Port:</guilabel>.</para>
<tip><para>If you are going to be using this database at other times, you can click on the button labeled
<guibutton>Keep settings</guibutton>. &kword; will ask for a descriptive name.</para>
<para>When you want to restore these settings on future sessions, simply select the descriptive name from the dropdown box in the 
upper left of the dialog box.</para>
</tip>
<para>When all information is correct, click <guibutton>OK</guibutton>.  &kword; will ask you for a password to that database.  Enter 
the password in the text box, and click <guibutton>OK</guibutton>.</para>
<para>This dialog box will re-appear.</para>

<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="mmerge1.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Click on <guibutton>Edit Current...</guibutton>.  Another dialog will appear.</para>

<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="mmergesql2.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>This dialog is designed to help you enter and test your database query.  The dialog is divided into three
sections:  Database information, Query information and Query line.</para>
<para>The database information section is labeled <guilabel>Information</guilabel> and consists of two combo boxes.  The
left combo box (<guilabel>Available tables</guilabel>) gives you a list of all available tables within the current database.
Select the desired table from the list by clicking on the table name with the &LMB;.  
A list of all available fields from that table will appear in the right combo box.</para>
<para>The query line is a text box located near the bottom of the dialog labeled <guilabel>Query</guilabel>.  Simply type your 
SQL query into this text box and click <guibutton>Execute</guibutton>.  &kword; will query the database and return the specified query
in tabular format in the <guilabel>Query result</guilabel> box.  You can alter, or edit your query on the query line and each time you 
click <guibutton>Execute</guibutton>, the new query results will appear.</para>
<note><para>&kword; does not limit your query strings.  They can be simple and straight forward:</para>
<para><userinput>select * from eMail</userinput></para>
<para>Or complex multitable queries:</para>
<para><userinput>select eMail.FirstName, eMail.LastName, eMail.address, data.Birthday, 
data.EyeColour from eMail, data where data.FirstName=eMail.FirstName and 
data.LastName=eMail.LastName
</userinput></para>
<para></para>
<para></para></note>
<para>Clicking <guibutton>Setup</guibutton>, will allow you to <link linkend="mail-merge-login">log into a different database</link>.</para>
<para>When you have the correct query in the <guilabel>Query</guilabel> text box, click <guibutton>OK</guibutton> to select that query.
</para>
<para>This will return you to the mail merge main dialog box.</para>

<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="mmerge1.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Click <guibutton>Close</guibutton>.</para>

<para>Now that you have selected your data query, it is time to insert the merge fields in the document.  Click 
<link linkend="mail-merge-fields">here to continue</link>.</para>
</sect3>
</sect2>

<sect2 id="mail-merge-internal">
<title>Using an internal representation of tabular data to create documents</title>
<para>For small sets of data, or when you do not currently have a database containing the merge data, &kword; 
offers you the ability to enter the data <emphasis>directly into &kword;</emphasis> in tabular form.  This internal data 
structure can then be used to create documents with this data inserted at predefined locations.</para>
<para>Using an internal representation of the data to create personalized documents is a three step process:</para>
<orderedlist>
<listitem><para><link linkend="mail-merge-internal-data">Enter the data</link> into &kword;</para></listitem>
<listitem><para><link linkend="mail-merge-fields">Insert the merge fields</link> to tell &kword;
where to insert the database information</para></listitem>
<listitem><para><link linkend="mail-merge-print">Print</link> the personalized documents.</para></listitem>
</orderedlist>
<para>After the data has been created once, you can go back and change the data as needed, and produce another set of
personalized documents from that data.</para>

<sect3 id="mail-merge-internal-data">
<title>Enter the data</title>
<para>To begin, select <menuchoice>
<guimenu>Tools</guimenu><guimenuitem>Configure Mail Merge...</guimenuitem></menuchoice> from
the menubar. A dialog box will appear.</para>

<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="mmerge1.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Click on <guibutton>Create New...</guibutton>.  Another small dialog will appear.</para>
<para>There is currently only one option in this dialog box <guilabel>Internal storage</guilabel>. Click on
<guibutton>OK</guibutton>.  A new dialog box will appear.</para>

<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="mmerge2.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>This is a record card for creating your tabular data file.  Along the top is a toolbar and the main part of the dialog is space to hold
your entry/data pairs.</para>
<sect4 id="mail-merge-internal-data-entry"><title>Defining the structure of your data table</title>
<para>First, we need to add one or more entries (merge fields).  This is accomplished by clicking the
<inlinemediaobject><imageobject>
<imagedata fileref="addentry.png" format="PNG" align="center"/></imageobject></inlinemediaobject> 
(<guilabel>Add entry</guilabel>)
button (third button from the right along the toolbar). A small dialog box will appear.  Type a descriptive name of your entry
in the dialog box (Name, Address, Balance Due, etc....). </para>
<note><para>This is for the name of the entry, not the data that is contained within the entry.</para></note>
<para>Click <guibutton>OK</guibutton>, and the entry is added to the card.</para>
<para>Repeat this process until all needed entries are visible on this first card.</para>
<para>If you want to delete an entry, simply click once on the entry name with the &LMB; and select <inlinemediaobject><imageobject>
<imagedata fileref="delentry.png" format="PNG" align="center"/></imageobject></inlinemediaobject>
(<guilabel>Remove entry</guilabel>). </para>
<warning><para>Be <emphasis>very</emphasis> sure you have selected the correct entry name.  Once you tell &kword; to delete 
the entry, the entry <emphasis>and all of the data within those entries will be deleted immediately</emphasis>.  You will not be
given the option to stop or reverse the process once it is begun.</para></warning>
<para></para>
</sect4>
<sect4 id="mail-merge-internal-data-value"><title>Entering the data into the table</title>
<para>Now that the structure of your data is defined, you can enter the data into your entries.</para>
<para>At the top of the dialog box, are 4 buttons surrounding a spin box.  The spin box gives the current record number.  All
records are numbered in the order they are added starting with number 1.  You can use the spin box to go directly to 
the desired record or you can use the arrows to graphically move
through the list of records.</para>

<informaltable>
<tgroup cols="2">
<thead>
<row><entry>button</entry><entry>Action</entry></row>
</thead><tbody>
<row><entry><inlinemediaobject><imageobject><imagedata fileref="beginning.png" format="PNG"/></imageobject></inlinemediaobject></entry><entry>Move directly to record one</entry></row>
<row><entry><inlinemediaobject><imageobject><imagedata fileref="back.png" format="PNG"/></imageobject></inlinemediaobject></entry><entry>Move back one record</entry></row>
<row><entry><inlinemediaobject><imageobject><imagedata fileref="forward.png" format="PNG"/></imageobject></inlinemediaobject></entry><entry>Move forward one record</entry></row>
<row><entry><inlinemediaobject><imageobject><imagedata fileref="end.png" format="PNG"/></imageobject></inlinemediaobject></entry><entry>Move to the last record in the dataset</entry></row>
</tbody>
</tgroup>
</informaltable>

<para>To enter the data, simply place the cursor in the text box to the right of the entry name, and type in the data. (&kword; uses 
<quote>No Value</quote> as the default value for all entries in newly created records.)</para>
<para>To add a record, click the 
<inlinemediaobject><imageobject>
<imagedata fileref="addrecord.png" format="PNG" align="center"/></imageobject></inlinemediaobject> button.</para>
<para>To delete a record, click the 
<inlinemediaobject><imageobject>
<imagedata fileref="delrecord.png" format="PNG" align="center"/></imageobject></inlinemediaobject> button.</para>
<warning><para>Be careful when you are deleting records.  Once deleted, the record can not be retrieved.</para></warning>
<para>Continue to enter all data until your dataset is complete.</para>  
<para>After your dataset is complete, click <guibutton>OK</guibutton> to 
save the changes to your dataset.  This will bring up the mail merge main dialog:</para>

<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="mmerge1.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Click <guibutton>Close</guibutton>.  Now it is time to insert the merge fields in the document.</para>

</sect4>

</sect3>

<sect3 id="mail-merge-fields">
<title>Insert merge fields in document</title>
<para>Now that &kword; knows the entries available in your data source, you can insert the merge fields into your document.</para>
<para>A merge field is a placeholder within the document.  This placeholder will be replaced in each personalized document with the
value of the entry for that individual record.</para>

<sect4 id="mail-merge-field-insert">
<title>Insert a merge field</title>
<para>To insert a merge field, place the cursor at the desired place in the document.  Select <menuchoice>
<guimenu>Insert</guimenu><guimenuitem>Variable</guimenuitem>
<guimenuitem>Mail Merge...</guimenuitem></menuchoice> from
the menubar.  A list of available entries will appear.  Select the desired entry, and click <guibutton>OK</guibutton>.</para>
<para>The merge field is inserted at the current cursor location.  The merge field is surrounded by brackets.</para>
<para>You can place the cursor in a new location in the document and insert another placeholder.  When you are done inserting placeholders, 
you can proceed to printing your document.</para>
</sect4>

<sect4 id="mail-merge-field-delete">
<title>Delete a merge field</title>
<para>To delete a merge field, simply place the cursor at the end of the merge field, and press the &Backspace; key.  The entire 
merge field will be deleted.</para>
<para></para>
</sect4>
</sect3>

<sect3 id="mail-merge-print">
<title>Previewing and printing the merged document</title>
<para>Once you have inserted all the merge fields you want, you are ready to preview and print the personalized documents.</para>
<sect4 id="mail-merge-print-preview">
<title>Preview your documents before printing</title>
<para>To preview your document select <menuchoice>
<guimenu>Tools</guimenu><guimenuitem>Configure Mail Merge...</guimenuitem></menuchoice> from
the menubar. A dialog box will appear.</para>

<screenshot>
<mediaobject>
<imageobject>
<imagedata fileref="mmerge1.png" format="PNG"/></imageobject>
</mediaobject>
</screenshot>

<para>Select <guilabel>Print Preview</guilabel>.  You will be able to see the final output of your personalized documents prior to 
printing.</para>
</sect4>
<sect4 id="mail-merge-print-printing">
<title>Print your personalized documents.</title>
<para>You print personalized documents using the same methods that you do to print traditional documents.  For more information on printing 
see the section on <link linkend="printing">Printing a Document</link>.</para>
</sect4>
</sect3>
</sect2>
</sect1>