Creating a New Module

This page contains a guide for Source Module authors to create their very own Source Module, complete with a bundle and a tab. The following set of pages assumes knowledge of the contents highlighted in the preceding 3 pages, namely the Development Guide page here, the Getting Started page here and the File page here.

Introduction

In this guide, we will be creating a Source Module called drawing. This example Source Module aims to give Source programs the opportunity to draw onto a HTML Canvas element, using a two dimensional array of pixels. Each pixel is a length 4 array of integers between 0 and 255 inclusive for the red, blue, green and alpha components respectively.

Creating the Source Module and Source Module Bundle

Ensure that your Source Modules code repository has alredy been set up properly. If this is not the case, please refer to the guide here on how to set up a local copy of the Source Modules code repository with the Source Implementations js-slang and Source Academy Frontend cadet-frontend.

To create a new module, run the module script in your favourite shell's command line interface at the root directory of the Source Modules code repository. Answer the questions that follow accordingly.

yarn run create
> What would you like to create? (module/tab)
module
> What is the name of your new module? (eg. binary_tree)
drawing

Your new drawing Source module should be added into the modules.json manifest file automatically with no tabs. A new folder drawing should also be created within the src/bundles directory consisting of a single file index.ts that is the entry point to your Source Module Bundle's implementation. Below is the updated modules.json file.

{ ..., "test": { "tabs": [] }, ... }

And below is the updated repository structure of the src directory

src
 ├── bundles
      ├── drawing
           ├── index.ts
 ├── tabs

Within the index.ts entry point at the root directory of the Source Module Bundle, the following sample should be generated.

// Un-comment the next line if your bundle requires the use of variables
// declared in cadet-frontend or js-slang.
// import __Params from '../../typings/__Params';

/**
 * <Brief description of the module>
 * @author <Author Name>
 * @author <Author Name>
 */

/**
 * Increment a number by a value of 1.
 * @param x the number to be incremented
 * @returns the incremented value of the number
 */
function sample_function(x: number) {
  return x + 1;
}

// Un-comment the next line if your bundle requires the use of variables
// declared in cadet-frontend or js-slang.
// export default (_params: __Params) => ({
export default () => ({
  sample_function,
});

To test that the new Source Module's Bundle has been set up correctly, transpile your Source Modules, start up the Source Modules local static server and your local instance of Source Academy frontend by using the following commands.

At the root directory of the Source Modules code repository, run the following commands.

yarn run build
yarn run serve

At the root directory of the Source Academy frontend code repository, run the following commands.

yarn start

Navigate to the Source Academy playground in your local instance of Source Academy and run the following Source program. Check that the result of the evaluation as shown in the Source Academy REPL is 2 and that the evaluation does not result in any errors.

import { sample_function } from "drawing"; 

sample_function(1);

Creating the Source Module Tab

To add a new tab to your Source Module, run the module script in your favourite shell's command line interface at the root directory of the Source Modules code repository. Answer the questions that follow accordingly.

yarn run module
> What would you like to create? (module/tab)
tab
> Add a new tab to which module?
drawing
> What is the name of your new tab? (eg. BinaryTree)
DrawingCanvas

Your new DrawingCanvas Source Module Tab should be added into the modules.json manifest file automatically. A new folder DrawingCanvas should also be created within the src/tabs directory consisting of a single file index.tsx that is the entry point to your Source Module Tab's implementation. Below is the updated modules.json file.

{ ..., "test": { "tabs": [ "DrawingCanvas" ] }, ... }

And below is the updated repository structure of the src directory

src
 ├── bundles
      ├── drawing
           ├── index.ts
 ├── tabs
      ├── DrawingCanvas
           ├── index.tsx

Within the index.tsx entry point at the root directory of the Source Module Tab, the following sample should be generated.

import React from 'react';

/**
 * <Brief description of the tab>
 * @author <Author Name>
 * @author <Author Name>
 */

/**
 * React Component props for the Tab.
 */
type Props = {
  children?: never;
  className?: never;
  context?: any;
};

/**
 * React Component state for the Tab.
 */
type State = {
  counter: number;
};

/**
 * The main React Component of the Tab.
 */
class Repeat extends React.Component<Props, State> {
  constructor(props) {
    super(props);
    this.state = {
      counter: 0,
    };
  }

  public render() {
    const { counter } = this.state;
    return (
      <div>This is spawned from the repeat package. Counter is {counter}</div>
    );
  }
}

export default {
  /**
   * This function will be called to determine if the component will be
   * rendered. Currently spawns when the result in the REPL is "test".
   * @param {DebuggerContext} context
   * @returns {boolean}
   */
  toSpawn: (context: any) => context.result.value === 'test',

  /**
   * This function will be called to render the module tab in the side contents
   * on Source Academy frontend.
   * @param {DebuggerContext} context
   */
  body: (context: any) => <Repeat context={context} />,

  /**
   * The Tab's icon tooltip in the side contents on Source Academy frontend.
   */
  label: 'Sample Tab',

  /**
   * BlueprintJS IconName element's name, used to render the icon which will be
   * displayed in the side contents panel.
   * @see https://blueprintjs.com/docs/#icons
   */
  iconName: 'build',
};

To test that the new Source Module's Tab has been set up correctly, transpile your Source Modules, start up the Source Modules local static server by using the following commands at the root directory of the Source Modules code repository.

yarn run build
yarn run serve

Remember to also empty cache and hard reload your local instance of Source Academy frontend on your browser.

Navigate to the Source Academy playground in your local instance of Source Academy and run the following Source program. Check that the result of the evaluation as shown in the Source Academy REPL is "test" and that the evaluation does not result in any errors.

import { sample_function } from "drawing"; 

sample_function(1);
"test";

Also, a new side content tab with a hammer icon should be spawned. In the tab, there should be a line of text corresponding to the program in index.tsx at the root directory of your Source Module Tab. Check that evaluating a Source program that does not return the string "test" in the REPL cause the side content tab to despawn.