% Generated by roxygen2: do not edit by hand
% Please edit documentation in R/crowd_plots_as_docx.R
\name{crowd_plots_as_docx}
\alias{crowd_plots_as_docx}
\title{Write Plots to Word Document (DOCX)}
\usage{
crowd_plots_as_docx(
  plot_list,
  path,
  docx_template = NULL,
  heading_style = "heading 2",
  prefix_style = "Normal",
  add_dep_label_prefix = TRUE,
  chart_width = NULL,
  chart_height = NULL,
  extract_metadata = TRUE
)
}
\arguments{
\item{plot_list}{Either:
\itemize{
\item A named list of mschart objects (from \code{makeme(..., type = "cat_plot_docx", docx_return_object = TRUE)})
\item A \code{saros_officer_plots} object (from \code{\link[=crowd_plots_as_officer]{crowd_plots_as_officer()}})
}}

\item{path}{Character. File path where the DOCX should be saved (e.g., \code{"output.docx"}).}

\item{docx_template}{Optional template passed to saros' internal \code{use_docx()} helper.
Can be a file path string, \code{NULL} for default template, or FALSE to skip template.}

\item{heading_style}{Character. officer paragraph style for section headings (plot names).
Default is \code{"heading 2"}.}

\item{prefix_style}{Character. officer paragraph style for prefix text (main question labels).
Default is \code{"Normal"}. Only used when \code{add_dep_label_prefix = TRUE}.}

\item{add_dep_label_prefix}{Logical. If \code{TRUE} (default), adds the main question text
(from \code{\link[=get_dep_label_prefix]{get_dep_label_prefix()}}) as a paragraph before each chart.}

\item{chart_width}{Numeric or \code{NULL}. Width in inches for charts. If \code{NULL} (default),
uses saros' internal \code{get_docx_dims()} helper based on template page layout.}

\item{chart_height}{Numeric or \code{NULL}. Height in inches for charts. If \code{NULL} (default),
uses saros' internal \code{get_docx_dims()} helper based on template page layout.}

\item{extract_metadata}{Logical. If \code{TRUE} (default), automatically extracts metadata
from plots using \code{\link[=crowd_plots_as_officer]{crowd_plots_as_officer()}} when \code{plot_list} is a plain list.
Ignored if \code{plot_list} is already a \code{saros_officer_plots} object.}
}
\value{
Invisible file path to the created DOCX file.
}
\description{
High-level function to write a list of mschart plots directly to a Word
document file, with optional section headings and chart labels. Simplifies
the workflow for generating DOCX reports from Quarto/RMarkdown by handling
all officer boilerplate internally.
}
\details{
This function provides a simple, single-call interface for writing Word documents
from saros plots, ideal for Quarto workflows where you want:
\itemize{
\item \strong{One QMD file → One DOCX file} (no chapter merging)
\item \strong{Minimal code in .qmd chunks} (just \code{makeme()} + \code{crowd_plots_as_docx()})
\item \strong{Automatic layout handling} (page dimensions, chart sizing, heading styles)
}

\strong{Typical Workflow:}
\enumerate{
\item Generate mschart objects with \code{makeme(..., type = "cat_plot_docx", docx_return_object = TRUE, crowd = ...)}
\item Call \code{crowd_plots_as_docx(plots, path = "report.docx")} to write the file
}

\strong{Empty Plot Lists:}
If \code{plot_list} contains no valid mschart objects, the function:
\itemize{
\item Issues a warning via \code{cli::cli_warn()}
\item Creates an empty DOCX file at the specified path
\item Returns the path invisibly
}
}
\examples{
\dontrun{
# Generate mschart objects for Word
plots <- makeme(
  data = ex_survey,
  dep = b_1:b_3,
  crowd = c("target", "others"),
  mesos_var = "f_uni",
  mesos_group = "Uni of A",
  type = "cat_plot_docx",
  docx_return_object = TRUE
)

# Write directly to a Word file
crowd_plots_as_docx(plots, path = "survey_results.docx")

# With custom template and styling
crowd_plots_as_docx(
  plots,
  path = "styled_report.docx",
  docx_template = "my_template.docx",
  heading_style = "Heading 1",
  prefix_style = "Body Text",
  chart_width = 6,
  chart_height = 4
)

# Without prefix labels
crowd_plots_as_docx(
  plots,
  path = "minimal_report.docx",
  add_dep_label_prefix = FALSE
)
}
}
\seealso{
\itemize{
\item \code{\link[=crowd_plots_as_officer]{crowd_plots_as_officer()}} for obtaining a structured plot object
\item \code{\link[=crowd_plots_as_tabset]{crowd_plots_as_tabset()}} for the Quarto/HTML equivalent
\item \code{\link[=makeme]{makeme()}} for creating plots with crowd parameter
\item \code{\link[officer:read_docx]{officer::read_docx()}} for manual DOCX assembly
}
}
