Skip to content

Embedding Guide

Andrew Brogdon edited this page Jul 26, 2019 · 11 revisions

Original Embedding UI

List of Query Elements

  • id (gist ID) to load a gist ID
  • line (line number) to jump to a line
  • verticalRatio (0 to 100) [Embed only]
  • horizontalRatio(0 to 100) [Embed only]
  • run (run = true) to autorun [Embed only]
  • strong (strong = false) to disable strong mode (enabled by default)

Embedded views exported in strong mode will land in the main dartpad web client with strong mode enabled.

So, you want to embed a code snippet into your website? No worries, it's simple!

DartPad offers 3 different embedding choices for shared code. You have the option to show:

  1. Dart, Console, and Documentation [embed-dart]
  2. Dart, Console, and Html Output (with options to modify HTML/CSS) [embed-html]
  3. Dart and Console (Minimal) [embed-inline]

DartPad pages use query parameters in the URL to retrieve & show certain information. This means that users can configure how to show their code by quickly changing the URL.

A sample URL would be https://dartpad.dev/embed-inline.html?id=5d70bc1889d055c7a18d35d77874af88&verticalRatio=60

It can be embedded by inserting the following code into a html document:

<iframe src="https://dartpad.dev/embed-html.html?id=72d83fe97bfc8e735607&verticalRatio=80></iframe>

Specify the width and the height as style parameters of the iframe:

<iframe style="width:400px;height:400px;" src="https://dartpad.dev/embed-html.html&id=72d83fe97bfc8e735607&verticalRatio=80></iframe>

In this URL, we have the query ending ?id=72d83fe97bfc8e735607&verticalRatio=80 added path. This means that our servers will show a gist with the hashed ID 72d83fe97bfc8e735607 Found at https://gist.github.com/devoncarew/72d83fe97bfc8e735607, and vertical splitters with ratios of 80%:20%.

To add multiple queries, simply separate them by the "&" (ampersand) symbol.

Experimental Embedding UI

DartPad also offers a newer, experimental UI with which we intend to replace the existing embed UI. It offers an updated look and two important capabilities:

  • Integration with Flutter for web
  • The ability to test a user's code.

Just like the original UI, the experimental one can be added to a page via an iframe. Three different layouts are available, and they can be accessed via different HTML files in the /experimental directory:

embed-new-dart.html

A simple interface for Dart code that includes an editor and console on the righthand side.

Screen Shot 2019-07-25 at 1 39 21 PM

embed-new-inline.html

Another simple interface for Dart code with a console beneath the editor.

Screen Shot 2019-07-25 at 9 41 17 PM

embed-new-flutter.html

A layout for editing and running Flutter code. When this layout is used, code is compiled with DDC rather than dart2js, and the Flutter for web packages are available for import.

Screen Shot 2019-07-25 at 1 39 36 PM

embed-new-html.html

A layout for editing dart:html projects. Editors for HTML, CSS, and Dart are included, and HTML output is displayed to the right.

Screen Shot 2019-07-25 at 1 41 10 PM

See the experimental embeddings demo page for live examples of each format.

List of query elements

The experimental embed UI looks for these parameters in its query string:

  • id: ID of a GitHub gist to load into the editor
  • split: Percentage of the iframe width to use for the editor (the rest may be used by the console or Flutter/HTML output).
  • theme: Set this to 'dark' to use the dark theme (seen in the first screenshot above).

Styling the editor

Right now, the embedded editor will style its own contents according to the desired theme (either light or dark). No border is added to the iframe contents by DartPad, nor does it attempt to size itself. Developers adding DartPad iframes to their pages should use CSS within their own pages to style these properties.

Testing the user's code

In addition to running code and displaying the output, the new embed UI can present exercises to be completed by the user and then test their responses. It does this by combining the user's code with additional "test" code provided by the exercise author and executing the result as if it were a single file.

An example exercise might look like this:

User's code

String stringify(int x, int y) {
  return '$x $y';
}

Test code

void main() {
  try {
    final str = stringify(2, 3); 

    if (str == '2 3') {
      _result(true);
    } else if (str == '23') {
      _result(false, ['Test failed. It looks like you forgot the space!']);
    } else if (str == null) {
      _result(false, ['Test failed. Did you forget to return a value?']);
    } else {
      _result(false, ['That\'s not quite right. Keep trying!']);
    }
  } catch (e) {
    _result(false, ['Tried calling stringify(2, 3), but received an exception: ${e.runtimeType}']);
  }
}

When combined and executed, the main method present in the test code runs, calls into the user's code, and validates the result. The _result function is provided by DartPad in the scope in which the test code executes and can be used to report the result of a test. It takes a single boolean indicating success or failure, and a list of strings to be displayed to the user with the result.

Testing the user's code

GitHub gists can be loaded into the new embed UI automatically by appending id=[Gist ID] to the end of the query string. The embed will look for the following files within a gist:

  • main.dart: The starting state for the user's code (an unfinished method, for example).
  • test.dart: A main that will test the above code, along with any classes, functions, constants, etc. that will be used in the process.
  • solution.dart: The ideal solution to the exercise (i.e. what main.dart would look like after being successfully completed by the user).
  • hint.txt: A text hint that can be displayed to the user when requested, and which will help them complete the exercise ("Try X or Y," "Have you considered Z," etc.).
You can’t perform that action at this time.