-
Notifications
You must be signed in to change notification settings - Fork 3.3k
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Doc: "Flutter for the react.js developer" #114
Comments
I'd be happy to help out with this. It's fairly similar, but I would lean closer to the JS style in Dart (instead of Java-esque feel of the current tutorial). Use FWIW, I wrote this pen yesterday while I was going through the tutorial. It's a port of the Counter example to React. Notice how simple the |
There are two reasons we don't use
The reason we don't use
I'd be fine with this style change. If we make this change, we should update the entire codebase rather than having one piece of documentation randomly in a different style. @Hixie is in charge of Flutter style, so if you convince him to make this change, I can help you reformat the codebase.
Having an immutable object to represent stateless components enables us to do important performance optimizations. In particular, suppose you pass widget A to widget B and B incorporates it into its build. When widget B rebuilds, we can tell whether we need to rebuild widget A by comparing the object identity of the instance. There are several situations where we pass around WidgetBuilder objects instead of Widget objects. A WidgetBuilder is essentially a (possibly pure) functional representation of a Widget. However, using that pattern everywhere would harm performance. |
For the tutorial, it would be interesting to start with a more JS-esque style (to reduce the amount of differences) and then, once some of the Flutter concepts are explained, we then go into the Dart concepts. "OK, now that you've seen how Flutter works, let's show you how to scale the code up, by adding type annotations." and then explain why Flutter uses type annotations. Also, as a second step, remove the We could start with the builders, and then "upgrade" to the full classes. I think it's all about growing this doc's code over time, introducing one new concept at a time. The feedback we got was "I know JS and React.js, but when I took a look at Flutter, there were too many different things all at once." |
Tutorials should provide an accessible way for people new to the language to learn it. They should teach the minimum amount you need to understand at the beginning, and then layer on complexity: progressive disclosure. One way to think about it: would you rather climb 10 steps or a 10' wall? The tutorial right now is information overload. It's like climbing the wall. We should make it more like climbing stairs. As someone who's familiar with JavaScript, beginning every line/statement with a type annotation makes it harder for me to see the mechanics of the framework. (It feels like clutter.) That makes it harder to follow and to learn, even if Google prefers types for production code.
The target audience of the introduction should be a lot wider than "advanced users"
The value it adds is familiarity to newcomers. This is the distinction between the tutorial and the style guide. JavaScript developers understand
For me, it's a huge readability improvement. It's easier to understand what the constructor is setting if you have already seen the scope of things it could be setting. It's also easier to follow without having to understand the mechanics of hoisting.
Is this an implementation detail leaking out? It seems like the way you represent them internally doesn't necessarily need to dictate the external API. Moreover, if you had a pure function: var LabeledValue = (label, value) => new Text("$label: $value");
// or perhaps
var LabeledValue = (props) => new Text("$props.label: $props.value"); the state that gets passed around is the immutable object you could compare. Doesn't seem like the component itself needs to serve that role. |
There are often tables in such documentation that say "If you do A in system X, you do B in system Y". It might be useful in this case to have a third column: "If you do A in JavaScript, the most direct/obvious translation is B in Dart. But it's more idiomatic (shorter/more convenient/more performant) to do C instead". |
We should definitely have a "Flutter for Web engineers" tutorial. The current tutorial is really "Flutter for Dart engineers"; it doesn't make any effort to explain Dart concepts, only Flutter concepts. |
@Hixie - thoughts on moving the public var definitions above the constructor definition? |
Our style guide encourages members to be grouped together in logical groups, for example, all the layout logic, then all the painting logic, then all the hit-testing logic, etc. So members should be grouped with the rest of the stuff that deals with whatever they deal with. They should especially be grouped with their setters and getters when they have them. Having fields in one place and other code that refers to them in another leads to less maintainable and less readable code because you have to jump up and down to find what's going on (especially to find the type annotations). Constructors should come first because they run first. Our style guide encourages putting code in the order that it runs in normal operation, so constructors first, and functions like Also, putting the constructors first dramatically improves maintainability when creating new classes by copying other classes: since Dart doesn't have a |
That's often the cause for API decisions that are geared towards performance. We've made lots of decisions in the structure of the framework's API to gently guide developers towards patterns that are faster because of implementation details. For example, Container doesn't have any clipping facilities because clipping is more expensive in the implementation. Similarly, adding a borderRadius doesn't imply an RRect clip because RRect clips are more expensive that rectangular clips. The overall style of the framework is inspired by React.js, but we've done a number of things in different ways, largely for specific reasons. In particularly, we've decided to use objects rather than closures in most places in order to let us perform some performance optimizations that don't exist in react. That decision ends up propagating throughout the system, including making StatelessComponents objects rather than closures. |
By the way, you might be interested in the Builder widget: http://docs.domokit.org/flutter/material/Builder-class.html That widget let's you make a Widget out of a WidgetBuilder. |
Lovely idea, and we'd love to see this pop up, but it's not currently planned. |
* Update build action for website-private repo (#81) Co-authored-by: Khanh Nguyen <[email protected]> * Bring PR template up to date & update build for website-private (#96) * Bring PR template up to date for freeze * update build to run ci on website-private * Bump examples/codelabs from `644dc33` to `33aadee` (#95) Bumps [examples/codelabs](https://github.com/flutter/codelabs) from `644dc33` to `33aadee`. - [Release notes](https://github.com/flutter/codelabs/releases) - [Commits](flutter/codelabs@644dc33...33aadee) --- updated-dependencies: - dependency-name: examples/codelabs dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Khanh Nguyen <[email protected]> * Bump site-shared from `faddba8` to `04233ee` (#97) Bumps [site-shared](https://github.com/dart-lang/site-shared) from `faddba8` to `04233ee`. - [Release notes](https://github.com/dart-lang/site-shared/releases) - [Commits](dart-lang/site-shared@faddba8...04233ee) --- updated-dependencies: - dependency-name: site-shared dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * [Windows] Document the dark title bar migration (#98) * Document Windows dark title bar migration guide * Update example link Co-authored-by: Loic Sharma <[email protected]> * Bump examples/codelabs from `33aadee` to `48a4d2d` (#100) Bumps [examples/codelabs](https://github.com/flutter/codelabs) from `33aadee` to `48a4d2d`. - [Release notes](https://github.com/flutter/codelabs/releases) - [Commits](flutter/codelabs@33aadee...48a4d2d) --- updated-dependencies: - dependency-name: examples/codelabs dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Migrate check_link_references tool to be Dart based (#99) * Migrate check_link_references tool to be Dart based Also enable the workflow for flutter-forward-23 so broken links are found. * Add a success confirmation message * Adjust name of workflow for new behavior * Simplify workflow name * Clean up messaging and names * Update linkcheck to null-safe release (#101) * Update to Ruby 3.2 with fix to liquid (#102) * Bump examples/codelabs from `48a4d2d` to `907b2a4` (#105) * Add CupertinoList widgets to the catalog (#107) * Bump github/codeql-action from 2.1.37 to 2.1.38 (#111) * Bump examples/codelabs from `907b2a4` to `caeae28` (#112) Bumps [examples/codelabs](https://github.com/flutter/codelabs) from `907b2a4` to `caeae28`. - [Release notes](https://github.com/flutter/codelabs/releases) - [Commits](flutter/codelabs@907b2a4...caeae28) --- updated-dependencies: - dependency-name: examples/codelabs dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Fix and cleanup snippets from recent i18n changes (#110) * Remove intl_example test and analysis skip * Fixes and cleanup to snippets from recent i18n changes * Adjust text around pinning * Add linguist override to increase language accuracy (#115) * Add new commands to Flutter CLI reference (#116) * Add localization entries to Flutter pubspec reference (#114) Fixes #7456 * Update 'intl_example' to use 'intl_translation' and add basic test (#113) * Update 'intl_example' to use 'intl_translation' and add basic test * Add new line at end of file * Remove lastModified * Refresh code excerpts Co-authored-by: Anthony Sansone <[email protected]> * Update 'Obfuscating Dart code' for updated platform support (#108) * Update 'Obfuscating Dart code' for updated platform support * Add Linux to list of supported build targets as well * Switch to info for the web note * Use code font for the supported build targets * Make web note more concise Co-authored-by: Anthony Sansone <[email protected]> * Make adjustments to pre-existing writing from feedback * Switch list format * Switch app back to code Co-authored-by: Anthony Sansone <[email protected]> * Update base Docker image to bullseye from buster (#103) * Update base Docker image to bullseye from buster * Use slim version of bullseye Co-authored-by: Anthony Sansone <[email protected]> * Bump examples/codelabs from `caeae28` to `57bed10` (#117) * Bump pigeon in /examples/development/platform_integration (#118) Bumps [pigeon](https://github.com/flutter/packages/tree/main/packages) from 5.0.1 to 6.0.1. - [Release notes](https://github.com/flutter/packages/releases) - [Commits](https://github.com/flutter/packages/commits/pigeon-v6.0.1/packages) --- updated-dependencies: - dependency-name: pigeon dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Khanh Nguyen <[email protected]> * fix examples for beta (#119) * fix examples for beta * update build.yml for beta build * Adding a page on false positives from security tools (#120) * Adding a page on false positives from security tools * Incorporating feedback * Updating the security page (#124) * Adding a page on false positives from security tools * Updating the security page and adding a link to the new false security errors page. * Bump examples/codelabs from `57bed10` to `fa74033` (#121) Bumps [examples/codelabs](https://github.com/flutter/codelabs) from `57bed10` to `fa74033`. - [Release notes](https://github.com/flutter/codelabs/releases) - [Commits](flutter/codelabs@57bed10...fa74033) --- updated-dependencies: - dependency-name: examples/codelabs dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Bump googleapis from 9.2.0 to 10.0.0 in /examples/googleapis (#123) Bumps [googleapis](https://github.com/google/googleapis.dart/tree/master/generated) from 9.2.0 to 10.0.0. - [Release notes](https://github.com/google/googleapis.dart/releases) - [Commits](https://github.com/google/googleapis.dart/commits/googleapis-v10.0.0/generated) --- updated-dependencies: - dependency-name: googleapis dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Bump github/codeql-action from 2.1.38 to 2.1.39 (#127) * Update activesupport and nokogiri (#126) * Remove duplicated false positives page (#125) * Bump examples/codelabs from `fa74033` to `2adc98c` (#128) Bumps [examples/codelabs](https://github.com/flutter/codelabs) from `fa74033` to `2adc98c`. - [Release notes](https://github.com/flutter/codelabs/releases) - [Commits](flutter/codelabs@fa74033...2adc98c) --- updated-dependencies: - dependency-name: examples/codelabs dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Thoroughly update and categorize codelabs page (#129) Add new codelabs and categorize the 'Codelabs & workshops' page. Co-authored-by: Parker Lougheed <[email protected]> * Updating info about bitcode (#130) * Adding a page on false positives from security tools * Thorough update of the codelabs page. * Updating bitcode info for iOS * Incorporating feedback and fixing build * Revert "Adding a page on false positives from security tools" This reverts commit cd401f4. * Revert "Thorough update of the codelabs page." This reverts commit b79b8d0. * Removing bitcode image Co-authored-by: Parker Lougheed <[email protected]> * Bump examples/codelabs from `2adc98c` to `d48179d` (#131) Bumps [examples/codelabs](https://github.com/flutter/codelabs) from `2adc98c` to `d48179d`. - [Release notes](https://github.com/flutter/codelabs/releases) - [Commits](flutter/codelabs@2adc98c...d48179d) --- updated-dependencies: - dependency-name: examples/codelabs dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Bump pigeon in /examples/development/platform_integration (#132) Bumps [pigeon](https://github.com/flutter/packages/tree/main/packages) from 6.0.3 to 7.0.0. - [Release notes](https://github.com/flutter/packages/releases) - [Commits](https://github.com/flutter/packages/commits/pigeon-v7.0.0/packages) --- updated-dependencies: - dependency-name: pigeon dependency-type: direct:production update-type: version-update:semver-major ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Documents new web initialization config. (#133) * Document new web initialization. * Attempt to correctly render tables in github. * Fix table definition (3 cols) * Apply suggestions from code review Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]> Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]> * Bump examples/codelabs from `d48179d` to `967b87a` (#137) * Bump jekyll from 4.3.1 to 4.3.2 (#139) Bumps [jekyll](https://github.com/jekyll/jekyll) from 4.3.1 to 4.3.2. - [Release notes](https://github.com/jekyll/jekyll/releases) - [Changelog](https://github.com/jekyll/jekyll/blob/master/History.markdown) - [Commits](jekyll/jekyll@v4.3.1...v4.3.2) --- updated-dependencies: - dependency-name: jekyll dependency-type: direct:production update-type: version-update:semver-patch ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Bump jekyll-toc from 0.17.1 to 0.18.0 (#138) Bumps [jekyll-toc](https://github.com/toshimaru/jekyll-toc) from 0.17.1 to 0.18.0. - [Release notes](https://github.com/toshimaru/jekyll-toc/releases) - [Commits](toshimaru/jekyll-toc@v0.17.1...v0.18.0) --- updated-dependencies: - dependency-name: jekyll-toc dependency-type: direct:development update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * Background isolate channels (#140) * Updated the platform channels documentation to show how to use plugins and platform channels from background isolate. * Update src/development/platform-integration/platform-channels.md Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]> Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]> * Add a blockquote style for new 'Security false positives' page (#141) * Add a new check_link_references exception for release notes (#142) * Add a new check_link_references exception * Adjust code comments * Remove release notes used for testing * Use full code block for 'Testing accessibility on web' command (#143) This allows for syntax highlighting and easy copying of the command. * updating the Whats new in 3.7 page (#134) * Updating for the 3.7 release * Adding another update * Fixing a typo * Updating the what's new page for 3.7 * Fix unclosed comment * Fix Impeller GitHub Wiki link reference Co-authored-by: Parker Lougheed <[email protected]> * 3.7.0 release notes (#136) * [WIP] 3.7.0 release notes * Update medium link Update medium link to include flutter 3.7 * Fix broken medium link Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]> * News toolkit page (#135) * Stashing the in-progress news toolkit page * Stashing the news toolkit page * Tweaking, as per Zoey's instructions * Fix toolkit docs link reference Co-authored-by: Parker Lougheed <[email protected]> * Update the videos page (#144) * Adding a page on false positives from security tools * Thorough update of the codelabs page. * Stashing changes until I get more info * Update the videos page for 3.7 * Remove sidenav change * Delete security-false-positives.md * link learning to fly s2e1 Co-authored-by: Khanh Nguyen <[email protected]> * Bump examples/codelabs from `967b87a` to `a6b830b` (#145) * Updating banner to check to livestream (#147) * Removing unpublished articles (#146) * Bump flutter from `135454a` to `b06b8b2` (#148) Bumps [flutter](https://github.com/flutter/flutter) from `135454a` to `b06b8b2`. - [Release notes](https://github.com/flutter/flutter/releases) - [Commits](flutter/flutter@135454a...b06b8b2) --- updated-dependencies: - dependency-name: flutter dependency-type: direct:production ... Signed-off-by: dependabot[bot] <[email protected]> Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> * fix build.yml * Remove Python from CodeQL analysis * Remove extra branch specifiers from link check workflow Signed-off-by: dependabot[bot] <[email protected]> Co-authored-by: John Ryan <[email protected]> Co-authored-by: Khanh Nguyen <[email protected]> Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> Co-authored-by: Loïc Sharma <[email protected]> Co-authored-by: Loic Sharma <[email protected]> Co-authored-by: Mitchell Goodwin <[email protected]> Co-authored-by: Anthony Sansone <[email protected]> Co-authored-by: Shams Zakhour (ignore Sfshaza) <[email protected]> Co-authored-by: David Iglesias <[email protected]> Co-authored-by: gaaclarke <[email protected]> Co-authored-by: Kevin Chisholm <[email protected]> Co-authored-by: Khanh Nguyen <[email protected]>
It would be interesting to write a document that specifically talks to JavaScript and react.js developers. There are enough similarities and differences that we could probably use a doc for this.
The text was updated successfully, but these errors were encountered: