Mike
McBride

# Document Variables

A variable is a simple way of allowing &kword; to modify the document in very specific ways to reflect the changing nature of the document or report.

A variable can be a number (such as a page number, the total number of pages in a document, etc), a selection of words (clients name, product name, the documents filename, etc), a date, a time, or nearly anything you desire.

Once the variable is defined, a placeholder is inserted in the document. &kword; will replace this placeholder with the value of that variable each time the placeholder is used.

Variables can either be fixed (which means that once inserted, their value does not change), or variable (where the placeholder is updated by &kword; to reflect the current value of the variable).

This chapter will begin with a few examples of commonly used variables (date, time, and page numbers), then detail the remaining variables available to you. Finally, it will detail how to create custom variables for documents.

## Date and Time

Many letters, reports and documents contain information about the dates or times they correspond to. The date and time information may establish the creation of a document (which will remain fixed as long as the document is around), or the date and time may serve as a notice of the last date of modification (which would change with each passing day).

&kword; allows for both fixed and variable date and time variables in the document.

### Insert Date

To insert the date in the document, simply place the cursor in the text box where the date should be inserted and select Insert Variable Date from the menubar. This will bring up several selections. To insert the current date, select one of two options: Current date (fixed) and Current date (variable).

Current date (fixed)

  Selecting this option will insert the current date into the current cursor position. This date is determined by checking with the computers system clock. Once entered, this value will not change, even when &kword; is asked to update the document variables.

  This item is ideal for dates of document creation, or when including data in a report from todays work. Compare this choice to Current date (variable).

Current date (variable)

  Selecting this option will insert the current date into the current cursor position. This date is determined by checking with the computers system clock. This value will change when &kword; is asked to update the document variables.

  This option is good for any point in the document where the current date is always wanted. Compare this choice to Current date (fixed)

Once the date has been selected, a dialog box will appear.

The top combo box determines the layout of the variable. Your choices are:

Locale date format

  This inserts the date in the format specified in the &kde; Control Center.

  To select this option, simply make sure the upper combo box says Locale date format. A preview of the date format will appear above the OK button. If satisfied click OK.

Preformatted date strings

  &kword; comes with 19 predefined date strings. These predefined strings will be all that are needed in most circumstances. Simply select the predefined string in the upper combo box. A preview of the date format will appear above the OK button. If satisfied click OK.

Custom String

  If the appropriate format for the date cannot be found, it is possible to create custom date format strings.

  A date format string consists of a list of letters and numbers which follow specific rules (which are outlined below) to create the completed date.

  The date format string consists of placeholders and separators. The placeholders are defined in the following three tables.

  Days

  Day placeholders | d | dd | ddd | dddd
  Example | 6 | 06 | Thu | Thursday

  Months

  Month placeholders | M | MM | MMM | MMMM
  Example | 3 | 03 | Mar | March

  Year

  Year placeholders | yy | yyyy
  Example | 02 | 2002

  Simply combine placeholders with normal text (separators) to create completed date strings.

  For example:

  MM/dd/yyyy is translated to 01/06/2004

  and

  MMMM d, yyyy becomes January 6, 2004

  Notice that only the placeholders change. Spaces, commas, slashes and other text remains unchanged.

  It is important to remember that placeholders are case sensitive. DD is not a placeholder, only dd.

  To create a custom date string, place a mark in the Custom check box.

  Now type placeholders and separators text into the upper combo box. Alternatively select the format from the Insert: combo box, and the placeholder will be inserted into the date format string at the cursor location.

There is a spinbox labeled Correct in Days. You can use this spin box to adjust the date up or down one or more days from the current date.

A preview of the current date string is visible above the OK button. Click OK when the date format string is correct to insert the variable into the document.

Once the date has been inserted into the document, it can be reformatted to a different layout and toggled between fixed and variable dates. Simply click once with the &RMB; on the date. A small menu will appear. Select Change Variable To and a submenu will appear. Select your new variable or new layout from the menu and the variable is immediately updated.

There are three additional dates you can insert into your document:

