Author Guide

This authoring guide will start you off creating a very simple code exercise, and then walk you through adding on features like solutions and test code.

For all of these examples, you will see a markdown specification immediately followed by the code cell that that markdown woud produce. You can also copy the markdown specification into our custom previewer if you'd like to experiment.

The Basics

With ckcode, coding exercises are specified using HTML or markdown. It doesn't really matter which you use as long as your deployment is set up to convert the markdown format to HTML (it is set up this way on CourseKata).

Here is the simplest R code exercise you can create:

```{ data-ckcode #empty data-submittable=false }

```

This will render a cell with nothing pre-populated in the editor, along with the Run and Reset buttons. Students can type whatever they want into the editor and click Run to execute it on the server. The Reset button will clear the editor.

Some notes on this exercise:

• All ckcode specifications need to have some attributes set. In markdown you can set attributes on a fenced code block (i.e., code blocks that start and end with three backticks ```) using curly brackets. The attributes for this exercise are data-ckcode #empty data-submittable=false.
  • The data-ckcode attribute tells the loader that this is a code exercise.
  • This exercise is given the ID "empty" by setting #empty in the attributes. IDs are mandatory for some of the ckcode features (like remembering last response and properly recording submissions). IDs must be unique.
  • The data-submittable=false attribute is needed to prevent ckcode from thinking this is a submittable exercise (more on submittable exercises later).

Change the Language

By default, ckcode will render the editor in R. You can change this by setting the data-language attribute. Here is an example that renders the editor in Python:

```{ data-ckcode #python data-language=python data-submittable=false }

```

Customizing the Prompt

Most of the time you will want users to complete a particular task in the cell. To help with this, you can pre-populate the editor with some code. Here is an example that gives students some stem code to work with:

```{ data-ckcode #stemmed data-submittable=false }
%%% prompt
# fit a linear model predicting mpg from hp
lm(   , data = mtcars)
```

%%% prompt
# fit a linear model predicting mpg from hp
lm(   , data = mtcars)

The prompt is specified by a section prompt which is set off by three percent signs (%). The prompt can be any valid R code. When the exercise is rendered, the prompt will be pre-populated in the editor. Students can edit the prompt and click Run to execute it on the server. The Reset button will clear the editor and re-populate it with the prompt.

Checking Student Code

The Simplest Solution

If you are using these exercises in an educational context, you will likely want to be able to automatically test student code. To do this, you will need to add a solution and some test code to the exercise.

Here is the simplest solution you can add:

```{ data-ckcode #simple-solution }
%%% prompt
# try running this code
lm(mpg ~ hp, data = mtcars)

%%% solution
# no solution

%%% test
ex() %>% check_error()
```

%%% prompt
# try running this code
lm(mpg ~ hp, data = mtcars)

%%% solution
# no solution

%%% test
ex() %>% check_error()

This item has two new sections solution and test, both of which are needed to make an item submittable. Note that it also omits data-submittable=false. As a result, the exercise now has a Submit button. If you click Submit, you will see that the exercise is scored as correct for any code that does not produce an error.

The test section is code that will be run in a lightly wrapped implementation of DataCamp's testwhat package (R) (or pythonwhat if you are using Python). We support most of the features of that package, but not all (think like 95%). If you find something that is not supported, please email Adam for advice on a workaround or for a feature implementation.

A More Complex Solution

The next exercise is an example of how you might check that a student called the lm() function correctly and got the expected result.

```{ data-ckcode #more-complex }
%%% prompt
# fit a linear model predicting mpg from hp
lm(   , data = mtcars)

%%% solution
# fit a linear model predicting mpg from hp
lm(mpg ~ hp, data = mtcars)

%%% test
ex() %>%
  check_function("lm") %>%
  check_result() %>%
  check_equal()
```

%%% prompt
# fit a linear model predicting mpg from hp
lm(   , data = mtcars)

%%% solution
# fit a linear model predicting mpg from hp
lm(mpg ~ hp, data = mtcars)

%%% test
ex() %>%
  check_function("lm") %>%
  check_result() %>%
  check_equal()

This exercise has the same prompt as the previous one, but the solution and test are different. The solution is now the correct code, and the test is a little more complex. The test code is a series of check_ functions that are chained together. The first checks that the student called the lm() function. The second and third check that the result of the function call is the same as the solution. If either of these checks fail, the student will get feedback on what went wrong.

The solution code is mandatory here because of the way that testwhat works. When the code is submitted, both the student's code and the solution code are run independently. The results are passed to the test code which compares them. If you do not provide a solution, the test code will usually fail because it will not have anything to compare to.

Hiding setup code

Often, you will use different libraries or packages to simplify coding and keep coding challenges relevant to the learning process (as opposed to tedium). The code to load those libraries can clutter up the editor and the student's headspace, so you can move them to a setup area. The code in the setup area is run before the submission code is run. Here is an example that loads a library for the user invisibly:

```{ data-ckcode #setup data-submittable=false }
%%% setup
library(forcats)

%%% prompt
# try running this --- the forcats package was loaded in the background
fct_lump
```

%%% setup
library(forcats)

%%% prompt
# try running this --- the forcats package was loaded in the background
fct_lump

Notice that the setup section does not populate into the editor, but when you run the code you will get the expected result (the body of the fct_lump function). If you were to omit the setup here, you will see that the fct_lump function is not available (you will get a message that says, Error: object 'fct_lump' not found). So even though you can't see the setup code here, it runs and loads the package for you!

Resources

You should now have all the information you need for specifying code exercises using ckcode! That said, writing these specifications can get tricky, especially when it comes to writing code to test student responses. Here are a couple resources to help with that:

• Authoring tool: this page has an editor that will help you write and edit specifications for exercises. It is useful for testing things out without having to build a whole website.
• testwhat documentation: help and specs for writing test code for R exercises
• pythonwhat documentation: help and specs for writing test code for Python exercises
• Questions, comments, concerns? Let us know and we can work on it!