path: root/doc/kword/mailmerge.docbook

<sect1 id="mail-merge">
<sect1info>
<authorgroup>
<author>
<firstname>Mike</firstname>
<surname>McBride</surname>
</author>
<!-- TRANS:ROLES_OF_TRANSLATORS -->
</authorgroup>
</sect1info>
<title>Mail Merge</title>
<indexterm><primary>mail merge</primary><secondary>introduction</secondary></indexterm>

<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>You can retreive your mail-merge data from a number of sources:  </para>
<itemizedlist>
<listitem><para>If you want to use an outside SQL database, click <link linkend="mail-merge-sql">here</link> for instructions.</para></listitem>
<listitem><para>If you want to use a &kspread; file for your data, click <link linkend="mail-merge-kspread">here</link>.</para></listitem>
<listitem><para>If you want use information from your &tde; Address Book, click <link linkend="mail-merge-ab">here</link>.</para></listitem>
<listitem><para>If you want to use the internal database of &kword;, click <link linkend="mail-merge-internal">here</link>.</para></listitem>
</itemizedlist>

<sect2 id="mail-merge-sql">
<title>Using an external SQL database as a data source</title>
<indexterm><primary>mail merge</primary><secondary>SQL databases</secondary></indexterm>

<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>

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

<para>Select <guilabel>QT-SQL Source</guilabel> and 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 driver named <guilabel>QMYSQL3</guilabel> from the combo 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 combo 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>&kword; will now ask if you want to replace your current data source with the source you have selected.  Click <guibutton>Yes</guibutton>. </para>
<para>You are now connected to the database.  Now you need to select the data from the database. This dialog box has re-appeared.  </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 Clients</userinput></para>
<para>Or complex multitable queries:</para>
<para><userinput>select Clients.FirstName, Clients.LastName, Clients.address, data.Birthday, 
data.EyeColour from eMail, data where data.FirstName=Clients.FirstName and 
data.LastName=Clients.LastName
</userinput></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-kspread">
<title>Using a &kspread; file as a data source</title>
<indexterm><primary>mail merge</primary><secondary>using &kspread; file</secondary></indexterm>

<para>&kword; can use data in a &kspread; document for personalizing documents.</para>
<note><para>In order to use this data, you only need to know the location of the &kspread; document and the worksheet (page) number the data is located on.</para></note>

<para>Using a &kspread; document to create personalized documents is a three step process:</para>
<orderedlist>
<listitem><para><link linkend="mail-merge-kspread-data">Select the file the data is located within.</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-kspread-data">
<title>Selecting the file that contains 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>Open Existing...</guibutton>.  Another small dialog will appear.</para>

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

<para>Select <guilabel>&kspread; Table Source</guilabel> from the drop down box labeled <guilabel>Available sources:</guilabel> and click on
<guibutton>OK</guibutton>.  A new dialog box will appear.</para>

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

<para>Enter the &URL; or file name of the &kspread; document in the text box labeled <guilabel>URL:</guilabel>.  You can type the file name 
directly into the text box, or click on the button with the blue folder and use the file dialog to select the &kspread; file.</para>
<para>Once you have selected the &kspread; document, the drop down box labeled <guilabel>Page number:</guilabel> will show you all the available pages or worksheets 
within the &kspread; document.  Select the page (or worksheet) that contains the mail merge data.</para>
<para>When all information is correct, click <guibutton>OK</guibutton>.  &kword; will ask you if you want to replace the current data source.  Click <guibutton>Yes</guibutton> to continue.</para>


<para>You will again see 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-ab">
<title>Using your &tde; Address book as a data source</title>
<indexterm><primary>mail merge</primary><secondary>using &tde; Address Book</secondary></indexterm>

<para>&kword; can use data in your address book for personalizing documents.</para>

<para>Using address book entries to create personalized documents is a three step process:</para>
<orderedlist>
<listitem><para><link linkend="mail-merge-ab-data">Select the people you want included in the mail merge.</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-ab-data">
<title>Select the people you want included</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>

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

<para>Select <guilabel>&tde; Addressbook Plugin</guilabel> from the drop down box labeled <guilabel>Available sources:</guilabel> and click on
<guibutton>OK</guibutton>.  A new dialog box will appear.</para>

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

<para>The dialog consists of two listboxes labeled <guilabel>Address Book</guilabel> and <guilabel>Selected Addresses</guilabel>.  By moving entries from your Address book to the <guilabel>Selected Addresses</guilabel> listbox, you will be including those entries in your merge document.  </para>
<para>To add an entry, select the entry in the left listbox by clicking with the &LMB;.  Then click <guibutton>Add</guibutton>.</para>
<para>To remove an entry, select the entry in the right listbox by clicking with the &LMB;.  Then click <guibutton>Remove</guibutton>.</para>
<tip><para>You can locate entries quickly by entering the first 2-3 letters of an entries name in the textbox labeled <guilabel>Filter on:</guilabel></para></tip>
<note><para>You can load the full address book application by clicking the <guibutton>Address Book...</guibutton> button.</para>
<para>You can also save a distribution list using the <guibutton>Save as Distribution List...</guibutton> button.  For more information on distribution lists, see the documentation on the &tde; Addressbook.</para></note>

<para>When you have selected all the entries and distribution lists you want, click <guibutton>OK</guibutton>.  &kword; will ask you if you want to replace the current data source.  Click <guibutton>Yes</guibutton> to continue.</para>


<para>You will again see 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>
<indexterm><primary>mail merge</primary><secondary>using &kword; data tables</secondary></indexterm>

<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>

</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 cannot 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>
<indexterm><primary>mail merge</primary><secondary>inserting merge fields</secondary></indexterm>

<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>
<indexterm><primary>mail merge</primary><secondary>deleting a merge field</secondary></indexterm>

<para>You can delete a merge field two ways.</para>

<itemizedlist>
<listitem><para>Place the cursor at the end of the merge field, and press the &Backspace; key. </para></listitem>
<listitem><para>Place the cursor at the beginning of the merge field, and press the <keycap>Delete</keycap> key. </para></listitem>
</itemizedlist>

</sect4>
</sect3>

<sect3 id="mail-merge-print">
<title>Previewing and printing the merged document</title>
<indexterm><primary>mail merge</primary><secondary>merging data and text</secondary></indexterm>

<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>Click <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>