Date of Last Printing

  Selecting this option will insert the date this document was last printed into the current cursor position.

Date of File Creation

  Selecting this option will insert the date this document created into the current cursor position.

Date of File Modification

  Selecting this option will insert the date this document was last edited into the current cursor position.

### Insert Time

To insert the time in the document, simply place the cursor in the text box where the time should be inserted and select Insert VariableTime from the menubar. This will bring up two selections: Current time (fixed) and Current time (variable).

Current time (fixed)

  Selecting this option will insert the current time into the current cursor position. This time is determined by checking with the computers system clock. Once entered, this value will not change, even when &kword; is asked to update the document variables.

  This item is ideal for timestamps. Compare this choice to Current time (variable).

Current time (variable)

  Selecting this option will insert the current time into the current cursor position. This time is determined by checking with the computers system clock. This value will change when &kword; is asked to update the document variables.

  This option is good for any point in your document where the current time is always wanted. Compare this choice to Current time (fixed)

This brings up a dialog box.

The top combo box determines the layout of the variable. The choices are:

Locale format

  This inserts the time in the format specified in the &kde; Control Center.

  To select this option, simply make sure the upper combo box says Locale format. A preview of the current time string is visible above the OK button. If satisfied click OK.

Preformatted time strings

  &kword; comes with 6 predefined time strings. These predefined strings will be all that are needed in most circumstances. Simply select the predefined string in the upper combo box. A preview of the current time string is visible above the OK button. If satisfied click OK.

Custom String

  If the appropriate format cannot be found, a custom time format string can be created.

  A time format string consists of a list of letters and numbers which follow specific rules (which are outlined below) to create the completed time.

  The time format string consists of placeholders and separators. The placeholders are defined in the following five tables.

  Hours

  Hour placeholders | h | hh
  Example | 6 | 06

  Minutes

  Minutes placeholders | m | mm
  Example | 3 | 03

  Seconds

  Seconds placeholders | s | ss
  Example | 2 | 02

  Milliseconds

  Milliseconds placeholders | zzz
  Example | 022

  Seconds

  AM/PM placeholders | ap | AP
  Example | am | AM

  Simply combine placeholders with normal text (separators) to create completed time strings.

  For example:

  hh:mm:ss becomes 06:23:13

  and

  h:mm ap becomes 6:23 am

  Notice that only the placeholders change. Spaces, colons and other text remains unchanged.

  It is important to remember that placeholders are case sensitive. HH is not a placeholder, only hh

  To create a custom time string, place a mark in the Custom check box.

  Type the placeholders and separator text into the upper combo box. Alternatively, you can select the format from the Insert: combo box, and the placeholder will be inserted into the time format string at the cursor location.

  A preview of the current time string is visible below the Custom check box. Click OK when the time format string is correct to insert the variable into your document.

A preview of the current time string is visible below the Custom check box. Click OK when the time format string is correct to insert the variable into your document.

Once the time has been inserted into the document, it can be reformatted to a different layout and toggled between fixed and variable times. Simply click once with the &RMB; on the time in the document. A small menu will appear. Select Change Variable To and a submenu will appear. Select your new variable or new layout from the menu and the variable is immediately updated.

## Page Numbering

Inserting page numbers is easy in &kword;.

There are five variables that relate to page numbers: Page Number, Number of Pages,Section TitleNext Page, and Previous Page.

To insert the current page number, place the cursor where you want the page number and select Insert VariablePage Page Number from the menubar. The page number will be inserted at the current cursor location.

To insert the total number of pages, place the cursor where you want the variable and select Insert VariablePage Number of Pages from the menubar. The total number of pages will be inserted.

To insert the title of the section, place the cursor where you want the variable and select Insert VariablePage Section Title from the menubar. The section title will be inserted.

By selecting Insert VariablePage Next Page from the menubar, a reference to the page number after the current page will be inserted at the current cursor location.

Likewise, by selecting Insert VariablePage Previous Page from the menubar, a reference to the page number before the current page will be inserted at the current cursor location.

Page numbers are updated dynamically as the document is edited.

