figma (version 0.2.0)

get_figma_file: Get data of a Figma File from the API

Description

This function uses the /v1/files/ endpoint of Figma API to get all of the data of a particular Figma file, and fit it into a R object.

Usage

get_figma_file(
  file_key,
  token,
  geometry = FALSE,
  .output_format = "response",
  ...
)

Value

By default, get_figma_file() do not parse the output from the API, and returns the raw response object produced by the httr HTTP methods (e.g. httr::GET()).

But you can change this behavior with .output_format argument. With .output_format = "tibble", a tibble::tibble() object is returned. With .output_format = "figma_document", a object of class figma_document is returned (See Details section for more information).

Arguments

file_key

A string with the key of the Figma File you want to get;

token

A string with your personal Figma token to authenticate in the API;

geometry

A boolean value indicating if you want to export vector data. Defaults to FALSE;

.output_format

The output format. Options are "response", "figma_document", "tibble". Defaults to "response";

...

Further arguments that are passed to parse_response_object();

Be aware of possible HTTP errors

To get the data of your Figma file, the functions from figma package make a HTTP request to the Figma API. But this request can fail for a number of reasons, and if this does happen, get_figma_file() will use report_http_error() to raise an error and report to the user, what kind of error message the Figma API returned. See vignette("http-errors") for more details.

Details

With this function you can bring all of the data of your Figma file into R. By default, get_figma_file() returns a `response` object with all of the data returned by the API. That is, not only the data of your Figma file, but also, the data from the HTTP request.

All of your Figma file data is in the content element of the `response` object. However, by default, the Figma API returns this data in raw format (that is, as raw bytes). To convert these bytes into a useful object (like a JSON object, or a character vector, or a list), is highly recommended to apply the httr::content() function over this content element.

Although this being a useful output format (i.e. `response` object) (specially because it brings all of the available data), you might want a more "formatted" (or friendly) output. In this case, you can use the .output_format argument to get a different output format.

With .output_format = "figma_document", get_figma_file() use figma::as_figma_document() to convert the `response` object into a Figma Document object (i.e. a object of class figma_document), and returns it as the output. This figma_document object, is a normal R list, with only the data of your Figma file (See documentation of figma::as_figma_document() for more details).

With .output_format = "tibble", get_figma_file() will use figma::as_tibble() to parse the output from the API to fit into a tibble::tibble() object. If you use this output format, you can also use the simplified argument to control if document metadata should be present in the resulting tibble (See examples section).

By default, simplified is set to TRUE, so get_figma_file() outputs a tibble with all the objects data from your Figma file, and their corresponding canvas metadata. However, it does not include any metadata from the document per se.

In other words, with simplified = TRUE you get all the data of the objects from each canvas in your Figma file, but you do not get any metadata from the document. That is okay, because you usually do not need these informations.

But if you want them in the resulting tibble, pass simplified = FALSE to get_figma_file(). If you want just the document metadata (and not the canvas or objects data), you might want to use the get_document_info() function instead of get_figma_file() (See get_document_info() documentation for more details).

See Also

as_tibble

as_figma_document

Examples

if (FALSE) {
library(figma)

file_key <- "hch8YlkgaUIZ9raDzjPvCz"
token <- "my figma token secret ... "

# Returns a `response` object:
result <- figma::get_figma_file(file_key, token)

# Returns a `tibble` object:
result <- figma::get_figma_file(
  file_key, token, .output_format = "tibble"
)

# Returns the same `tibble` object as before
# but, now, with all the metadata from the
# Figma document too:
result <- figma::get_figma_file(
  file_key, token,
  .output_format = "tibble",
  simplified = FALSE
)

# Returns a `figma_document` object:
result <- figma::get_figma_file(
  file_key, token, .output_format = "figma_document"
)
}