Mike McBride mail mergeintroduction &kword; has the ability to use data from an outside database (or internal database) to personalize your documents for individual members/clients/friends. 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: Creating an external database. Security issues regarding databases. Detailed instructions on SQL. It is assumed you have some knowledge regarding SQL if you are using a SQL database for your data source. Accessing the network or Internet. For answers to these questions, other documentation is available on the Internet that is specific to the software you have chosen. You can retreive your mail-merge data from a number of sources: If you want to use an outside SQL database, click here for instructions. If you want to use a &kspread; file for your data, click here. If you want use information from your &kde; Address Book, click here. If you want to use the internal database of &kword;, click here. mail mergeSQL databases &kword; has the ability to use several of the most popular open source databases as a source of data for personalized documents. In order to access an outside database using SQL, your machine needs to have the appropriate database module compiled into your copy of QT. For more information see the installation section of this documentation. 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. In order to use the database, you must know the following information: Name of the database Host name/IP address of the computer the database is located on The port address on the specified computer granting SQL access A valid user name for the database A valid password for the user name If you have all this information at your finger tips, you are ready to proceed. Using an outside database to create personalized documents is a three step process: Connect to the database and select your query. Insert the merge fields to tell &kword; where to insert the database information. Print the personalized documents. To begin, select ToolsConfigure Mail Merge... from the menubar. A dialog box will appear. Click on Open Existing.... Another small dialog will appear. Select QT-SQL Source and click on OK. A new dialog box will appear. Enter the &URL; or IP address of the computer that holds the database in the text box labeled Hostname:. Select the driver named QMYSQL3 from the combo box labeled Driver:. Enter the database name you were provided in the text box labeled Database name: and a user name in the text box labeled Username:. If the database access is through a port other than the default port enter that port number in the text box labeled Port:. If you are going to be using this database at other times, you can click on the button labeled Keep settings.... &kword; will ask for a descriptive name. 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. When all information is correct, click OK. &kword; will ask you for a password to that database. Enter the password in the text box, and click OK. &kword; will now ask if you want to replace your current data source with the source you have selected. Click Yes. You are now connected to the database. Now you need to select the data from the database. This dialog box has re-appeared. Click on Edit Current.... Another dialog will appear. 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. The database information section is labeled Information and consists of two combo boxes. The left combo box (Available tables:) 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. The query line is a text box located near the bottom of the dialog labeled Query:. Simply type your SQL query into this text box and click Execute. &kword; will query the database and return the specified query in tabular format in the Query Result box. You can alter, or edit your query on the query line and each time you click Execute, the new query results will appear. &kword; does not limit your query strings. They can be simple and straight forward: select * from Clients Or complex multitable queries: select Clients.FirstName, Clients.LastName, Clients.address, data.Birthday, data.EyeColour from eMail, data where data.FirstName=Clients.FirstName and data.LastName=Clients.LastName Clicking Setup, will allow you to log into a different database. When you have the correct query in the Query: text box, click OK to select that query. This will return you to the mail merge main dialog box. Click Close. Now that you have selected your data query, it is time to insert the merge fields in the document. Click here to continue. mail mergeusing &kspread; file &kword; can use data in a &kspread; document for personalizing documents. 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. Using a &kspread; document to create personalized documents is a three step process: Select the file the data is located within. Insert the merge fields to tell &kword; where to insert the database information Print the personalized documents. To begin, select ToolsConfigure Mail Merge... from the menubar. A dialog box will appear. Click on Open Existing.... Another small dialog will appear. Select &kspread; Table Source from the drop down box labeled Available sources: and click on OK. A new dialog box will appear. Enter the &URL; or file name of the &kspread; document in the text box labeled URL:. 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. Once you have selected the &kspread; document, the drop down box labeled Page number: will show you all the available pages or worksheets within the &kspread; document. Select the page (or worksheet) that contains the mail merge data. When all information is correct, click OK. &kword; will ask you if you want to replace the current data source. Click Yes to continue. You will again see the mail merge main dialog box. Click Close. Now that you have selected your data query, it is time to insert the merge fields in the document. Click here to continue. mail mergeusing &kde; Address Book &kword; can use data in your address book for personalizing documents. Using address book entries to create personalized documents is a three step process: Select the people you want included in the mail merge. Insert the merge fields to tell &kword; where to insert the database information Print the personalized documents. To begin, select ToolsConfigure Mail Merge... from the menubar. A dialog box will appear. Click on Open Existing.... Another small dialog will appear. Select &kde; Addressbook Plugin from the drop down box labeled Available sources: and click on OK. A new dialog box will appear. The dialog consists of two listboxes labeled Address Book and Selected Addresses. By moving entries from your Address book to the Selected Addresses listbox, you will be including those entries in your merge document. To add an entry, select the entry in the left listbox by clicking with the &LMB;. Then click Add. To remove an entry, select the entry in the right listbox by clicking with the &LMB;. Then click Remove. You can locate entries quickly by entering the first 2-3 letters of an entries name in the textbox labeled Filter on: You can load the full address book application by clicking the Address Book... button. You can also save a distribution list using the Save as Distribution List... button. For more information on distribution lists, see the documentation on the &kde; Addressbook. When you have selected all the entries and distribution lists you want, click OK. &kword; will ask you if you want to replace the current data source. Click Yes to continue. You will again see the mail merge main dialog box. Click Close. Now that you have selected your data query, it is time to insert the merge fields in the document. Click here to continue. mail mergeusing &kword; data tables 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 directly into &kword; in tabular form. This internal data structure can then be used to create documents with this data inserted at predefined locations. Using an internal representation of the data to create personalized documents is a three step process: Enter the data into &kword; Insert the merge fields to tell &kword; where to insert the database information Print the personalized documents. 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. To begin, select ToolsConfigure Mail Merge... from the menubar. A dialog box will appear. Click on Create New.... Another small dialog will appear. There is currently only one option in this dialog box Internal Storage. Click on OK. A new dialog box will appear. 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. First, we need to add one or more entries (merge fields). This is accomplished by clicking the (Add entry) 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....). This is for the name of the entry, not the data that is contained within the entry. Click OK, and the entry is added to the card. Repeat this process until all needed entries are visible on this first card. If you want to delete an entry, simply click once on the entry name with the &LMB; and select (Remove entry). Be very sure you have selected the correct entry name. Once you tell &kword; to delete the entry, the entry and all of the data within those entries will be deleted immediately. You will not be given the option to stop or reverse the process once it is begun. Now that the structure of your data is defined, you can enter the data into your entries. 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. ButtonAction Move directly to record one Move back one record Move forward one record Move to the last record in the dataset 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 No Value as the default value for all entries in newly created records.) To add a record, click the button. To delete a record, click the button. Be careful when you are deleting records. Once deleted, the record cannot be retrieved. Continue to enter all data until your dataset is complete. After your dataset is complete, click OK to save the changes to your dataset. This will bring up the mail merge main dialog: Click Close. Now it is time to insert the merge fields in the document. Now that &kword; knows the entries available in your data source, you can insert the merge fields into your document. 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. mail mergeinserting merge fields To insert a merge field, place the cursor at the desired place in the document. Select InsertVariable Mail Merge... from the menubar. A list of available entries will appear. Select the desired entry, and click OK. The merge field is inserted at the current cursor location. The merge field is surrounded by brackets. 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. mail mergedeleting a merge field You can delete a merge field two ways. Place the cursor at the end of the merge field, and press the &Backspace; key. Place the cursor at the beginning of the merge field, and press the Delete key. mail mergemerging data and text Once you have inserted all the merge fields you want, you are ready to preview and print the personalized documents. To preview your document select ToolsConfigure Mail Merge... from the menubar. A dialog box will appear. Click Print Preview.... You will be able to see the final output of your personalized documents prior to printing. You print personalized documents using the same methods that you do to print traditional documents. For more information on printing see the section on Printing a Document.