Guide for Authors

To look at the definition of a pre-existing exercise/example on the site, click the blue </> link on its bottom-right corner. (Seeing these links requires that you are logged in.) To look at the definition of an entire page on the site, click the  icon on its bottom-right corner. Use these as examples. They are released under a Creative Commons Non-Commerical Share-Alike 3.0 License. The backend code is available on GitHub.

If you are interested in authoring but don't want to install CS Circles on your own, please contact us for a sandbox account.

This page documents the various shortcodes that are used to describe elements of a CS Circles lesson. The idea of shortcodes is not unique to CS Circles, they come from WordPress. However, we have added a number of new shortcodes to our site.

If you've never used WordPress before, the most important thing to know is that shortcodes extend the language of HTML, and it is in this extended language that page content is written. So any valid HTML will also be valid inside of a CS Circles lesson, for example this lets us use bulleted lists (e.g. see Lesson 0), boldface, italics, tables, images, colored text, headings, etc. The WordPress "Visual Editor" means that you don't have to be an HTML expert to write lessons since it will do this formatting for you in a graphical way where you need it. But some basic knowledge of HTML is very useful.

We start with some basic examples of how shortcodes are like an extension of HTML. Then we go over the ones we think will be most useful in creating lessons. Then we describe the more specialized ones.

In some cases it is easier to write lessons in HTML mode, which you can access here once your account has editor permission:

Warmup: collapsible and accordion

The collapsible is a basic example of a UI element; its goal is to provide some information that can be expanded or collapsed. It is analogous to the anchor (a) html tag, which you probably know is written in source as

<a href="http://cscircles.ca">linked text</a>
and which causes this to be displayed: linked text

The code to create a collapsible element is:

[collapsible caption="your caption here"] shown or hidden body [/collapsible]
and  this results in the following being displayed, which you can click to expand or collapse:

your caption here
shown or hidden body

See how clicking opens and closes it?

If you want a collapsible that is open by default, add the show valueless argument:

[collapsible show caption="..."] ... [/collapsible]
Next, accordion elements are used to group several collapsible elements so that when one is opened, all others close. It takes no arguments; the most basic example is

[accordion]
[collapsible caption="title 1"] body 1 [/collapsible]
[collapsible caption="title 2"] body 2 [/collapsible]
[/accordion]
This generates:

title 1
body 1

title 2
body 2

Note that if body 1 is open, clicking on title 2 both opens body 2 and closes body 1.

Shortcodes for Python: pyExample, escaping, and @file: references

The pyExample shortcode lets you show a small example program. You specify the code, a title, and optionally a description. For instance,

[pyExample code="print(2*2)" title="Hip to be square"]Optional description[/pyExample]
will produce

Example: Hip to be square
Optional description

There are numerous additional options for pyExample, in fact they are the same as for pyBox, but we talk about these options later on. Instead, let us mention escaping in shortcodes. For example, what if you want your example code argument to contain double-quotes? There are a few rules you should know and that you can take advantage of:

  • the following applies to shortcode arguments, but not shortcode bodies
  • you can use single quotes to contain arguments instead of double quotes
  • you can use backslashes to escape either quote, newlines, and backslashes
  • real newlines (pressing Enter) also work, but not several in a row (due to WordPress editor limitations)

For example, mixing a few of these:

