diff --git a/R/class-workbook-wrappers.R b/R/class-workbook-wrappers.R index 21413d5c7..837f2b2f6 100644 --- a/R/class-workbook-wrappers.R +++ b/R/class-workbook-wrappers.R @@ -11,7 +11,7 @@ #' "Savon", "Slice", "Vapor Trail", "View", "Wisp", "Wood Type" #' #' @param creator Creator of the workbook (your name). Defaults to login username or `options("openxlsx2.creator")` if set. -#' @param title,subject,category,keywords,comments Workbook property, a string. +#' @param title,subject,category,keywords,comments,manager,company Workbook property, a string. #' @param datetime_created The time of the workbook is created #' @param theme Optional theme identified by string or number. #' See **Details** for options. @@ -41,6 +41,8 @@ wb_workbook <- function( theme = NULL, keywords = NULL, comments = NULL, + manager = NULL, + company = NULL, ... ) { wbWorkbook$new( @@ -52,6 +54,8 @@ wb_workbook <- function( theme = theme, keywords = keywords, comments = comments, + manager = manager, + company = company, ... = ... ) } @@ -2204,11 +2208,21 @@ wb_ungroup_rows <- function(wb, sheet = current_sheet(), rows) { #' workbook `title`, `subject` and `category` field. Use [wb_workbook()] #' to easily set these properties with a new workbook. #' -#' @name properties +#' To set properties, the following XML core properties are used. +#' - title = dc:title +#' - subject = dc:subject +#' - creator = dc:creator +#' - keywords = cp:keywords +#' - comments = dc:description +#' - modifier = cp:lastModifiedBy +#' - datetime_created = dcterms:created +#' - datetime_modified = dcterms:modified +#' - category = cp:category +#' +#' In addition, manager and company are used. +#' @name properties-wb #' @param wb A Workbook object -#' @param creators A character string indicating who has created the workbook -#' @param date_time_created datetime created -#' @param modifiers A character string indicating who was the last person to modify the workbook +#' @param modifier A character string indicating who was the last person to modify the workbook #' @seealso [wb_workbook()] #' @inheritParams wb_workbook #' @return A wbWorkbook object, invisibly. @@ -2227,19 +2241,21 @@ wb_get_properties <- function(wb) { wb$get_properties() } -#' @rdname properties +#' @rdname properties-wb #' @export -wb_set_properties <- function(wb, creators = NULL, title = NULL, subject = NULL, category = NULL, date_time_created = Sys.time(), modifiers = NULL, keywords = NULL, comments = NULL) { +wb_set_properties <- function(wb, creator = NULL, title = NULL, subject = NULL, category = NULL, datetime_created = Sys.time(), modifier = NULL, keywords = NULL, comments = NULL, manager = NULL, company = NULL) { assert_workbook(wb) wb$clone()$set_properties( - creators = creators, + creator = creator, title = title, subject = subject, category = category, - date_time_created = date_time_created, - modifiers = modifiers, + datetime_created = datetime_created, + modifier = modifier, keywords = keywords, - comments = comments + comments = comments, + manager = manager, + company = company ) } @@ -2297,7 +2313,7 @@ wb_remove_creators <- function(wb, creators) { #' @export wb_get_creators <- function(wb) { assert_workbook(wb) - strsplit(wb$get_properties()[["dc:creator"]], ";")[[1]] + strsplit(wb$get_properties()[["creator"]], ";")[[1]] } diff --git a/R/class-workbook.R b/R/class-workbook.R index 84dcfdf6f..a8ea9f428 100644 --- a/R/class-workbook.R +++ b/R/class-workbook.R @@ -155,7 +155,7 @@ wbWorkbook <- R6::R6Class( #' @description #' Creates a new `wbWorkbook` object #' @param creator character vector of creators. Duplicated are ignored. - #' @param title,subject,category,keywords,comments workbook properties + #' @param title,subject,category,keywords,comments,manager,company workbook properties #' @param datetime_created The datetime (as `POSIXt`) the workbook is #' created. Defaults to the current `Sys.time()` when the workbook object #' is created, not when the Excel files are saved. @@ -171,6 +171,8 @@ wbWorkbook <- R6::R6Class( theme = NULL, keywords = NULL, comments = NULL, + manager = NULL, + company = NULL, ... ) { @@ -199,6 +201,9 @@ wbWorkbook <- R6::R6Class( assert_class(category, "character", or_null = TRUE) assert_class(keywords, "character", or_null = TRUE) assert_class(comments, "character", or_null = TRUE) + assert_class(manager, "character", or_null = TRUE) + assert_class(company, "character", or_null = TRUE) + assert_class(datetime_created, "POSIXt") stopifnot( @@ -208,13 +213,15 @@ wbWorkbook <- R6::R6Class( ) self$set_properties( - creators = creator, + creator = creator, title = title, subject = subject, category = category, - date_time_created = datetime_created, + datetime_created = datetime_created, keywords = keywords, - comments = comments + comments = comments, + manager = manager, + company = company ) self$comments <- list() self$threadComments <- list() @@ -5121,18 +5128,40 @@ wbWorkbook <- R6::R6Class( ### creators -------------------------------------------------------------- #' @description Get properties of a workbook - #' @param escape escape xml strings get_properties = function() { nams <- xml_node_name(self$core, "cp:coreProperties") - vapply(nams, function(x) { + properties <- vapply(nams, function(x) { xml_value(self$core, "cp:coreProperties", x, escapes = TRUE) }, FUN.VALUE = NA_character_) + + name_replace <- c( + title = "dc:title", + subject = "dc:subject", + creator = "dc:creator", + keywords = "cp:keywords", + comments = "dc:description", + modifier = "cp:lastModifiedBy", + datetime_created = "dcterms:created", + datetime_modified = "dcterms:modified", + category = "cp:category" + ) + # use names + names(properties) <- names(name_replace)[match(names(properties), name_replace)] + + + if (!is.null(self$app$Company)) { + properties <- c(properties, "company" = xml_value(self$app$Company, level1 = "Company")) + } + if (!is.null(self$app$Manager)) { + properties <- c(properties, "manager" = xml_value(self$app$Manager, level1 = "Manager")) + } + properties }, #' @description Set a property of a workbook - #' @param creators,title,subject,category,date_time_created,modifiers,keywords,comments A workbook property to set - set_properties = function(creators = NULL, title = NULL, subject = NULL, category = NULL, date_time_created = Sys.time(), modifiers = NULL, keywords = NULL, comments = NULL) { + #' @param creator,title,subject,category,datetime_created,modifier,keywords,comments,manager,company A workbook property to set + set_properties = function(creator = NULL, title = NULL, subject = NULL, category = NULL, datetime_created = Sys.time(), modifier = NULL, keywords = NULL, comments = NULL, manager = NULL, company = NULL) { # get an xml output or create one core_dctitle <- "dc:title" @@ -5173,10 +5202,10 @@ wbWorkbook <- R6::R6Class( } # update values where needed - if (!is.null(creators)) { - if (length(creators) > 1) creators <- paste0(creators, collapse = ";") - xml_properties[core_creator] <- xml_node_create(core_creator, xml_children = creators) - modifiers <- creators + if (!is.null(creator)) { + if (length(creator) > 1) creator <- paste0(creator, collapse = ";") + xml_properties[core_creator] <- xml_node_create(core_creator, xml_children = creator) + modifier <- creator } if (!is.null(keywords)) { @@ -5187,15 +5216,23 @@ wbWorkbook <- R6::R6Class( xml_properties[core_describ] <- xml_node_create(core_describ, xml_children = comments) } + if (!is.null(manager)) { + self$app$Manager <- xml_node_create("Manager", xml_children = manager) + } + + if (!is.null(company)) { + self$app$Company <- xml_node_create("Company", xml_children = company) + } + xml_properties[core_created] <- xml_node_create(core_created, xml_attributes = c( `xsi:type` = "dcterms:W3CDTF" ), - xml_children = format(as_POSIXct_utc(date_time_created), "%Y-%m-%dT%H:%M:%SZ") + xml_children = format(as_POSIXct_utc(datetime_created), "%Y-%m-%dT%H:%M:%SZ") ) - if (!is.null(modifiers)) { - xml_properties[core_lastmod] <- xml_node_create(core_lastmod, xml_children = modifiers) + if (!is.null(modifier)) { + xml_properties[core_lastmod] <- xml_node_create(core_lastmod, xml_children = modifier) } if (!is.null(category)) { @@ -5224,24 +5261,24 @@ wbWorkbook <- R6::R6Class( #' @param creators A character vector of creators to set. Duplicates are #' ignored. set_creators = function(creators) { - self$set_properties(creators = creators) + self$set_properties(creator = creators) }, #' @description Add creator(s) #' @param creators A character vector of creators to add. Duplicates are #' ignored. add_creators = function(creators) { - creators <- paste0(self$get_properties()[["dc:creator"]], ";", creators) - self$set_properties(creators = creators) + creators <- paste0(self$get_properties()[["creator"]], ";", creators) + self$set_properties(creator = creators) }, #' @description Remove creator(s) #' @param creators A character vector of creators to remove. All duplicated #' are removed. remove_creators = function(creators) { - old <- strsplit(self$get_properties()[["dc:creator"]], ";")[[1]] + old <- strsplit(self$get_properties()[["creator"]], ";")[[1]] old <- old[which(!old %in% creators)] - self$set_properties(creators = old) + self$set_properties(creator = old) }, #' @description @@ -5254,7 +5291,7 @@ wbWorkbook <- R6::R6Class( .Deprecated(old = "LastModifiedBy", new = "name", package = "openxlsx2") name <- list(...)$LastModifiedBy } - self$set_properties(modifiers = name) + self$set_properties(modifier = name) }, #' @description page_setup() diff --git a/_pkgdown.yml b/_pkgdown.yml index be03c69d8..bc51c5d19 100644 --- a/_pkgdown.yml +++ b/_pkgdown.yml @@ -90,9 +90,9 @@ reference: desc: > These functions are used to modify setting of a workbook as a whole. contents: + - properties-wb - wb_set_last_modified_by - creators-wb - - wb_set_properties - wb_order - sheet_names-wb - wb_remove_worksheet diff --git a/man/properties-wb.Rd b/man/properties-wb.Rd new file mode 100644 index 000000000..ab0438fd8 --- /dev/null +++ b/man/properties-wb.Rd @@ -0,0 +1,71 @@ +% Generated by roxygen2: do not edit by hand +% Please edit documentation in R/class-workbook-wrappers.R +\name{properties-wb} +\alias{properties-wb} +\alias{wb_get_properties} +\alias{wb_set_properties} +\title{Modify workbook properties} +\usage{ +wb_get_properties(wb) + +wb_set_properties( + wb, + creator = NULL, + title = NULL, + subject = NULL, + category = NULL, + datetime_created = Sys.time(), + modifier = NULL, + keywords = NULL, + comments = NULL, + manager = NULL, + company = NULL +) +} +\arguments{ +\item{wb}{A Workbook object} + +\item{creator}{Creator of the workbook (your name). Defaults to login username or \code{options("openxlsx2.creator")} if set.} + +\item{title, subject, category, keywords, comments, manager, company}{Workbook property, a string.} + +\item{datetime_created}{The time of the workbook is created} + +\item{modifier}{A character string indicating who was the last person to modify the workbook} +} +\value{ +A wbWorkbook object, invisibly. +} +\description{ +This function is useful for workbooks that are loaded. It can be used to set the +workbook \code{title}, \code{subject} and \code{category} field. Use \code{\link[=wb_workbook]{wb_workbook()}} +to easily set these properties with a new workbook. +} +\details{ +To set properties, the following XML core properties are used. +\itemize{ +\item title = dc:title +\item subject = dc:subject +\item creator = dc:creator +\item keywords = cp:keywords +\item comments = dc:description +\item modifier = cp:lastModifiedBy +\item datetime_created = dcterms:created +\item datetime_modified = dcterms:modified +\item category = cp:category +} + +In addition, manager and company are used. +} +\examples{ +file <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") +wb <- wb_load(file) +wb$get_properties() + +# Add a title to properties +wb$set_properties(title = "my title") +wb$get_properties() +} +\seealso{ +\code{\link[=wb_workbook]{wb_workbook()}} +} diff --git a/man/properties.Rd b/man/properties.Rd deleted file mode 100644 index 1aac08d64..000000000 --- a/man/properties.Rd +++ /dev/null @@ -1,53 +0,0 @@ -% Generated by roxygen2: do not edit by hand -% Please edit documentation in R/class-workbook-wrappers.R -\name{properties} -\alias{properties} -\alias{wb_get_properties} -\alias{wb_set_properties} -\title{Modify workbook properties} -\usage{ -wb_get_properties(wb) - -wb_set_properties( - wb, - creators = NULL, - title = NULL, - subject = NULL, - category = NULL, - date_time_created = Sys.time(), - modifiers = NULL, - keywords = NULL, - comments = NULL -) -} -\arguments{ -\item{wb}{A Workbook object} - -\item{creators}{A character string indicating who has created the workbook} - -\item{title, subject, category, keywords, comments}{Workbook property, a string.} - -\item{date_time_created}{datetime created} - -\item{modifiers}{A character string indicating who was the last person to modify the workbook} -} -\value{ -A wbWorkbook object, invisibly. -} -\description{ -This function is useful for workbooks that are loaded. It can be used to set the -workbook \code{title}, \code{subject} and \code{category} field. Use \code{\link[=wb_workbook]{wb_workbook()}} -to easily set these properties with a new workbook. -} -\examples{ -file <- system.file("extdata", "openxlsx2_example.xlsx", package = "openxlsx2") -wb <- wb_load(file) -wb$get_properties() - -# Add a title to properties -wb$set_properties(title = "my title") -wb$get_properties() -} -\seealso{ -\code{\link[=wb_workbook]{wb_workbook()}} -} diff --git a/man/wbWorkbook.Rd b/man/wbWorkbook.Rd index b43e59cb6..df02ca9bd 100644 --- a/man/wbWorkbook.Rd +++ b/man/wbWorkbook.Rd @@ -279,6 +279,8 @@ Creates a new \code{wbWorkbook} object theme = NULL, keywords = NULL, comments = NULL, + manager = NULL, + company = NULL, ... )}\if{html}{\out{}} } @@ -288,7 +290,7 @@ Creates a new \code{wbWorkbook} object \describe{ \item{\code{creator}}{character vector of creators. Duplicated are ignored.} -\item{\code{title, subject, category, keywords, comments}}{workbook properties} +\item{\code{title, subject, category, keywords, comments, manager, company}}{workbook properties} \item{\code{datetime_created}}{The datetime (as \code{POSIXt}) the workbook is created. Defaults to the current \code{Sys.time()} when the workbook object @@ -2073,13 +2075,6 @@ Get properties of a workbook \if{html}{\out{