feat: add lock_content() and unlock_content() (#457)

Co-authored-by: Kara Woo <[email protected]>

Author: toph-allen

NAMESPACE

@@ -125,6 +125,7 @@ export(get_variants)
 export(groups_create_remote)
 export(has_image)
 export(has_thumbnail)
+export(lock_content)
 export(page_cursor)
 export(page_offset)
 export(poll_task)
@@ -163,6 +164,7 @@ export(swap_vanity_url)
 export(swap_vanity_urls)
 export(tbl_connect)
 export(terminate_jobs)
+export(unlock_content)
 export(update_integration)
 export(user_guid_from_username)
 export(users_create_remote)

NEWS.md

@@ -12,6 +12,8 @@
 - Support content search API with the `search_content()` function. (#272)
 - New `search_content()` function which lets you search and filter content items
   on the Connect server. (#272, #447)
+- New `lock_content()` and `unlock_content()` functions for locking and unlocking
+  content items. (#453)
 
 # connectapi 0.8.0
 

R/connect.R

@@ -45,7 +45,9 @@ Connect <- R6::R6Class(
     #' @param server The base URL of your Posit Connect server.
     #' @param api_key Your Posit Connect API key.
     initialize = function(server, api_key) {
-      message_if_not_testing(glue::glue("Defining Connect with server: {server}"))
+      message_if_not_testing(glue::glue(
+        "Defining Connect with server: {server}"
+      ))
       if (is.null(httr::parse_url(server)$scheme)) {
         stop(glue::glue(
           "ERROR: Please provide a protocol (http / https). You gave: {server}"
@@ -450,7 +452,10 @@ Connect <- R6::R6Class(
       include = "tags,owner"
     ) {
       if (!is.null(guid)) {
-        return(self$GET(v1_url("content", guid), query = list(include = include)))
+        return(self$GET(
+          v1_url("content", guid),
+          query = list(include = include)
+        ))
       }
 
       query <- list(

R/content.R

@@ -1051,6 +1051,65 @@ content_update_owner <- function(content, owner_guid) {
   content_update(content = content, owner_guid = owner_guid)
 }
 
+#' Lock or Unlock Content
+#'
+#' Lock or unlock a content item. When content is locked, all processes are
+#' terminated, rendering is disabled, and new bundles cannot be deployed.
+#'
+#' `lock_content()` locks a content item with an optional message displayed to
+#' visitors (supports Markdown).
+#'
+#' `unlock_content()` unlocks a content item, reverting the effects of locking.
+#'
+#' @param content An R6 content item
+#' @param locked_message Optional. A custom message that is displayed by the
+#' content item when locked. It is possible to format this message using Markdown.
+#'
+#' @return An R6 content item
+#'
+#' @family content functions
+#' @rdname lock_content
+#' @export
+#' @examples
+#' \dontrun{
+#' # Lock content with a message
+#' client <- connect()
+#' content <- content_item(client, "content-guid")
+#' content <- lock_content(content, locked_message = "Ah ah ah! You didn't say the magic word!")
+#'
+#' # Lock content without a message
+#' content <- lock_content(content)
+#'
+#' # Unlock content
+#' content <- unlock_content(content)
+#' }
+lock_content <- function(content, locked_message = "") {
+  validate_R6_class(content, "Content")
+  error_if_less_than(content$connect$version, "2024.08.0")
+
+  update_params <- list(locked = TRUE)
+  if (!is.null(locked_message)) {
+    update_params$locked_message <- locked_message
+  }
+
+  content$update(!!!update_params)
+  content$get_content_remote()
+
+  return(content)
+}
+
+#' @rdname lock_content
+#' @export
+unlock_content <- function(content) {
+  validate_R6_class(content, "Content")
+  error_if_less_than(content$connect$version, "2024.08.0")
+
+  content$update(locked = FALSE, locked_message = "")
+  content$get_content_remote()
+
+  return(content)
+}
+
 
 #' Verify Content Name
 #'