Skip to content

Commit 4df4bd2

Browse files
xzripperxzripper
authored
Documentation.
Documentation.
1 parent fb9aee2 commit 4df4bd2

File tree

1 file changed

+101
-42
lines changed

1 file changed

+101
-42
lines changed

‎flet-navigator-docs.md‎

Lines changed: 101 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
<h1 align="center">FletNavigator v2.6.5 Documentation.</h1>
1+
<h1 align="center">FletNavigator v2.7.5 Documentation.</h1>
22

33
<h4 align="center">Menu:</h4>
44

@@ -10,7 +10,11 @@
1010
- [`NavigatorAnimation`](#navigatoranimation)
1111
- [`route`](#route)
1212
- [`define_page`](#define_page)
13+
- [`parameters`](#parameters)
1314
- [`template`](#template)
15+
- [`global_template`](#global_template)
16+
- [`render`](#render)
17+
- [`anon`](#anon)
1418
- [Summary.](#summary)
1519

1620
<hr>
@@ -21,7 +25,10 @@ FletNavigator - Simple and fast navigator (router) for Flet (Python) that allows
2125
Installation is quite easy: ```pip install flet_navigator```
2226

2327
> [!WARNING]
24-
> FletNavigator is in active development phase + only one developer works on this project. Please, be patient and report all bugs.
28+
> ~FletNavigator is in active development phase + only one developer works on this project. Please, be patient and report all bugs.~
29+
30+
> [!NOTE]
31+
> Starting from `v2.7.5` FletNavigator is production-stable and almost completely ready to use. Any bug reports are very appreciated.
2532
2633
**FletNavigator Features**:
2734
- **✨ Simple installation and very simple using.**
@@ -111,33 +118,25 @@ Homepage is main page, that you can set with `set_homepage`, and navigate with `
111118
- `get_route_data(route: str) -> Any` - Get route data. More <a href="https://github.com/xzripper/flet_navigator/issues/4#issuecomment-1817908000">detailed</a>.
112119
- `set_homepage(self, homepage: str) -> None` - Set homepage (main page). More <a href="https://github.com/xzripper/flet_navigator/issues/4#issuecomment-1817908000">detailed</a>.
113120

121+
- `@property virtual() -> bool[True]` - Is navigator virtual? Used in `PageData`.
122+
114123
Using example:
115124

116125
```python
117-
from flet import app, Page, Text, FilledButton
126+
from flet import app, Text
118127

119-
from flet_navigator import VirtualFletNavigator, PageData, ROUTE_404, route
128+
from flet_navigator import PageData, render, anon, route
120129

121130

122131
@route('/')
123132
def main_page(pg: PageData) -> None:
124-
pg.add(FilledButton('Navigate to second page.', on_click=lambda _: pg.navigator.navigate('second_page', pg.page)))
133+
pg.add(Text('Main Page!')) # or `pg.page.add`.
125134

126135
@route('second_page')
127136
def second_page(pg: PageData) -> None:
128-
... # Second page content.
129-
130-
# Specify 404 page (since v2.6.5 it's optional).
131-
# @route(ROUTE_404)
132-
# def route_404(pg: PageData) -> None:
133-
# ... # 404 Page Content.
137+
... # Second page content.
134138

135-
# Main function.
136-
def main(page: Page) -> None:
137-
# Initialize navigator and render page.
138-
VirtualFletNavigator().render(page)
139-
140-
app(main)
139+
app(anon(render, virtual=True))
141140
```
142141

143142
<hr>
@@ -155,40 +154,32 @@ app(main)
155154
- `route_changed_handler: RouteChangedHandler = None` - Route changed handler.<br><br>
156155

157156
- `__init__(page: Page, routes: Routes={}, route_changed_handler: RouteChangedHandler=None, navigator_animation: NavigatorAnimation=NavigatorAnimation()) -> None` - Initialize Flet Navigator.
158-
- `navigate(route: str, page: Page, args: Arguments=None, parameters: dict=None) -> None` - Navigate to specific route. Specify `args` to transfer arguments to other page. Specify `parameters` to add URL parameters.
159-
- `navigate_homepage(page: Page, args: Arguments=None, parameters: dict=None) -> None` - Navigate to homepage (main page).
157+
- `navigate(route: str, page: Page, args: Arguments=None, parameters: dict[str, Any]=None) -> None` - Navigate to specific route. Specify `args` to transfer arguments to other page. Specify `parameters` to add URL parameters.
158+
- `navigate_homepage(page: Page, args: Arguments=None, parameters: dict[str, Any]=None) -> None` - Navigate to homepage (main page).
160159
- `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.
161160
- `set_route_data(route: str, data: Any) -> int` - Set route data (cookies-like mechanism). Returns success/fail. More <a href="https://github.com/xzripper/flet_navigator/issues/4#issuecomment-1817908000">detailed</a>.
162161
- `get_route_data(route: str) -> Any` - Get route data. More <a href="https://github.com/xzripper/flet_navigator/issues/4#issuecomment-1817908000">detailed</a>.
163162
- `set_homepage(homepage: str) -> None` - Set homepage (main page). More <a href="https://github.com/xzripper/flet_navigator/issues/4#issuecomment-1817908000">detailed</a>.
164163

164+
- `@property virtual() -> bool[False]` - Is navigator virtual? Used in `PageData`.
165+
165166
Using example:
166167

167168
```python
168-
from flet import app, Page, Text, FilledButton, WEB_BROWSER
169+
from flet import app, Text
169170

170-
from flet_navigator import FletNavigator, PageData, ROUTE_404, route
171+
from flet_navigator import PageData, render, anon, route
171172

172173

173174
@route('/')
174175
def main_page(pg: PageData) -> None:
175-
pg.add(FilledButton('Navigate to second page.', on_click=lambda _: pg.navigator.navigate('second_page', pg.page)))
176+
pg.add(Text('Main Page!')) # or `pg.page.add`.
176177

177178
@route('second_page')
178179
def second_page(pg: PageData) -> None:
179180
... # Second page content.
180181

181-
# Specify 404 page (since v2.6.5 it's optional).
182-
# @route(ROUTE_404)
183-
# def route_404(pg: PageData) -> None:
184-
# ... # 404 Page Content.
185-
186-
# Main function.
187-
def main(page: Page) -> None:
188-
# Initialize navigator and render page.
189-
FletNavigator(page).render(page)
190-
191-
app(main, view=WEB_BROWSER)
182+
app(anon(render))
192183
```
193184

194185
<hr>
@@ -204,7 +195,9 @@ app(main, view=WEB_BROWSER)
204195
- `page_id: int = None` - Page ID.<br><br>
205196

206197
- `set_appbar(appbar: Control) -> None` - Set appbar for current page. More <a href="https://github.com/xzripper/flet_navigator/issues/4#issuecomment-1817908000">detailed</a>.
207-
- `add(self, *controls: Control) -> None` - Append control(s) to page. Works as same as `Page.add`.
198+
- `add(*controls: Control) -> None` - Append control(s) to page. Works as same as `Page.add`.
199+
- `navigate(route: str, args: Arguments=None, parameters: dict[str, Any]=None) -> None` - Navigate to specific route. Parameters aren't used if navigator is virtual. Works as same as `PageData.navigator.navigate`.
200+
- `navigate_homepage(args: Arguments=None, parameters: dict[str, Any]=None) -> None` - Navigate to homepage. Parameters aren't used if navigator is virtual. Works as same as `PageData.navigator.navigate_homepage`.
208201

209202
<hr>
210203

@@ -315,20 +308,86 @@ define_page('second_page', 'my_second_page_name') # => my_second_page_name
315308

316309
<hr>
317310

311+
<h3 align="center"><code>parameters</code></h3>
312+
313+
```parameters(route: str, **_parameters: dict) -> str```
314+
315+
<code>parameters</code> function added in <code>v2.7.5</code> and used to append route with parameters.<br><br>
316+
317+
```python
318+
parameters('route', param=1, param2=2, param3=3) # Returns 'route?param=1&param2=2&param3=3'.
319+
```
320+
321+
<hr>
322+
318323
<h3 align="center"><code>template</code></h3>
319324

320-
```template(template_definition: TemplateDefinition, page_data: PageData, arguments: Arguments=None) -> Union[Control, None]```
325+
```template(template_definition: Union[str, TemplateDefinition], page_data: PageData, arguments: Arguments=None) -> Union[Control, None]```
326+
327+
Used to render template. More <a href="https://github.com/xzripper/flet_navigator/issues/4#issuecomment-1817908000">detailed</a>.<br>
321328

322-
Used to render template. More <a href="https://github.com/xzripper/flet_navigator/issues/4#issuecomment-1817908000">detailed</a>. Example:<br>
329+
In `v2.7.5` template features are extended: added global templates. Now you can use `@global_template` to register template and call template just by it's name.
330+
331+
Example:<br>
323332

324333
```python
325-
def go_to_button(pg: PageData, args: Arguments) -> None:
326-
pg.page.add(FilledButton(args[0], on_click=lambda _: pg.navigator.navigate(args[1], pg.page, args[2]))) # Or return FilledButton so we can do things with button later.
334+
def local_template(pd: PageData, args: Arguments) -> Union[Control, None]:
335+
... # Template content...
336+
337+
@global_template # or use @global_template(%TEMPLATE_NAME%) for custom name. So now template with name `my_global_template` is registered in global templates.
338+
def my_global_template(pd: PageData, args: Arguments) -> Union[Control, None]:
339+
... # Template content...
340+
341+
@route('/')
342+
def index(pd: PageData) -> None:
343+
template(local_template) # Local template.
327344

328-
def main(pg: PageData) -> None:
329-
pg.page.add(Text('Hello World!'))
345+
template('my_global_template') # Global template.
346+
```
330347

331-
template(go_to_button, pg, ('Go to second page.', 'second_page', None)) # Out is FilledButton with text 'Go to second page.', and on click redirect to `second_page` happens.
348+
<hr>
349+
350+
<h3 align="center">global_template.</h3>
351+
352+
```@global_template(template_name: str=None) -> Any```
353+
354+
Decorator used to register global templates.
355+
356+
```python
357+
def local_template(pd: PageData, args: Arguments) -> Union[Control, None]:
358+
... # Template content...
359+
360+
@global_template # or use @global_template(%TEMPLATE_NAME%) for custom name. So now template with name `my_global_template` is registered in global templates.
361+
def my_global_template(pd: PageData, args: Arguments) -> Union[Control, None]:
362+
... # Template content...
363+
```
364+
365+
<hr>
366+
367+
<h3 align="center">render</h3>
368+
369+
```render(page: Page=None, routes: Routes={}, args: Arguments=None, parameters: dict[str, Any]=None, route_changed_handler: RouteChangedHandler=None, navigator_animation: NavigatorAnimation=NavigatorAnimation(), virtual: bool=False) -> None```
370+
371+
Shortcut for rendering page at start (`Nav(page?).render(page)`). Better use it with `anon`.
372+
373+
```python
374+
@route('/')
375+
def index(pd: PageData) -> None:
376+
... # Index content...
377+
378+
app(lambda page: render(page))
379+
```
380+
381+
<hr>
382+
383+
<h3 align="center">anon</h3>
384+
385+
```anon(function: Callable, args: Arguments=(), **kwargs: dict) -> Callable```
386+
387+
Function used to create anonymous functions. Anonymous function has one argument required - `page`.
388+
389+
```python
390+
app(anon(render)) # instead of app(lambda page: render(page))
332391
```
333392

334393
<hr>
@@ -340,4 +399,4 @@ Summary! Now you know difference between virtual and non-virtual navigator, how
340399

341400
<hr>
342401

343-
<p align="center"><b><i>FletNavigator V2.6.5</i></b></p>
402+
<p align="center"><b><i>FletNavigator V2.7.5</i></b></p>

0 commit comments

Comments
 (0)