[pyExample code='print(1)

print(\'four\')\nprint("9")' title="It's hip to be square"] [/pyExample]
This gives:
Example: It's hip to be square

Sometimes it is awkward to correctly type out a chunk of code with lots of escaping. For this reason you also can use an @file: reference. This tells Python to go fetch a file from the file system (in the wp-content/lesson_files folder) and use it as the value of that argument; no escaping is needed within that file. An example in Lesson 2 is:

[pyExample code="@file:lesson2/printy.py"] [/pyExample]
which generates

Example

You can see the actual contents of the printy.py file here.

Let us mention that the body of a shortcode doesn't need escaping. The body of a shortcode can contain more shortcodes, but shortcode arguments can't contain shortcodes (this is more or less analogous to HTML).

The remaining sections are shown below in an accordion. You do not have to read them in order.

Coding exercises: pyBox (& pyScramble)

The pyBox shortcode is used to define exercises in our system. It can be used in many different ways and accordingly, it has a lot of different options. We'll mostly describe the elements by example.

Basics: input/stdin, solver (model solution), body

[pyBox input1='2' input2='3' solver='print(-int(input()))'] Read an integer from input and print its negative. [/pyBox]
WARNING: this problem needs a permanent slug to save user data
Coding Exercise
Read an integer from input and print its negative.

If you only have one test case, you can write input instead of input1.

Generating random test cases: generator (and repeats)

[pyBox generator="print(_rint(10, 100))" repeats=3 solver='print(-int(input()))'] [/pyBox]
WARNING: this problem needs a permanent slug to save user data
Coding Exercise

Here, _rint is a short-form for Python's random.randint function, defined here in a utilities file.

Evaluating a student-defined function: autotests

Whereas the previous examples give students input through stdin and check their output through stdout, the second testing paradigm is to make them define functions. Then the exact type and value of the function's return value of the student's code is compared to that of the solver code.

[pyBox solver="def square(x): return x*x" autotests="square(3)\nsquare(4)"] Define a function square(x) that takes a number x and returns its square. [/pyBox]
WARNING: this problem needs a permanent slug to save user data
Coding Exercise
Define a function sqr(x) that takes a number and returns its square.

To do this with repetition and randomization, use this construction instead:

autotests="for i in range(3):\n   square(_rint(1, 100))"

Pre-defining user variables/functions: precode

You can define a utility function for the user (see 11c.rightperimeter for an example), or use a variable as a way of providing test input (see 1.heads for an example).

[pyBox solver="print(mynum*mynum)" precode="mynum=_rint(1, 100)" repeats=2] The grader will define a variable <code>mynum</code> for you. Print out its square.[/pyBox]
WARNING: this problem needs a permanent slug to save user data
Coding Exercise
The grader will define a variable mynum for you. Print out its square.

Testing user variables: autotests

The autotests argument not only can be used to call functions (like above) but it also can be used to test variables. This is often used with precode, see for example 1.swap.

[pyBox autotests="x" solver="x=5"]Define a variable x equal to the number five.[/pyBox]
WARNING: this problem needs a permanent slug to save user data
Coding Exercise
Define a variable x equal to the number five.

Default Code (code) and Code Scrambles: pyScramble

To create a Code Scramble exercise, use pyScramble instead of pyBox:

[pyScramble solver="a=1\nb=a+1\nc=b+1"] Make this not crash.[/pyScramble]
WARNING: this problem needs a permanent slug to save user data
Scramble Exercise
Make this not crash.
  • c=b+1
  • b=a+1
  • a=1

The solver code is randomly permuted initially. A better option is to use code (or its synonym defaultcode) to start the student in some well-scrambled state.
Note: you also can use defaultcode in non-scrambled pyBox exercises if you want to give the student a template, or a buggy program to debug.

Other useful pyBox arguments

  • title: Gives a title at the top of the exercise. Mandatory for exercises when published.
  • slug: A permanent unique identifier like 1.swap or 11c.rightperimeter. Mandatory for exercises when published. Use only letters, numbers and periods. It is not user-facing but is needed for internal use; even if you change some problem options, as long as the slug stays the same the history will be remembered by the system.
  • taboo: comma-separated list of keywords (like "for, while", space optional) which can not appear in the submitted code. Each keyword optionally is of the form display|regex where regex is the regex to search for and display is what to display to the user. E.g., taboo="lower|\\.lower" would say "lower is not allowed" but searches for regex "*\.lower"
  • desirederror: (e.g. lesson 6) use this when you want the student to create an error. The last line of stderr is compared with the string passed as desirederror. The exercise is completed successfully if they match. See an example here.
  • grader: By default, when there is output to be compared, exercises use a grader that compares the output to see if it is exactly equal to the expected one. To override this, grader should be defined equal to a chunk of Python code which (a) takes string array variables InputLines, ExpectedLines, and OutputLines, (b) prints out Y if the output is deemed correct and N otherwise, and (c) prints out any additional feedback (typically only for incorrect cases) after that first character. See one of several predefined graders for examples: @file:anyorder.py, @file:real-per-line.py, and @file:warmup.py.
  • generator: Python code that prints procedurally-generated stdin. See 9.abs for an example.
  • maxeditdistance: Enforces a maximum number of changed characters from the original program. See 1e.joe for an example.

Non-coding exercises: pyShort, pyMulti, pyMultiScramble

These are short-answer exercises, multiple-choice exercises, and unscrambling exercises. All three accept an epilogue option which is a string (or file reference) to give an extra message once the problem is completed correctly. They should have a title and slug the same as pyBox does.

Short Answer: pyShort

[pyShort answer="Q"]what is the letter after P?[/pyShort]
Short Answer Exercise
what is the letter after P?
Correct!

Arguments:

  • answer: the correct answer
  • type (optional): put "number" to treat "5.00" the same as "+5" etc. If left out, string comparison is used. See 1.plusminus for example.

Multiple Choice: pyMulti

[pyMulti right="correct answer" wrong="bad1\nbad2\n..."]Body[/pyMulti]
WARNING: this problem needs a permanent slug to save user data
Multiple Choice Exercise
Body
Correct!

Descrambling (without code): pyMultiScramble

[pyMultiScramble answer="put this first\nsecond\nthird\n4"] content [/pyMultiScramble]
WARNING: this problem needs a permanent slug to save user data
Scramble Exercise
content
  • third
  • second
  • 4
  • put this first
Correct!

See an example at 12.ordering.

Idiomatic information for the user: pyHint, pyLink, pyWarn, latex

pyWarn

Gives a warning.

[pyWarn] Warning text [/pyWarn]
Warning text

pyHint

Gives a clickable pop-up hint (also consider using collapsible hints).

Here's a [pyHint hint="the hint text"]hint[/pyHint]!
Here's a hint!

pyLink

Gives a clickable link to code in the console.

This [pyLink code='print("|"*10)']link[/pyLink] rules.
This link rules.



Note: often we use an @file: reference for the code parameter.

latex (WP-latex plugin)

\displaystyle{f = c \times \frac{9}{5} + 32}
\displaystyle{f = c \times \frac{9}{5} + 32}

Fine-tuning HTML: br, pyRaw, style

  • Despite significant effort, we are unable to get newlines to work well inside of shortcode bodies. This has to do with WordPress' "autop" system that automagically determines where to put <p> and </p> tags. To compensate for this, we define the shortcode

    which forces an html <br> newline to occur.
  • If you need specific html that the visual editor mangles, use
    @file:filename
    which will put the contents of the specified file at that location, after all other processing on the page is done. We use this in lessons 6, 8, and 9.
  • If you want specific css styles on your page, use the style shortcode. For example, 
     <h6>Ta-da</h6>
    creates

    Ta-da

The rest: authorship, pyRecall, youtube, pyVis

  • Write
    to indicate the authorship history of a lesson. Look at the source code of any page for an example.
  • Use pyRecall for translation. See more information on the Translation Notes page.
  • Use youtube to embed a youtube video. See lesson 7a for an example.
  • Use pyVis to do an embedded visualization. For example 
    [pyVis code='x = 2\nx += 1']

    The visualization will be cached unless the word "random" appears in the source code.

Help: for help with authoring problems, please create a new issue at https://github.com/cemc/cscircles-wp-content/issues