Skip to content

Commit cc46491

Browse files
xzripperxzripper
authored
Documentation.
Documentation.
1 parent 0c4efcf commit cc46491

File tree

1 file changed

+184
-0
lines changed

1 file changed

+184
-0
lines changed

‎flet-navigator-docs.md‎

Lines changed: 184 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1 +1,185 @@
1+
<h1 align="center">FletNavigator v2.0.1 Documentation.</h1>
12

3+
<h4 align="center">Menu:</h4>
4+
5+
- [Getting Started.](#getting-started)
6+
- [General.](#general)
7+
- [`VirtualFletNavigator`](#virtualfletnavigator)
8+
- [`FletNavigator`](#fletnavigator)
9+
- [Summary.](#summary)
10+
11+
<hr>
12+
13+
<h3 align="center">Getting Started.</h3>
14+
FletNavigator - Simple and fast navigator (router) for Flet (Python) that allows you to create multi-page applications!<br>It allows you to define own routes, provides built-in URL parameters support, animations (in-future), virtual routing, and more...<br><br>
15+
16+
Installation is quite easy: ```pip install flet_navigator```
17+
18+
> [!WARNING]
19+
> FletNavigator is in active development phase + only one developers works on this project. Please, be patient and report all bugs.
20+
21+
**FletNavigator Features**:
22+
- **✨ Simple installation and very simple using.**
23+
- **✨ Fast.**
24+
- **✨ Cookies-like mechanism.**
25+
- **✨ Animations between page change. (FUTURE).**
26+
- **✨ Built-in smart URL parameters parser. (Not fully implemented).**
27+
- **✨ Multiple routing modes.**
28+
- **✨ And more! And even more coming in future!**
29+
30+
**FletNavigator TODO**:
31+
- **Animations between page change.**
32+
- **Implement URL parameters for `navigate`.**
33+
- **Fix bugs.**
34+
35+
**FletNavigator Known Bugs**:
36+
- **Double redirect when using `navigate` (class `FletNavigator`).**
37+
- **Unable to trace previous page when manually updating URL in browser (`_nav_route_change_handler`).**
38+
- **Non-tested in real projects.**
39+
40+
<hr>
41+
42+
<h3 align="center">General.</h3>
43+
44+
- **What's the difference between virtual navigator (`VirtualFletNavigator`) and non virtual navigator (`FletNavigator`)?**<br>
45+
Virtual navigator uses its own virtual route for navigating. `VirtualFletNavigator` depends on `VirtualFletNavigator.route`, while `FletNavigator` uses page route (`page.route`).<br><br>
46+
While you're using virtual navigator you can't have route in your URL, because route is virtual (created in navigator class and used in navigator class). Also you can't use URL parameters. Basically this mode is useful for desktop applications, because you don't need URL's in desktop application, URL parameters even more so. You can share your data between pages using `arguments` (keep reading for explanation).<br><br>
47+
What's about non virtual navigator? Non-virtual navigator uses actual page route, so navigator renders page depending on page route. So you can have route in your URL (<code>`http://127.0.0.1:53863/` `second_page`</code>), URL parameters (`http://127.0.0.1:53863/second_page?id=123&etc=true`), etc. This mode should be used in web applications (optional).<br><br>
48+
49+
- **"Cookies-like mechanism"?**
50+
51+
FletNavigator has its own cookies like mechanism for each route (page). The main difference from cookies that that data contained on server, in navigator class, not on user computer. Example:
52+
53+
```python
54+
navigator.set_route_data('my_page', data)
55+
56+
# Somewhere on other page....
57+
navigator.get_route_data('my_page') # => data
58+
```
59+
60+
<br>
61+
62+
- **URL Parameters.**
63+
64+
URL Parameters (`http://127.0.0.1:53863/second_page?id=123&etc=true`) will be returned as dictionary (`{'id': 123, 'etc': True}`) (parameters parser can cast types).
65+
66+
<br>
67+
68+
- **Route naming.**
69+
70+
Route should have latin alphabet (no cyrillic), route can have underscores and digits. Route can't have special characters, cyrillic alphabet & spaces. Wrong route will be removed from registered routes.
71+
72+
```flet_navigator::constructor:51: Warning: Wrong route name: "$my_route1У H". Allowed only digits and underscores.```
73+
74+
<br>
75+
76+
- **Page definition.**
77+
<img src="doc_media_1.png">
78+
79+
<hr>
80+
81+
<h3 align="center"><code>VirtualFletNavigator</code></h3>
82+
83+
- `VirtualFletNavigator` - Virtual Flet Navigator Class.
84+
- `route: str = '/'` - Current route.
85+
- `routes: dict[str, Callable[[Page, 'VirtualFletNavigator', tuple[Any], str], None]] = {}` - Registered routes.
86+
- `routes_data: dict[str, Any] = {}` - Routes data.
87+
- `route_changed_handler: Callable[[str], None] = None` - Route changed handler.<br><br>
88+
89+
- `__init__(routes: dict[str, Callable[[Page, 'VirtualFletNavigator', tuple[Any], str], None]], route_changed_handler: Callable[[str], None]=None) -> None` - Initialize Virtual Flet Navigator.
90+
- `navigate(route: str, page: Page, args: tuple[Any]=None, route_parameters: dict[str, Any]={}) -> None` - Navigate to specific route. Specify `args` to transfer arguments to other page.
91+
- `render(page: Page, args: tuple[Any]=None, route_parameters: dict[str, Any]={}) -> None` - Render current route. If there is no route like that throw ROUTE-404 (if specified). Should be called only one time.
92+
- `set_route_data(self, route: str, data: Any) -> int` - Set route data (cookies-like mechanism). Returns success/fail.
93+
- `get_route_data(self, route: str) -> Any` - Get route data.
94+
95+
Using example:
96+
97+
```python
98+
from flet import app, Page
99+
100+
from flet_navigator import VirtualFletNavigator, Any, ROUTE_404
101+
102+
def main_page(page: Page, navigator: VirtualFletNavigator, args: tuple[Any], previous: str, parameters: dict[str, Any]) -> None:
103+
... # Main page content.
104+
105+
def second_page(page: Page, navigator: VirtualFletNavigator, args: tuple[Any], previous: str, parameters: dict[str, Any]) -> None:
106+
... # Second page content.
107+
108+
def route_404(page: Page, navigator: VirtualFletNavigator, args: tuple[Any], previous: str, parameters: dict[str, Any]) -> None:
109+
... # 404 Page Content.
110+
111+
def main(page: Page) -> None:
112+
# Initialize navigator.
113+
flet_navigator = VirtualFletNavigator(
114+
{
115+
'/': main_page, # Main page route.
116+
'second_page': second_page, # Second page route.
117+
ROUTE_404: route_404 # 404 page route.
118+
}, lambda route: print(f'Route changed!: {route}') # Route change handler (optional).
119+
)
120+
121+
flet_navigator.render(page) # Render current page.
122+
123+
app(target=main)
124+
```
125+
126+
<hr>
127+
128+
<h3 align="center"><code>FletNavigator</code></h3>
129+
130+
- `FletNavigator` - Flet Navigator Class.
131+
- `page: Page = None` - Page.
132+
- `route: str = '/'` - Current route.
133+
- `routes: dict[str, Callable[[Page, 'VirtualFletNavigator', tuple[Any], str], None]] = {}` - Registered routes.
134+
- `routes_data: dict[str, Any] = {}` - Routes data.
135+
- `route_changed_handler: Callable[[str], None] = None` - Route changed handler.<br><br>
136+
137+
- `__init__(page: Page, routes: dict[str, Callable[[Page, 'VirtualFletNavigator', tuple[Any], str], None]], route_changed_handler: Callable[[str], None]=None) -> None` - Initialize Flet Navigator.
138+
- `navigate(route: str, page: Page, args: tuple[Any]=None, route_parameters: dict[str, Any]={}) -> None` - Navigate to specific route. Specify `args` to transfer arguments to other page.
139+
- `render(page: Page, args: tuple[Any]=None, route_parameters: dict[str, Any]={}) -> None` - Render current route. If there is no route like that throw ROUTE-404 (if specified). Should be called only one time.
140+
- `set_route_data(self, route: str, data: Any) -> int` - Set route data (cookies-like mechanism). Returns success/fail.
141+
- `get_route_data(self, route: str) -> Any` - Get route data.
142+
143+
Using example:
144+
145+
```python
146+
from flet import app, Page, WEB_BROWSER
147+
148+
from flet_navigator import FletNavigator, Any, ROUTE_404
149+
150+
151+
def main_page(page: Page, navigator: FletNavigator, args: tuple[Any], previous: str, parameters: dict[str, Any]) -> None:
152+
... # Main page content.
153+
154+
def second_page(page: Page, navigator: FletNavigator, args: tuple[Any], previous: str, parameters: dict[str, Any]) -> None:
155+
... # Second page content.
156+
157+
def route_404(page: Page, navigator: FletNavigator, args: tuple[Any], previous: str, parameters: dict[str, Any]) -> None:
158+
... # 404 page content.
159+
160+
def main(page: Page) -> None:
161+
# Initialize navigator.
162+
flet_navigator = FletNavigator(page, # Specify page.
163+
{
164+
'/': main_page, # Main page route,
165+
'second_page': second_page, # Second page route,
166+
ROUTE_404: route_404 # 404 page route
167+
}, lambda route: print(f'Route changed!: {route}') # Route change handler (optional).
168+
)
169+
170+
# Render current page.
171+
flet_navigator.render(page)
172+
173+
app(target=main, view=WEB_BROWSER) # Non-Virtual Navigator recommended in web.
174+
```
175+
176+
<hr>
177+
178+
<h3 align="center">Summary.</h3>
179+
Summary! Now you know difference between virtual and non-virtual navigator, how to use navigator, etc! Good luck, have fun! But remember that project isn't finished!
180+
181+
*Developer Note*: It would be great support for me if you'd added credits for FletNavigator! Optional!
182+
183+
<hr>
184+
185+
<p align="center"><b><i>FletNavigator V2.0.1</i></b></p>

0 commit comments

Comments
 (0)