# getting-started

# rgoogleclassroom

`rgoogleclassroom` is a Google API wrapper that allows you to use Google Classroom and Google Forms from the coziness and comfort of R.

You can read the rgoogleclassroom package documentation here.

## To get started

To use this package you need to have a Google Classroom account. Go here to get that: https://edu.google.com/workspace-for-education/products/classroom/

## How to install

If you want the development version (not advised) you can install using the `remotes` package to install from GitHub.

    if (!("remotes" %in% installed.packages())) {
      install.packages("remotes")
    }
    remotes::install_github("datatrail-jhu/rgoogleclassroom")

### Getting your owner Id

In order to make a new course with `rgoogleclassroom` you need your owner id. You can get this by running the following:

``owner_id <- get_owner_id()`

## Usage

To start, you need to `authorize()` the package to access your files. Select all the scopes you feel comfortable sharing. Note that you need to select certain scopes for certain functions to work.

You can do this by running the `authorize()` function. You can authorize programmatically using a secret if you use the `auth_from_secret()` function.

    authorize()

### Basics

There are different objects on the Google API:

- courses
- forms
- courseWorks
- courseWork Materials
- topics

Most of these objects have functions that do the following:

- `get_<object>_list()`
- `create_<object>()`
- `get_<object>_properties()`
- `delete_<object>()`

For example:

`get_course_list(owner_id)` retrieves a list of courses for a particular owner id. `create_course()` creates a course `get_course_properties(course_id)` retrieves the properties of a course given its id.

These can be built together to be pretty nifty.

## Example workflow

Run the function to authorize the app to use your Google account.

    authorize()

Retrieve whatever your owner id for Google Classroom is.

    owner_id <- get_owner_id()

Now you can retrieve a list of courses that are associated with your owner id.

    course_df <- get_course_list(owner_id)

For the following examples, we will need to use

    Create a course
    new_course <- create_course(owner_id$id, name = "New course")

### Managing materials

We can create new material for the students using by building this together like this:

    # Create a course we will use for this test
    owner_id <- get_owner_id()
    new_course <- create_course(owner_id$id, name = "New course")

    # Create material at this course
    new_material <- create_material(course_id = new_course$id,
                                    title = "New material")

    # Retrieve the material info
    materials_info <- get_materials_properties(course_id = new_course$id,
                                                 materials_id = new_material$id)

Retrieve the list of all the materials for the course

    materials_list <- get_materials_list(course_id = new_course$id)

### Managing courseworks

We can manage courseworks!

It’s mandatory from the Google API that due dates for courseworks be given.

    # Create a new coursework
    new_coursework <- create_coursework(course_id = new_course$id,
                                        title = "New coursework",
                                        due_date = lubridate::today() + lubridate::hours(24))

    # Get coursework properties
    course_work_info <- get_coursework_properties(course_id = new_course$id, coursework_id = new_coursework$id)

    # Retrieve all the courseworks for this course
    coursework_list <- get_coursework_list(course_id = new_course$id)

### Make a quiz

We can build a quiz like this:

    course_id <- get_course_list()$courses$id[1]

    quiz_form_id <- create_quiz(
      course_id = course_id,
      quiz_title = "new quiz",
      quiz_description = "This is a great quiz",
      due_date = "2025-12-1")

We can create a new multiple choice question in the quiz we just made by using these steps:

    create_multiple_choice_question(
      form_id = quiz_form_id$formId,
      question = "What answer do you want?",
      choice_vector = c("A", "B", "C", "D"),
      correct_answer = 3,
      shuffle_opt = TRUE
    )

We can create a text question in the quiz by doing this:

    create_text_question(
      form_id = quiz_form_id$formId,
      question = "Put some text here to answer this question",

    )

### Delete or archive courses

Before you can delete a course, you have to archive it:

    archive_course(new_course$id)

Then we can delete it:

    delete_course(new_course$id)

    sessionInfo()

    ## R version 4.4.0 (2024-04-24)
    ## Platform: x86_64-apple-darwin20
    ## Running under: macOS 15.3.2
    ##
    ## Matrix products: default
    ## BLAS:   /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRblas.0.dylib
    ## LAPACK: /Library/Frameworks/R.framework/Versions/4.4-x86_64/Resources/lib/libRlapack.dylib;  LAPACK version 3.12.0
    ##
    ## locale:
    ## [1] C/en_US.UTF-8/en_US.UTF-8/C/en_US.UTF-8/en_US.UTF-8
    ##
    ## time zone: America/New_York
    ## tzcode source: internal
    ##
    ## attached base packages:
    ## [1] stats     graphics  grDevices utils     datasets  methods   base
    ##
    ## loaded via a namespace (and not attached):
    ##  [1] digest_0.6.37     R6_2.5.1          fastmap_1.2.0     xfun_0.50
    ##  [5] cachem_1.1.0      knitr_1.49        htmltools_0.5.8.1 rmarkdown_2.29
    ##  [9] lifecycle_1.0.4   cli_3.6.3         sass_0.4.9        jquerylib_0.1.4
    ## [13] compiler_4.4.0    rstudioapi_0.17.1 tools_4.4.0       evaluate_1.0.3
    ## [17] bslib_0.8.0.9000  yaml_2.3.10       rlang_1.1.5       jsonlite_1.8.9