site-www
site-www copied to clipboard
Auto-include codelab exercise code
The async-await codelab has 3 exercises (embedded DartPads with not only the main code, but also solutions, tests, and hints). Unlike the page's 5 examples (embedded DartPads with only main code), the exercises can't have auto-included code. Auto-including the exercise code would enable analysis at the least; testing should be possible too.
Enabling auto-inclusion of exercise code will require some infrastructure work. (For the record, PR #2454 was when we switched all examples and exercises to use in-page code, with the example code being auto-included via code-excerpt.)
/cc @RedBrogdon @johnpryan
Not sure what the code excerpter supports, but we need it to support code like this:
```dart:run-dartpad:height-380px:ga_id-incorrect_usage
{$ begin main.dart $}
String message = 'Hello, World!';
{$ end main.dart $}
{$ begin solution.dart $}
String message = 'delete your code';
{$ end solution.dart $}
{$ begin test.dart $}
main() => print(message);
{$ end test.dart $}
{$ begin hint.txt $}
This is a hint.
{$ end hint.txt $}
```
We often also have a hint... which might or might not be auto-included, but which needs to be in the same code block.
We could also add a feature to the inject script that combines snippets. Then the code excerpter could be used without any modifications.
For example:
```dart:run-dartpad:height-380px:ga_id-incorrect_usage:file-main.dart
main() {}
```
```dart:run-dartpad:height-380px:ga_id-incorrect_usage:file-solution.dart
solution() {}
```
```dart:run-dartpad:height-380px:ga_id-incorrect_usage:file-test.dart
test() {}
```
```dart:run-dartpad:height-380px:ga_id-incorrect_usage:file-hint.txt
This is a hint.
```
The script could combine these into a single DartPad based on the ga_id or maybe that they're right after each other. I don't think this would be a breaking change if we make sure they've specified a file value.
It'd be nice if we didn't have to specify all the same info for all of them if they're adjacent; less prone to error. Something closer to this (although adding run-dartpad: wouldn't be so bad):
```dart:run-dartpad:height-380px:ga_id-incorrect_usage:file-main.dart
main() {}
```
```dart:file-solution.dart
solution() {}
```
```dart:file-test.dart
test() {}
```
```dart:file-hint.txt
This is a hint.
```
The dart-cheatsheet codelab is a heavy user of exercises. (See #2491)
This is also relevant for examples including Dart/HTML/CSS. As more examples are migrated to use embedded DartPads it would be nice to have this functionality so snippets don't get out of date.
I think @kwalrath's previous example seems like the most appropriate and flexible.
This is now possible and has been implemented as an example in the async-await codelab with: https://github.com/dart-lang/site-www/commit/8a49647b3301e62b310359201148a95fb4336b2b