% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/report_spec.r
\name{titles}
\alias{titles}
\title{Adds a title block}
\usage{
titles(
  x,
  ...,
  align = "center",
  blank_row = "below",
  borders = "none",
  width = NULL,
  bold = FALSE,
  font_size = NULL,
  header = FALSE,
  columns = 1
)
}
\arguments{
\item{x}{The object to assign titles to.  Valid objects are a report, or
a table, text, or plot specification.}

\item{...}{A set of title strings.}

\item{align}{The position to align the titles.  Valid values are 'left', 
'right', 'center' or 'centre'.  For titles, the default is 'center'.}

\item{blank_row}{Where to place a blank row.  Valid values are 'above',
'below', 'both', or 'none'.  Default is "below".}

\item{borders}{Whether and where to place a border. Valid values are 'top',
'bottom', 'left', 'right', 'outside', 'inside', 'all', or 'none'.  
Default is "none".  
The 'left', 'right', 'outside', and 'inside' border specifications 
only apply to RTF, HTML, PDF and DOCX reports.}

\item{width}{The width of the titles block.  If the titles are attached
to the report, valid values are 'page' or a numeric width, and the default
is 'page'. If the titles are attached to the
table, plot, or text content, the valid values are 'page', 'content' or a 
numeric value, and the default is 'content'.  The value 'content' means the 
titles will be aligned to the width of the table, plot, or text
content.  The value
'page' means the titles will be aligned to the width of the page. 
In addition to these two convenience settings, you 
may also specify a specific width in the current units of measure.  The
units of measure is determined by the 'units' parameter on 
\code{\link{create_report}}.}

\item{bold}{A parameter to bold the titles.  Valid values are TRUE and FALSE.
Default is FALSE.  This parameter only applies to variable-width RTF, HTML, 
PDF, and DOCX output types.}

\item{font_size}{The font size to use for the title block.  The font size
of the report will be used by default.  Valid values are 8, 9, 10, 11, 12,
13, and 14.  This parameter only applies to variable-width RTF, HTML, PDF,
and DOCX output types.}

\item{header}{Whether to put the titles in the page header. Valid values
are TRUE and FALSE.  Default is FALSE. This option only works on the RTF 
and DOCX output types, and only applies to titles assigned 
to the report object.  Titles in the page header will appear on every page, 
and be the same throughout the report.}

\item{columns}{The number of columns for the title block. Valid values
are 1, 2, and 3.  Default is 1.  If this parameter is set to 2, the title
block will be split into two columns, each aligned to the outside.  If 
this parameter is set to 3, the title block will be split into 3 columns,
with the outer columns aligned to the outside and the middle column
aligned center.  Titles are assigned to cells from top left to bottom right.}
}
\value{
The modified report.
}
\description{
This function adds one or more titles to an object as a title block.  
If added to a report, 
the titles will be added to
the page template, and thus appear on each page of the report. Titles may 
also be added to a table, text, or plot object.
}
\details{
The titles function accepts a set of strings of the desired title text. To
specify multiple titles for the block, pass them to the function 
as separate strings.

The titles may be aligned center, left or right using the align parameter.
The alignment will be applied to all titles contained in the 
block.  To control alignment of titles separately for each title, use 
multiple titles functions.

Titles may be assigned to a report, a table, a text specification, or a plot. 
If assigned to the report, the title will appear at the top of the page, and
be repeated for every page of the report.  If the titles are assigned to  
content, the titles will appear above the content, and be repeated if the 
content breaks to the next page.  

If titles are assigned to the report,
alignment will be oriented to the page body.  If titles are assigned to
content, alignment will be oriented to the edge of the content.

One title function accepts up to 10 titles.  However, multiple title 
blocks may be added to the same object if needed.  

Blank rows above or below the title block may be controlled using the 
\code{blank_row} parameter.

Each title string must fit within the available space.  The \strong{reporter}
package will not wrap titles on fixed-width reports.  
If a title does not fit within the 
available space, a warning will be generated and the title will be 
truncated.  In these situations, either
shorten the title or split it into multiple titles that each fit within the
available space.
}
\examples{
library(reporter)
library(magrittr)

# Create a temporary file
tmp <- file.path(tempdir(), "expenses.txt")

# Prepare data
dat <- data.frame(category = rownames(USPersonalExpenditure),
                  USPersonalExpenditure, stringsAsFactors = FALSE)

# Define table
tbl <- create_table(dat) \%>\% 
  titles("Table 1.0", "US Personal Expenditures from 1940 - 1960") \%>\% 
  column_defaults(from = X1940, to = X1960, width = .6, format = "$\%.2f") \%>\%
  define(category, label = "Category") \%>\% 
  define(X1940, label = "1940") \%>\% 
  define(X1945, label = "1945") \%>\% 
  define(X1950, label = "1950") \%>\% 
  define(X1955, label = "1955") \%>\% 
  define(X1960, label = "1960") \%>\% 
  footnotes("* In billions of dollars")

# Define report
rpt <- create_report(tmp, orientation="portrait") \%>\%
  add_content(tbl) 

# Write the report
write_report(rpt)

# Display in console
writeLines(readLines(tmp, encoding = "UTF-8"))
#                               Table 1.0
#               US Personal Expenditures from 1940 - 1960
# 
#     Category                1940    1945    1950    1955    1960
#     ------------------------------------------------------------
#     Food and Tobacco      $22.20  $44.50  $59.60  $73.20  $86.80
#     Household Operation   $10.50  $15.50  $29.00  $36.50  $46.20
#     Medical and Health     $3.53   $5.76   $9.71  $14.00  $21.10
#     Personal Care          $1.04   $1.98   $2.45   $3.40   $5.40
#     Private Education      $0.34   $0.97   $1.80   $2.60   $3.64
# 
#     * In billions of dollars
}
\seealso{
Other report: 
\code{\link{add_content}()},
\code{\link{create_report}()},
\code{\link{footer_image}()},
\code{\link{footnotes}()},
\code{\link{header_image}()},
\code{\link{options_fixed}()},
\code{\link{page_by}()},
\code{\link{page_footer}()},
\code{\link{page_header}()},
\code{\link{print.report_spec}()},
\code{\link{set_margins}()},
\code{\link{title_header}()},
\code{\link{write_report}()}
}
\concept{report}