Page numbers are usually best located within headers and footers. This ensures that every page will have a page number at the appropriate place.

## Section Title

You can insert the section title anywhere in your document by selecting Insert VariablePage Section Title from the menubar.

&kword; determines the Section title by beginning a search from the top of the current page. The first paragraph with a style of Head 1 is the section title. If there are no paragraphs on the current page, &kword; does the same search along on previous pages until it finds a section title.

## Other Variables

&kword; provides other commonly used variables that you might find useful. This set of variables are specific to the document. You can insert these variables by selecting Insert Variable Document Information from the menubar. This will bring up a list of variables. The variables are detailed below.

Variable | Example | Details
--- | --- | ---
Author Name | Joseph User | The name of the author as specified in the Document information box.
City | Philadelphia | The city specified in the Document information box.
Company | &kde; | The company name specified in the Document information box.
Country | United States | The country name specified in the Document information box.
Directory Name | /home/juser/kword | This is the folder name for the document. The filename is not included in the folder name variable.
Directory & Filename | /home/juser/kword/Resume.kwd | The folder and filename of the current file.
Document Abstract | This is a current resume. | The document abstract specified in the Document information box.
Document Keywords | Resume, job, application | The document keywords specified in the Document information box.
Document Subject | My resume. | The document subject line specified in the Document information box.
Document Title | My Resume | The document title specified in the Document information box.
Email | joeuser@kde.org | The email address of the author as specified in the Document information box.
Fax | Any valid telephone number | The fax machine number specified in the Document information box.
File Name | Resume.kwd | The complete name of the file.
File Name without extension | Resume | The filename without the suffix (usually .kwd).
Initials | JCU | The initials specified in the authors section of the Document information box.
Postal code | Any valid postal code | The postal code specified in the Document information box.
Street | 123 Main St. | The street address specified in the Document information box.
Telephone (work) | Any valid telephone number | The telephone number specified in the Document information box.
Telephone (private) | Any valid telephone number | The telephone number specified in the Document information box.
Title | Director of Information Systems | The title specified in the authors section of the Document information box.

Additionially, there are numerous variables under the Statistics submenu for inserting the number of words, lines, frames, etc. These variables should be self explanitory.

Uninitialized variables will appear as <none>, until you define their value in the Document information box.

## Custom Variables

&kword; has many predefined variables. You may encounter documents where it would be nice to define your own variables for a document.

Using Custom Variables, you can create an unlimited number of variables for each document.

### Create a new custom variable

To create a new custom variable, place the cursor at the location in the document to insert the new variable.

Select Insert VariableCustom New from the menubar. This will bring up a dialog box.

Enter the variable name and its current value in the text boxes provided.

Click OK to create the new variable name and insert it at the current cursor location. Click Cancel to cancel the creation of the new variable.

It is now possible to insert this new variable at any place in your document.

### Edit a custom variables value

In order for variables to be useful, you need to be able to give them a value, and be able to change that value easily. To change the value of a variable:

Select Tools Custom Variables... from the menubar. This will bring up a dialog box.

Each custom variable has a line in this table. The first column is the name of the variable, and the second column is the value.

To change the value of a variables, simply click within the text box to the right of the variable name. Enter the desired value.

When all the changes have been complete, simply click OK and all the variables will be updated.

### Insert a custom variable

To insert a new custom variable select Insert VariableCustom from the menubar. The custom variable is listed in the submenu. Click on the name of the variable and &kword; will insert the variable, with its current value, at the cursor location.

## Updating All Variable Values

You can tell &kword; to update all variable values (to make sure all variables are set to their current values). This is especially important with dates and times.

Simply select Insert Variable Refresh All Variables from the menubar.

## Updating One Date or Time Variable Value

You can tell &kword; to update a single date or time variable value, and leave the others unchanged.

Simply place the mouse pointer over the variable you want to update and click with the &RMB;. Select Change Variable To. A small menu will appear which will show several new date or time formatting options and the option to change either dates or times to fixed or variable time formats. Simply select the new option and this variable will be updated.