Blockflow

Blockflow ist ein Fork von Scratch zum Erstellen von geführten Tutorials. Hyperbook bietet zwei Direktiven zum Einbetten von Blockflow: einen Player zum Abspielen und einen Editor zum Erstellen von Tutorials.

Hyperbook enthält ein Blockflow-Browserpaket mit fester Version. Die CLI lädt es herunter, wenn ein Build Blockflow zum ersten Mal verwendet. Bücher mit einer dieser Direktiven verwenden eine gemeinsame lokale Kopie und sind für Editor und Player nicht auf blockflow.openpatch.org angewiesen. Die VS Code-Erweiterung enthält das Paket nicht. Ihre Vorschau verwendet die von der CLI heruntergeladene Kopie oder lädt Blockflow bis zum Download von blockflow.openpatch.org. Lokale Projekte und Tutorial-Medien funktionieren offline, wenn das Buch lokal bereitgestellt wird. Externe Projekte, Inhalte aus der Scratch-Bibliothek und Netzwerk-Erweiterungen benötigen weiterhin Internetzugang. Lizenz und Quellcode-Link von Blockflow werden mit den Dateien ausgeliefert.

Player

Der Blockflow Player bettet einen Player zum Abspielen von Scratch-basierten geführten Tutorials ein.

::blockflow-player{src="https://hyperbook.openpatch.org/elements/platformer.sb3"}

Player-Argumente

src: Die URL zu einer .sb3-Datei.
width: Die Breite des Players. Standard 100%.
height: Die Höhe des Players. Standard 600px.

Editor

Der Blockflow Editor bettet einen Editor zum Erstellen von Scratch-basierten geführten Tutorials ein. Die einzelnen Schritte können direkt in Markdown definiert werden und die Konfiguration wird automatisch beim Bauen generiert.

Grundlegende Verwendung

::::blockflow-editor{title="Mein Tutorial" src="./plattformer.sb3"}
 
:::step{title="Willkommen"}
Das ist der erste Schritt des Tutorials.
:::
 
:::step{title="Bewege die Katze"}
Benutze den Bewegen-Block, um die Katze 10 Schritte zu bewegen.
:::
 
::::

Schritte

Jeder Schritt wird mit einer :::step-Direktive innerhalb des Editor-Blocks definiert. Schritte unterstützen die folgenden Attribute:

title: Der Titel des Schritts.
image: Eine optionale Bild-URL für den Schritt.
video: Eine optionale Video-URL für den Schritt.

Der Textinhalt des Schritts wird als Beschreibung verwendet.

::::blockflow-editor{title="Tutorial" src="./projekt.sb3"}
 
:::step{title="Willkommen" image="./willkommen.png"}
Willkommen zu diesem Tutorial!
:::
 
:::step{title="Schau dir das an" video="./demo.mp4"}
Schau dir das Video an, um zu sehen, wie es funktioniert.
:::
 
::::

Toolbox-Konfiguration

Du kannst einschränken, welche Block-Kategorien und Blöcke im Editor verfügbar sind, indem du die Attribute categories und blocks-<kategorie> verwendest.

categories: Eine kommagetrennte Liste von Block-Kategorien, z.B. "motion,events,control,operators".
blocks-<kategorie>: Eine kommagetrennte Liste von Block-IDs für eine bestimmte Kategorie, z.B. blocks-motion="motion_movesteps,motion_turnright".

::::blockflow-editor{title="Tutorial" src="./projekt.sb3" categories="motion,events,control" blocks-motion="motion_movesteps,motion_turnright,motion_turnleft"}
 
:::step{title="Schritt 1"}
Probiere die Bewegungsblöcke aus!
:::
 
::::

UI-Konfiguration

allowExtensions: Ob Scratch-Erweiterungen erlaubt sind. Setze auf "false", um sie zu deaktivieren. Standard ist true.
showCostumesTab: Ob der Kostüme/Bühnenbilder-Tab angezeigt wird. Setze auf "false", um ihn auszublenden. Standard ist true. (Wird zu costumes.enabled in der Blockflow-Konfiguration.)
showSoundsTab: Ob der Klänge-Tab angezeigt wird. Setze auf "false", um ihn auszublenden. Standard ist true. (Wird zu sounds.enabled in der Blockflow-Konfiguration.)

::::blockflow-editor{title="Tutorial" src="./projekt.sb3" allowExtensions="false"}
 
:::step{title="Schritt 1"}
Los geht's!
:::
 
::::

Projektdatei

Anstatt den Editor inline zu konfigurieren, kannst du eine URL zu einer .json-Projektdatei über das project-Attribut angeben. Das ist nützlich, wenn du eine Konfiguration wiederverwenden oder extern verwalten möchtest. Du kannst den Blockflow Generator verwenden, um eine Projektdatei zu erstellen.

::::blockflow-editor{project="https://example.com/tutorial.json"}
::::

Wenn project gesetzt ist, werden alle anderen Konfigurationsattribute (title, src, allowExtensions, categories, blocks-*) und :::step-Kinder ignoriert.

Editor-Argumente

title: Der Titel des Tutorials.
src: Der Pfad oder die URL zur .sb3-Scratch-Projektdatei.
project: URL zu einer .json-Projektdatei. Wenn gesetzt, wird die Inline-Konfiguration ignoriert.
width: Die Breite des Editors. Standard 100%.
height: Die Höhe des Editors. Standard 700px.
allowExtensions: Scratch-Erweiterungen erlauben ("true" oder "false").
showCostumesTab: Kostüme/Bühnenbilder-Tab anzeigen oder ausblenden ("true" oder "false").
showSoundsTab: Klänge-Tab anzeigen oder ausblenden ("true" oder "false").
categories: Kommagetrennte Liste von Toolbox-Kategorien.
blocks-<kategorie>: Kommagetrennte Liste von Blöcken für eine Kategorie.