# sagemath/sagecell

Switch branches/tags
Nothing to show
Fetching contributors…
Cannot retrieve contributors at this time
462 lines (321 sloc) 12.1 KB

# Embedding Sage Cells

You can embed multiple customized Sage cells in arbitrary webpages. Customizable options include location of input and output and functionality shown to the user.

## Example

This is a very simple HTML page showing how to embed two cells with most things turned off and a default piece of code (you can replace `sagecell.sagemath.org` with a different SageMathCell server, if you like):

```<!DOCTYPE HTML>
<html>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width">
<title>SageMathCell</title>
<script src="https://sagecell.sagemath.org/static/embedded_sagecell.js"></script>
<script>
// Make the div with id 'mycell' a Sage cell
sagecell.makeSagecell({inputLocation:  '#mycell',
template:       sagecell.templates.minimal,
evalButtonText: 'Activate'});
// Make *any* div with class 'compute' a Sage cell
sagecell.makeSagecell({inputLocation: 'div.compute',
evalButtonText: 'Evaluate'});
</script>
<body>
<h1>Embedded Sage Cells</h1>

<h2>Factorial</h2>
Click the &ldquo;Activate&rdquo; button below to calculate factorials.
<div id="mycell"><script type="text/x-sage">
@interact
def _(a=(1, 10)):
print factorial(a)
</script>
</div>

Type your own Sage computation below and click &ldquo;Evaluate&rdquo;.
<div class="compute"><script type="text/x-sage">plot(sin(x), (x, 0, 2*pi))</script></div>
<div class="compute"><script type="text/x-sage">
@interact
def f(n=(0,10)):
print 2^n
</script></div>
</body>
</html>```

## Basic Usage

The following line should be inserted into `<head>`:

`<script src="https://<server>/static/embedded_sagecell.js"></script>`

where `<server>` is the root url of a SageMathCell server. This downloads additional required JavaScript and CSS libraries and creates a global JavaScript object called `sagecell`. Use :ref:`sagecell.init() <sagecell.init_embed>` for more configuration options upon initialization, including callback functionality.

Later, the following JavaScript should be run:

`sagecell.makeSagecell({inputLocation: "[jQuery selector]"});`

This creates basic Sage cells at the locations matching `inputLocation`. See the documentation for :ref:`sagecell.makeSagecell() <sagecell.makeSagecell>` for more configuration options. This function returns an object containing information necessary to later move portions of or remove the entirety of the Sage cell if desired.

`sagecell.makeSagecell()` can be called multiple times to embed multiple Sage cells, as long as the input (and output, if specified) locations of each call are unique to the page.

To remove a Sage cell, the following JavaScript can be used:

`sagecell.deleteSagecell(sagecellInfo);`

where `sagecellInfo` is the object returned upon that Sage cell creation by `sagecell.makeSagecell()`.

Sage cells can be safely embedded within HTML forms (even though each cell contains form elements) since those form elements are copied to a hidden form outside of the embedded context. However, in such a case, it may not be optimal for external form submission to include cell elements. To prevent this issue, the following JavaScript can be used before and after form submission to move and restore the Sage cell:

```sagecell.moveInputForm(sagecellInfo); // before submission
sagecell.restoreInputForm(sagecellInfo); // after submission```

where `sagecellInfo` is the object returned upon that Sage cell creation by `sagecell.makeSagecell()`.

## Customization

All customization occurs through `sagecell.makeSagecell()`, which takes a dictionary as its argument. The key/value pairs of this dictionary serve as the configuration of the created Sage cell. The following options can be set when embedding:

### Input Location

This sets the location of the input elements of a Sage cell, which includes the editor, mode selector, and the evaluate button:

```{ ..
inputLocation: "#..."
.. }```

The `inputLocation` argument (required) should be a jQuery selector (which may actually return more than one DOM element --- each one will be made into a Sage cell). If a DOM node is a textarea, the textarea will be used as the basis for the code input box (this can be helpful if you are trying to make an existing form textarea a live Sage cell).

### Output Location

This sets the location of the output elements of a Sage cell, which includes the session output and server messages:

```{ ..
outputLocation: "#..."
.. }```

The `outputLocation` argument should be a jQuery selector for a single DOM node. If `outputLocation` is not specified, it defaults to the same selector as `inputLocation`.

### Code Editor

This sets the type of code editor:

```{ ..
editor: "editor type"
.. }```

Available options are:

• `codemirror` - default, CodeMirror editor, which provides syntax highlighting and other more advanced functionality
• `codemirror-readonly` - like `codemirror`, but not editable
• `textarea` - plain textbox
• `textarea-readonly` - like `textarea`, but not editable

### Default code

This sets the initial content of the code editor:

```{ ..
code: "code"
.. }```

The value of the `code` argument should be a string of Python/Sage code.

Code editor content can also be set using the `codeLocation` argument:

```{ ..
codeLocation: "#..."
.. }```

The `codeLocation` argument should be a jQuery selector for a single DOM node. This node should be a `SCRIPT` element of type `text/x-sage` containing the default Python/Sage code:

```    <script type="text/x-sage" id="mycode">
print("Here's some code!")
print("Hello World")
</script>```

Note that all whitespace is preserved inside of the `<script>` tags. Since the Python/Sage language is whitespace-sensitive, make sure to not indent any lines unless you really want the indentation in the code.

```.. todo::

strip off the first blank line and any beginning
whitespace, so that people can easily paste in blocks of code and
have it work nicely.

```

If the code parameter is not set, the code location is examined for code. If no code is found there, the JavaScript attempts to restore in the editor whatever the user had in that particular cell before (using the web browser's session storage capabilities). If that fails, the editor is initialized to an empty string.

When multiple input locations are given, this sets whether the code from these cells is to be executed from the same kernel, so that code executed in one will affect the execution of code from another cell:

```{ ..
.. }```

This option is `false` by default.

### Evaluate button text

This sets the text of the evaluate button:

```{ ..
evalButtonText: "text"
.. }```

### Languages

This sets the list of languages that can be evaluated in the Sage cell:

```{ ..
languages: ["sage", ...]
.. }```

Possible values in this array are `"sage"`, `"gap"`, `"gp"`, `"html"`, `"maxima"`, `"octave"`, `"python"`, `"r"`, and `"singular"`. If more than one language is specified in this option, a selection box will appear to allow the user to select a language.

The default value is `["sage"]` (only Sage code allowed). To allow all of the available languages, use the value `sagecell.allLanguages` in place of the array.

### Managing subsequent sessions

This sets whether subsequent session output (future Sage cell evaluations) should replace or be displayed alongside current session output:

```{ ..
replaceOutput: boolean
.. }```

### Automatic evaluation

This sets whether the code from the `code` option will be immediately evaluated, without the need for pressing a button:

```{ ..
autoeval: boolean
.. }```

Caution!

Please use this option sparingly, especially with `@interact`, to decrease the load on servers. Unless majority of users who open your page are likely to use this cell, let them press a button to trigger evaluation.

### Callback

This is a function with no arguments that will be called after SageMathCell has finished loading:

```{ ..
callback: function
.. }```

### Hiding Sage Cell elements

This hides specified parts of the Sage cell using CSS `display: none`:

```{ ..
hide: ["element_1", ... , "element_n"]
.. }```

The following input elements can be hidden:

• Editor (`editor`)
• Full screen button (`fullScreen`) - note that it is still possible to switch to full screen via keyboard
• Language selection box (`language`)
• Evaluate button (`evalButton`)

The following output elements can be hidden:

• Share button to permalinks (`permalink`)
• Session output (`output`)
• Session end message (`done`)
• Session files (`sessionFiles`)

Additionally, the following debugging elements are hidden by default:

• Message logging (`messages`)
• Session title (`sessionTitle`)

These elements can be displayed in :ref:`debug_mode`.

### Templates

Templates provide an alternative way to set certain Sage cell properties and are designed to simplify the process of embedding multiple cells on the same page. A template is a JavaScript dictionary with key/value pairs corresponding to desired key/value pairs given to `sagecell.makeSagecell()`.

Within `sagecell.makeSagecell()`, a template can be applied with the following:

```{ ..
template: template_name
.. }```

The following options can be specified within a template dictionary (see the documentation for :ref:`customization <Customization>` for full syntax information, as these options mirror what can be given to `sagecell.makeSagecell()`).

• Hiding Sage cell elements:
```{ ..
hide: ["element_1", .. , "element_n"]
.. }```
• Editor type:
```{ ..
editor: "editor type"
.. }```
• Evaluate button text:
```{ ..
evalButtonText: "text"
.. }```
• Language selection:
```{ ..
languages: ["sage", ...]
.. }```
• Replacing or appending subsequent sessions:
```{ ..
replaceOutput: boolean
.. }```
• Automatic evaluation:
```{ ..
autoeval: boolean
.. }```

There are two built-in templates in `sagecell.templates` which are designed for common embedding scenarios:

• `sagecell.templates.minimal`: Prevents editing and display of embedded code, but displays output of that code when the Evaluate button is clicked.
• `sagecell.templates.restricted`: Displays a read-only version of the code.

Explicit options given to `sagecell.makeSagecell()` override options described in a template dictionary, with the exception of `hide`, in which case both the explicit and template options are combined.

### Debug Mode

A special "debug" mode is avaliable by passing the following to `sagecell.makeSagecell()`:

```{ ..
mode: "debug"
.. }```

This shows all page elements (overriding `hide` specification), which provides session titles and sent / recieved message logging that are otherwise hidden by default. Since this mode is not intended for production purposes, a browser warning will be raised when initializing a Sage cell in debug mode.