Beam Playground is an interactive environment to try out Beam transforms and examples. The vision for the Playground is to be a web application where users can try out Beam without having to install/initialize a Beam environment.
After checkout, run:
cp playground/frontend/lib/config.example.dart playground/frontend/lib/config.g.dart
This is a temporarily required step. See more: https://github.com/apache/beam/issues/24200
See playground/README.md for details on requirements and setup.
The following command is used to build and serve the frontend app locally:
flutter run -d chrome
Run the following command to generate a release build:
flutter build web
This produces build/web
directory with static files. Deploy them to your web server.
The app is deployed to production as a Docker container. You can also run it in Docker locally. This is useful if:
To run the frontend app with Docker, run this in the frontend directory:
docker build -t playground-frontend . docker run -p 1234:8080 playground-frontend
The container sets up NGINX on port 8080. This example exposes it as port 1234 on the host, and the app can be accessed at http://localhost:1234
This project relies on generated code for some functionality: deserializers, test mocks, constants for asset files, extracted Beam symbols for the editor, etc.
All generated files are version-controlled, so after checkout the project is immediately runnable. However, after changes you may need to re-run code generation.
Most of the generated files are produced by running the standard Dart code generator. This only requires Flutter, but must be called on multiple locations. For convenience, run this single command:
./gradlew :playground:frontend:generateCode
Requirements:
ast
, pyyaml
.Other SDKs will add more requirements as we add extraction scripts for them.
To generate all project's generated files including symbol dictionaries, run:
./gradlew :playground:frontend:generate
For consistency, it is recommended that you delete and re-generate all files before committing if you have all required tools on your machine. To delete all generated files, run:
./gradlew :playground:frontend:cleanGenerated
To run all pre-commit checks, execute this in the beam root:
./gradlew :playground:frontend:precommit
This includes:
Code can be automatically reformatted using:
flutter format ./lib
To delete all generated files and re-generate them again and then run tests:
./gradlew :playground:frontend:playground_components_test ./gradlew :playground:frontend:test
To run tests without re-generating files:
cd playground/frontend/playground_components flutter test cd .. flutter test
Integration tests currently can be run only on a local development machine. Server testing has not been verified yet.
chromedriver --port=4444
./gradlew :playground:frontend:integrationTest
The project is in the process of migrating from the built-in Flutter localization to easy_localization. It temporarily uses both ways.
To add a new localization, follow next steps:
Create app_YOUR_LOCALE_CODE.arb file with your key-translation pairs, except description tags, in lib/l10n directory (use app_en.arb as example).
Add Locale(‘YOUR_LOCALE_CODE’) object to static const locales variable in lib/l10n/l10n.dart file.
Run the following command to generate a build and localization files:
flutter build web
To add a new localization (using fr
as an example):
Create playground_components/assets/translations/fr.yaml
. Fill it with content copied from an existing translation file in another language.
Create assets/translations/fr.yaml
. Fill it with content copied from an existing translation file in another language.
Add the locale to the list in lib/l10n/l10n.dart
.
The app could be configured using gradle task (e.g. api url)
cd beam ./gradlew :playground:frontend:createConfig
For more information see See CONTRIBUTE.md
The full list of commands can be found here
If you'd like to contribute to the Apache Beam Playground website, read our contribution guide where you can find detailed instructions on how to work with the playground.