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.

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 code exercise you can create:

HTML

<code-cell id="empty"></code-cell>

Markdown

```{ data-ckcode=true #empty }

```

Rendered exercise

As you can see, it will render a cell with nothing pre-populated in the editor, along with the Run, Submit, and Reset buttons.

Try running some code in the cell, then refresh the page. You should see the same code you ran still in the editor. The cell below does not have an ID set for it. If you try running code and refresh the page, you will see that the cell resets.

Removing the Submit Button

The example above renders an empty cell. You can provide cells like this so that students have a scratchpad or sandbox to use. Generally, you don't need students to submit their code from scratchpads, so you can turn off the submit button.

HTML

<code-cell id="no-submit" preventSubmit></code-cell>

Markdown

```{ data-ckcode=true #no-submit data-submittable=false }

```

Rendered exercise

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:

HTML

<code-cell id="stemmed" preventSubmit>
  <code data-type="prompt">
    # fit a linear model predicting mpg from hp
    lm( , data = mtcars)
  </code>
</code-cell>

Markdown

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

Rendered exercise

Testing Student Code

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.

In the next example, note that there is now a solution and test code added. We currently only support using the testwhat package from DataCamp. Under that testing framework, the test code is used to compare the submitted code against the solution. Here we are just checking that the output of the lm() function is the same for both:

HTML

<code-cell id="testable">
  <code data-type="prompt">
    # fit a linear model predicting mpg from hp
    lm( , data = mtcars)
  </code>
  <code data-type="solution">
    # fit a linear model predicting mpg from hp
    lm(mpg ~ hp, data = mtcars)
  </code>
  <code data-type="test">
    ex() %>%
      check_function("lm") %>%
      check_result() %>%
      check_equal()
  </code>
</code-cell>

Markdown

```{ data-ckcode=true #testable data-submittable=false }
%%% 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()
```

Rendered exercise

Try running the cell. The Run button works the same as before. However, when you click Submit, a little extra happens. The submitted code and the test and solution code are both sent off for evaluation. Once that evaluation happens, the feedback is piped back and displayed. (Try lm(mpg ~ hp, data = mtcars) to get the feedback for a correct response.)

Hiding setup code

For most programming languages, you will use different libraries or pacakges to simplify coding or access datasets. The code to load those libraries can clutter up the editor, 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:

HTML

<code-cell id="setup">
  <code data-type="setup">
    library(forcats)
  </code>
  <code data-type="prompt">
    # try running this --- the forcats package was loaded in the background
    fct_lump
  </code>
</code-cell>

Markdown

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

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

Rendered exercise

You'll notice that if you try running the same code in any of the other cells, 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: currently only the DataCamp testwhat package is supported for writing test code. If you would like to use a different testing framework, please let us know and we can work on it!