"Create new flet app" and "Declarative vs. Imperative" docs updated - #6743
Merged
Conversation
Extract the two full example apps from declarative-vs-imperative-crud-app.md into standalone, runnable examples under sdk/python/examples/cookbook, and reference them from the doc via CodeExample, matching the pattern used by other cookbook/control docs. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…) claims Rewrite the doc to lead with the "why" up front, cut redundant AI-style repetition (the same points were made 2-3 times), and replace the verbose rewrite-recipes section with a compact cheat sheet. Also correct an inaccurate claim: page.update() is called automatically after event handlers since Flet 0.80.0, so the imperative example's explicit self.page.update() calls were redundant and are now removed. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…erative
Retitle and further edit the doc's intro, and fix the duplicate section
headings caused by remark-inject-example-headings auto-injecting a title
from each example's pyproject.toml on top of our hand-written headings
(suppressed via displayTitle={false}).
Update the sidebar entry and the blog post link (also fixing its anchor,
which pointed at a heading removed in the earlier rewrite).
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Rework the intro paragraph to state up front that the article compares imperative vs declarative using the same CRUD app, and name the specific on_click handlers and controls involved in the imperative example's visibility toggling. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Break the Edit/Save/Cancel/Delete description into a bulleted list, add the missing Add button, and replace the handler-naming intro sentence with a generic explanation of the imperative technique (direct property changes plus page control list mutation), with exact properties spelled out per bullet. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…todo declarative_vs_imperative_crud_app/imperative/main.py: - add_item cleared the name fields after page.add(item), but page.add() calls Page.update() internally, which marks the handler's update as already sent and suppresses Flet's automatic post-handler flush. The field clears were silently dropped. Fixed by mutating state before the update-triggering call. - edit_item never reset the TextFields from the row's actual values, so Cancel left whatever was typed in place; the next Edit showed the cancelled input instead of the saved name. Fixed by tracking first_name/last_name as the row's source of truth and resetting the fields from them on every Edit click. apps/todo/main.py: add_clicked is itself an on_click/on_submit handler, so the trailing self.update() was redundant now that Flet auto-updates after event handlers (same class of leftover as the CRUD example). Updated the cookbook doc's Edit/Save bullets to match the fixed behavior. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Move Observables/Components/Hooks into subsections that come before the CRUD walkthrough, so the concepts are defined before they're used. Expand each with purpose and the actual (verified) subscription mechanism: components subscribe to whole observable objects received as arguments or held via hooks, not individual fields, which is why editing one user only re-renders its UserView while adding/deleting re-renders all of AppView. Also add a per-action (Add/Edit/Save/Cancel/Delete) breakdown to the Declarative walkthrough, mirroring the Imperative section. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
- Fix an inaccuracy: components take arbitrary arguments, not "@ft.observable as an argument" — only args that are themselves Observable instances get subscribed to (delete_user, a plain callback, is the counter-example already in the same code sample). - Standardize on "change"/"changing" instead of "mutate"/"update" for property changes, consistent with earlier terminology decisions and to avoid confusion with the page.update()/control.update() methods discussed elsewhere in the doc. - Add short code snippets directly under Observables and Components so each concept is grounded in code without requiring a scroll down to the full example (Hooks already had one). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Replace the generic CounterBroken/Counter broken-vs-correct pair with the same lesson told through UserView's own is_editing hook, matching the pattern already used for Observables and Components. Also trim a verbose sentence about the shared hook/observable render mechanism. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Link "an observable field", "a hook's setter", and "components" in the intro to their respective subsections, and link the Declarative section's "this example" and its "Observables, Components, and Hooks" list to the matching anchors. Add an "### Example" subtitle marking where the concept explanations end and the concrete CRUD walkthrough begins. Rephrase "a Flet app is imperative" to "follows an imperative approach" for parallelism with the declarative paragraph. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
The "mutate: delete" arrow in crud-declarative.drawio was a floating, unconnected edge positioned to visually suggest AppView triggers deletion. In the actual example, delete is invoked from UserView (via the delete_user callback passed down as a prop), not AppView. Reconnect the edge from UserView to App and regenerate the PNG export to match. Also: state lives in *instances* of the observable classes, not the classes themselves (consistent with the earlier Observables fix), and align the Save bullet's em-dash structure with the other four bullets. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Replace the "Imperative -> declarative cheat sheet" table (largely redundant with material covered earlier in the doc) with a Conclusion section: the imperative-vs-declarative mental-model shift, additional scenarios where declarative helps (debugging, testing, multiple views of the same data, complex multi-step UIs), and links to more declarative example apps. Also fix 5 stale links in the "Introducing Declarative UI in Flet" blog post pointing at flat counter.py/todo.py/tic-tac-toe.py/minesweeper.py files and a hyphenated solitaire-final path that no longer exist — these examples now live in per-app subfolders (counter/main.py, etc.) with underscored names (tic_tac_toe, solitaire_final). Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Expand the thin "Creating a new Flet app" page into a tour of controls, layout, page structure, and events, built around the actual flet-create scaffold (counter + FAB) instead of a throwaway snippet, and tie it together with a worked catalog example. Move Auto-update out into its own cookbook article since it's a standalone concept, not part of project setup.
Source the counter snippet from the bundled apps/templates/basic_counter example via <CodeExample> so it gets the same "Try Online" button as every other control doc, and add a screenshot after it.
Fix inaccurate/awkward phrasing: link Container in the events list, explain the e argument and Event[Button] typing explicitly, correct the auto-update claim to match what the example actually does (calls show_dialog, not a control property), and trim a few other sentences.
Clarify the Container-for-clickability note, drop "Material" before AppBar, add a note on Cupertino controls/adaptive apps, and replace em dashes throughout with semicolons, parentheses, or colons depending on what the sentence actually needs.
Rename "Bringing it all together" to "Example: Product catalog" and add sdk/python/examples/cookbook/create_flet_app/product_catalog as a gallery-enabled example project, sourcing the doc's catalog snippet from it via <CodeExample> so it gets a "Try Online" button like the counter above it. Also fix the Stack's default hard-edge clipping, which was cutting off the negatively-offset "SALE" badge.
Add test_product_catalog.py under integration_tests/examples/cookbook, mirroring test_calculator.py, plus its generated golden macOS screenshot. Reference the screenshot in create-flet-app.md via the Image component's test-images mapping (used the same way in datatable2/index.md), and switch the counter screenshot to Image too for consistency.
Add Text/Row/Stack/Container screenshots to create-flet-app.md so readers can see what each snippet actually renders.
![sourcery-ai[bot]](https://avatars.githubusercontent.com/in/48477?s=60&v=4){kind=small}
Deploying flet-website-v2 with
|
| Latest commit: |
ec2ca56
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://1e59794c.flet-website-v2.pages.dev |
| Branch Preview URL: | https://inesa-docs.flet-website-v2.pages.dev |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Description
Test code
# Minimal test/reproduction code for reviewers, if applicable.Type of change
Checklist
website/sidebars.ymlfor breaking changes, removals, and deprecations, if applicable.Screenshots
Additional details
Summary by Sourcery
Refresh getting-started docs to better introduce Flet apps and surface new declarative vs. imperative guidance, alongside new cookbook examples and tests.
Enhancements:
Documentation:
Tests: