You are viewing a plain text version of this content. The canonical link for it is here.
Posted to issues@beam.apache.org by "ASF GitHub Bot (Jira)" <ji...@apache.org> on 2022/01/10 23:22:00 UTC
[jira] [Work logged] (BEAM-13113) [Playground] Frontend Documentation
[ https://issues.apache.org/jira/browse/BEAM-13113?focusedWorklogId=706536&page=com.atlassian.jira.plugin.system.issuetabpanels:worklog-tabpanel#worklog-706536 ]
ASF GitHub Bot logged work on BEAM-13113:
-----------------------------------------
Author: ASF GitHub Bot
Created on: 10/Jan/22 23:21
Start Date: 10/Jan/22 23:21
Worklog Time Spent: 10m
Work Description: pabloem commented on a change in pull request #16149:
URL: https://github.com/apache/beam/pull/16149#discussion_r781647003
##########
File path: playground/frontend/CONTRIBUTE.md
##########
@@ -0,0 +1,135 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Contribution Guide
+
+This guide consists of:
+
+- [Project structure](#project-structure)
+- [State Management](#state-management)
+- [Configuration](#configuration)
+- [Theming](#theming)
+- [Adding a new page](#adding-a-new-page)
+- [Accessibility](#accessibility)
+- [Unit testing](#unit-testing)
+- [Generated Files](#generated-files)
+
+## Project structure
+
+```
+frontend/
+├── web
+├── lib
+│ ├── api # generated dart client for the grpc api
+│ ├── components # general UI components used across the app
+│ ├── config # general configs e.g. theme
+│ ├── constants # different consts file like colors,sizes
+│ ├── modules # different parts of the app
+│ │ └── actions # common actions for the pages like new example, reset
+│ │ └── editor # editor text field and run code
+│ │ └── examples # everything related to loading/showing examples
+│ │ └── notifications # common notications system
+│ │ └── output # component to show log/output/graph result of running code
+│ │ └── sdk # sdk selector
+│ │ └── shortcuts # shortcuts modal and definitions
+│ ├── pages # playground pages
+│ │ └── playground # main playground editor paage
+│ │ └── embedded_playground # embedded version of the editor
+├── test # folder with unit tests
+├── pubspec.yaml # infromation about application and dependencies
+├── build.gradle # gradle tasks for playground frontends
+├── gradle.properties # default properties for project
+```
+
+## State Management
+
+Playground uses [provider](https://pub.dev/packages/provider) package for state management. We have
+top level providers like `ThemeProvider`, common page level provider `PlaygroundPageProviders` which
+contains decoupled playground page state and module providers like `OutputPlacementState`.
+
+For quick start up, please take a look
+to [this guide](https://docs.flutter.dev/development/data-and-backend/state-mgmt/simple)
+
+## Configuration
+
+The app could be configured using gradle task (e.g. api url)
+
+```
+cd beam
+./gradlew :playground:frontend:createConfig
+```
+
+The command generates [./lib/config.g.dart](./lib/config.g.dart) file with constants from
+gradle.properties which can be used in the app
+
+To add a new constant do the following steps:
+
+- Add a new line with const to the `:playground:frontend:createConfig` task
+ inside [build.gradle](./build.gradle);
+- Update [gradle.properties](./gradle.properties);
+- Run task to test it and commit [./lib/config.g.dart](./lib/config.g.dart) file.
+
+## Theming
+
+Playground app supports light and dart themes. Component themes are declared
Review comment:
```suggestion
Playground app supports light and dark themes. Component themes are declared
```
##########
File path: playground/frontend/README.md
##########
@@ -58,4 +68,25 @@ To add a new localization, follow next steps:
3. Run the following command to generate a build and localization files:
-$ flutter build web
\ No newline at end of file
+$ flutter build web
+
+### Configuration
+
+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](CONTRIBUTE.md)
+
+### Additional
+
+The full list of command can be found [here](https://flutter.dev/docs/reference/flutter-cli)
+
+## Contribution guide
+
+If you'd like to contribute to the Apache Beam Playground website, read
+our [contribution guide](CONTRIBUTE.md) where you can find detailed instructions on how to work with
+the website.
Review comment:
```suggestion
the playground.
```
##########
File path: playground/frontend/CONTRIBUTE.md
##########
@@ -0,0 +1,135 @@
+<!--
+ Licensed to the Apache Software Foundation (ASF) under one
+ or more contributor license agreements. See the NOTICE file
+ distributed with this work for additional information
+ regarding copyright ownership. The ASF licenses this file
+ to you under the Apache License, Version 2.0 (the
+ "License"); you may not use this file except in compliance
+ with the License. You may obtain a copy of the License at
+
+ http://www.apache.org/licenses/LICENSE-2.0
+
+ Unless required by applicable law or agreed to in writing,
+ software distributed under the License is distributed on an
+ "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
+ KIND, either express or implied. See the License for the
+ specific language governing permissions and limitations
+ under the License.
+-->
+
+# Contribution Guide
+
+This guide consists of:
+
+- [Project structure](#project-structure)
+- [State Management](#state-management)
+- [Configuration](#configuration)
+- [Theming](#theming)
+- [Adding a new page](#adding-a-new-page)
+- [Accessibility](#accessibility)
+- [Unit testing](#unit-testing)
+- [Generated Files](#generated-files)
+
+## Project structure
+
+```
+frontend/
+├── web
+├── lib
+│ ├── api # generated dart client for the grpc api
+│ ├── components # general UI components used across the app
+│ ├── config # general configs e.g. theme
+│ ├── constants # different consts file like colors,sizes
+│ ├── modules # different parts of the app
+│ │ └── actions # common actions for the pages like new example, reset
+│ │ └── editor # editor text field and run code
+│ │ └── examples # everything related to loading/showing examples
+│ │ └── notifications # common notications system
+│ │ └── output # component to show log/output/graph result of running code
+│ │ └── sdk # sdk selector
+│ │ └── shortcuts # shortcuts modal and definitions
+│ ├── pages # playground pages
+│ │ └── playground # main playground editor paage
+│ │ └── embedded_playground # embedded version of the editor
+├── test # folder with unit tests
+├── pubspec.yaml # infromation about application and dependencies
+├── build.gradle # gradle tasks for playground frontends
+├── gradle.properties # default properties for project
+```
+
+## State Management
+
+Playground uses [provider](https://pub.dev/packages/provider) package for state management. We have
+top level providers like `ThemeProvider`, common page level provider `PlaygroundPageProviders` which
+contains decoupled playground page state and module providers like `OutputPlacementState`.
+
+For quick start up, please take a look
+to [this guide](https://docs.flutter.dev/development/data-and-backend/state-mgmt/simple)
+
+## Configuration
+
+The app could be configured using gradle task (e.g. api url)
+
+```
+cd beam
+./gradlew :playground:frontend:createConfig
+```
+
+The command generates [./lib/config.g.dart](./lib/config.g.dart) file with constants from
+gradle.properties which can be used in the app
+
+To add a new constant do the following steps:
+
+- Add a new line with const to the `:playground:frontend:createConfig` task
+ inside [build.gradle](./build.gradle);
+- Update [gradle.properties](./gradle.properties);
+- Run task to test it and commit [./lib/config.g.dart](./lib/config.g.dart) file.
+
+## Theming
+
+Playground app supports light and dart themes. Component themes are declared
+in [theme.dart](./lib/config/theme.dart) file.
+
+To use specific color inside component you can use helper `ThemeColors` utility:
+
+`ThemeColors.of(context).greyColor`
+
+[colors.dart](./lib/constants/colors.dart) contains color declarations.
+
+## Adding a new page
+
+To add a new page do the following steps:
+
+- Add a page component to the `pages` folder
+- Add a url to the [routes.dart](./lib/pages/routes.dart) class as a static property
+- Add a case clause to the same class with your component
+
+```
+case Routes.page_url:
+ return Routes.renderRoute(const PageComponent());
+```
+
+## Accessibility
+
+Please, read the following guides about the accessibility:
+
+- [Flutter Doc](https://docs.flutter.dev/development/accessibility-and-localization/accessibility)
+- [Medium Article](https://medium.com/flutter-community/a-deep-dive-into-flutters-accessibility-widgets-eb0ef9455bc)
+
+## Unit testing
+
+Unit tests are on `tests` folder. It keeps the project structure from the `lib` folder
+with `_test.dart` file postfix.
+
+We are using standard flutter library for unit testing
+and [Mockito](https://pub.dev/packages/mockito) for generating mocks. To generate mocks for class
+you need to add `@GenerateMocks([ExampleClient])` annotation to a test file and
+run `$ flutter pub run build_runner build` command.
+
+Playground tests may be run using next commands:
+
+`$ flutter test`
+
+## Generated Files
+
+All generated files (generated api clients, mocks) should be published to the repository.
Review comment:
should we document how to generate files? Or is this documented elsewhere? Should we link to that place then?
##########
File path: playground/frontend/README.md
##########
@@ -58,4 +68,25 @@ To add a new localization, follow next steps:
3. Run the following command to generate a build and localization files:
-$ flutter build web
\ No newline at end of file
+$ flutter build web
Review comment:
```suggestion
`$ flutter build web`
```
##########
File path: playground/frontend/README.md
##########
@@ -58,4 +68,25 @@ To add a new localization, follow next steps:
3. Run the following command to generate a build and localization files:
-$ flutter build web
\ No newline at end of file
+$ flutter build web
+
+### Configuration
+
+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](CONTRIBUTE.md)
+
+### Additional
+
+The full list of command can be found [here](https://flutter.dev/docs/reference/flutter-cli)
Review comment:
```suggestion
The full list of commands can be found [here](https://flutter.dev/docs/reference/flutter-cli)
```
--
This is an automated message from the Apache Git Service.
To respond to the message, please log on to GitHub and use the
URL above to go to the specific comment.
To unsubscribe, e-mail: github-unsubscribe@beam.apache.org
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
Issue Time Tracking
-------------------
Worklog Id: (was: 706536)
Time Spent: 50m (was: 40m)
> [Playground] Frontend Documentation
> -----------------------------------
>
> Key: BEAM-13113
> URL: https://issues.apache.org/jira/browse/BEAM-13113
> Project: Beam
> Issue Type: Improvement
> Components: beam-playground
> Reporter: Artur Khanin
> Assignee: Aydar Farrakhov
> Priority: P3
> Labels: beam-playground-frontend, beam-playground-sprint-3, beam-playground-sprint-4, beam-playground-sprint-5
> Time Spent: 50m
> Remaining Estimate: 0h
>
> As a Beam Playground application developer, I want to have documentation to know how to run, debug and extend the frontend.
> Acceptance criteria:
> # All frontend requirements are listed
> # Concepts that are followed in the frontend application are presented
> # Steps on how to run the frontend application are presented
> # Steps on how to debug the frontend application are presented
> # Possible extensions for the frontend application are presented
--
This message was sent by Atlassian Jira
(v8.20.1#820001)