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.
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();
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).
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).
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.
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"
)
}