Hands-on tutorial on making code with DartPad

DartPad is an open source online editor for experiencing and running the Dart programming language in the browser. The goal is to help developers better understand the Dart programming language and Flutter application development.

The DartPad project started in 2015 as an online compiler that compiles, analyzes and displays Dart code execution results. Several important improvements have been made in the later period:

• In December 2019, a new version of DartPad was released, which not only launched an independent access domain name (dartpad.dev), but also supported running Flutter applications (displayed through web pages)
• In April 2020, CodePen started supporting Flutter apps, which use the same backend processing as DartPad
• In October 2020, the DartPad null-safe version was launched, providing developers with the Dart SDK for a null-safe compilation environment
• In May 2021, DartPad officially supports Workshop format content
• In November 2021, DartPad supports SDK version switching (Stable / Beta / Old), and introduces some commonly used packages, such as Google fonts (google_fonts), bloc, http, intl, and plans to continuously introduce new packages in the later period. 87 packages supported

Most of DartPad users are developers who have learned the Dart programming language, and can directly test Dart programming language features without configuring a local development environment. Another scenario is for the sharing of code snippets, which can be a small function. For example, when a widget is introduced in the Flutter API documentation, a DartPad will be embedded to show the developer the actual runtime effect of the widget, and code snippets can also be used. It is a minimal reproducible bug code, which is convenient to share the code with debug developers when describing the problem.

This article will take you to understand another usage of DartPad, we call it DartPad Workshop, we call it DartPad Hands-on Tutorial, this article was written and published by Flutter GDE Alex.

What is Workshop?

When Dart 2.13 (Flutter 2.2) was released in May 2021, the Flutter team added support for the Workshop format to DartPad, with the goal of supporting and improving the practical experience of Flutter lecturers when sharing and explaining courses. Many workshops have also been officially tested on the website, and the response of the developers has been very positive.

In the past, DartPad content was shared based on GitHub Gist, only one code could be shared, and there were no guided steps and interactions. Workshop is a set of interactive, multi-step, guided and Web Server-based content architecture. The author can customize the workshop name, define the content and solution of each step, use Markdown to show the introduction of the steps, and finally use various ways to host the workshop source files for use.

Next, I'll take you through all the necessary steps from using, creating, writing, and publishing the workshop to become a teaching guru!

How to start the workshop?

If a worker wants to do a good job, he must first sharpen his tools . If you want to write a good workshop, you must first understand what the final effect of the workshop will be.

Here it is recommended to browse the official Sliver Workshop for a simple experience.

It is not difficult to see from the above picture that the entire Workshop is divided into three parts:

• The left side is the introduction content block, and the steps can be switched at the same time;
• The upper right is the code editor, you can click Run to run the code;
• The lower right is the interface output, console and document interface.

At the same time, place the mouse on Step 1 at the bottom left, and a step switching list will appear, showing all switchable steps.

When a step contains a solution (there is solution.dart and has_solution is true ), the Show Solution button will be displayed in the lower right corner of the introduction content block on the left, after clicking The code content on the right will be completely replaced with the answer code.

During the whole process, whether it is the code prepared by Workshop for you or the answer code replaced by clicking Show Solution , you can modify and run it in the code editor on the right .

How to write Workshop?

Create a new directory with any name (for example my_workshop ), when the Workshop is completed, the structure should be as follows:

 my_workshop/
|---meta.yaml          # 元数据声明文件
|---step_01/           # 步骤目录（任意名称）
   |---instructions.md    # 步骤介绍 Markdown 文档
   |---snippet.dart       # 代码文件
   |---solution.dart      # 解答文件（可选）
|---step_02/
   |---instructions.md
   |---snippet.dart

meta.yml

In the metadata declaration file, you need to declare the contents of the following structure:

 name: My workshop      # Workshop 的名称
type: dart             # Workshop 的类型，可为 "dart" 或 "flutter"
steps:                 # 声明步骤
  - name: Step 1         # 步骤的名称
    directory: step_01   # 步骤对应的目录
    has_solution: true   # 步骤是否有解答
  - name: Step 2
    directory: step_02
    has_solution: false

If one of your steps requires the developer to manually modify and provide an answer at the end, you can set has_solution to true and create a solution.dart file for interaction.

The content of each step is similar, but before we start writing a specific step, we have another operation that is beneficial to our workshop development, that is, create a new one pubspec.yaml in the same level directory of the project . pubspec.yaml Helps CLI/IDE identify and configure your Dart/Flutter project. This way you can write your Workshop like a normal Dart/Flutter project.

Write step content

instructions.md

instructions.md is the introduction document corresponding to each step, which can be written in Markdown. The actual measurement can support <iframe> tags for embedding in the DartPad environment. You can embed videos or other interactive content to assist your introduction.

snippet.dart

This file is the required Dart code snippet for each step,
When switching steps, the corresponding code will be directly replaced in the code editor.
Code files sometimes don't require developers to pay attention to everything,
In such cases, it is recommended to use TODO in the file to mark the content that needs to be modified by the developer.

solution.dart

This file is an optional step answer. Before using it, you need to set the corresponding step has_solution meta.yml true in ---862ddf410bb3969bc47113d5b4596aec--- to take effect.
It is basically the same format as snippet.dart ,
In the previous article, we introduced that, click the Show Solution button,
You can replace the existing code with the answer you wrote.
Solution files come into play when you want to teach developers a specific implementation.
But if the corresponding step is an open-ended experience attempt, there is no need to provide a specific solution.

At the end of the article, you can experience the Workshop in the screenshot and refer to its build source code (including instructions.md , snippet.dart , solution.dart and other files).

How is Workshop deployed?

Workshop supports being hosted as an HTTP server . In general there are three main types of hosting:

• Deploy using your personal server, or host it locally or on a LAN to share with colleagues or students. The access URL at this time should be: https://dartpad.cn/workshops.html?webserver=https://www.example.com/my_workshop
• Use services provided by web application service providers, similar to PaaS services such as Firebase, web.app, Web+, Webify, etc. The access URL at this time should be: https://dartpad.cn/workshops.html?webserver=https://your_app.web.app/path/to/my_workshop
• Upload code directly to GitHub and access it via the GitHub API or the original repository. The access URL at this time can be: https://dartpad.cn/workshops.html?webserver=https://raw.githubusercontent.com/your_name/my_workshop or: https://dartpad.cn/workshops.html?gh_owner=your_name&gh_repo=my_workshop

It should be noted that in the actual operation process, Workshop readers will read the corresponding content from the deployment page through their own browser, and display and run it on the DartPad page, so the author needs to ensure that the deployed Workshop address can be correct. access.

Experience an existing Workshop

This year's I/O Adventure showcased the workshop made by Flutter GDE through 15 virtual booths in the Flutter product section. You can go to https://io.google/ to experience it online:

It is recommended that you experience the LazyIndexedStack Worshop made by Alex, the code warehouse address .