Skip to content
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.

Sign up for GitHub

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

chore: reformat and fix code block in README.md #2062

Open
wants to merge 1 commit into
base: master
Choose a base branch
from
Open

chore: reformat and fix code block in README.md #2062

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
59 changes: 33 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -57,12 +57,13 @@
- [ActiveGuardObserver](#activeguardobserver)
- [Examples](#examples)


## Migration guides

- [Migrating to v9](https://github.com/Milad-Akarie/auto_route_library/blob/master/migrations/migrating_to_v9.md)
- [Migrating to v6](https://github.com/Milad-Akarie/auto_route_library/blob/master/migrations/migrating_to_v6.md)

## Old documentation

- [Pre v9 documentation](https://github.com/Milad-Akarie/auto_route_library/blob/master/old/pre_v9_README.md)
- [Pre v6 documentation](https://github.com/Milad-Akarie/auto_route_library/blob/master/old/pre_v6_README.md)

Expand All @@ -78,7 +79,7 @@ If your App requires deep-linking or guarded routes or just a clean routing setu

## Installation

```yaml
```yaml
dependencies:
auto_route: [latest-version]

Expand All @@ -92,7 +93,7 @@ dev_dependencies:
1. Create a router class and annotate it with `@AutoRouterConfig` then extend "RootStackRouter" from The auto_route package
2. Override the routes getter and start adding your routes.

```dart
```dart
@AutoRouterConfig()
class AppRouter extends RootStackRouter {

Expand Down Expand Up @@ -140,7 +141,7 @@ class AppRouter extends RootStackRouter {

@override
RouteType get defaultRouteType => RouteType.material(); //.cupertino, .adaptive ..etc

@override
List<AutoRoute> get routes => [
// HomeScreen is generated as HomeRoute because
Expand Down Expand Up @@ -298,6 +299,7 @@ then inside of your `LoginPage`, pop with results
```dart
router.maybePop(true);
```

Specifying the type of the result is optional, but it's recommended to avoid runtime errors.

```dart
Expand All @@ -311,6 +313,7 @@ router.maybePop<bool>(true);
```

#### 2. Passing a callback function as an argument.

We only have to add a callback function as a parameter to our page constructor like follows:

```dart
Expand Down Expand Up @@ -353,7 +356,7 @@ Nested navigation means building an inner router inside of a page of another rou
<img alt="nested-router-demo" src="https://raw.githubusercontent.com/Milad-Akarie/auto_route_library/master/art/nested_router_demo.png?raw=true" height="370">
</p>

Defining nested routes is as easy as populating the children field of the parent route. In the following example `UsersPage`, `PostsPage` and `SettingsPage` are nested children of `DashboardPage`.
Defining nested routes is as easy as populating the children field of the parent route. In the following example `UsersPage`, `PostsPage` and `SettingsPage` are nested children of `DashboardPage`.

```dart
@AutoRouterConfig(replaceInRouteName: 'Page,Route')
Expand Down Expand Up @@ -400,6 +403,7 @@ class DashboardPage extends StatelessWidget {
}
}
```

**Note** NavLink is just a button that calls router.push(destination). Now if we navigate to `/dashboard/users`, we will be taken to the `DashboardPage` and the `UsersPage` will be shown inside of it.

What if want to show one of the child pages at `/dashboard`? We can simply do that by giving the child routes an empty path `''` to make initial or by setting initial to true.
Expand Down Expand Up @@ -430,8 +434,10 @@ AutoRoute(
```

#### Creating Empty Shell routes

Empty shell routes build a screen that contain the `AutoRouter` widget, which is used to render nested routes.
So you can build the widget your self like follows:

```dart
@RoutePage()
class MyShellPage extends StatelessWidget {
Expand All @@ -443,23 +449,22 @@ class MyShellPage extends StatelessWidget {
}
}
```

You can shorten the code above a bit by directly extending the `AutoRouter` Widget.

```dart
@RoutePage()
class MyShellPage extends AutoRouter {
const MyShellPage({Key? key}) : super(key: key);
const MyShellPage({Key? key}) : super(key: key);
}
```

finally you can create a shell route without code generation using the `EmptyShellRoute` helper

```dart
const BooksTab = EmptyShellRoute('BooksTab');
context.push(BooksTab());
```



```dart
const BooksTab = EmptyShellRoute('BooksTab');
context.push(BooksTab());
```

### Things to keep in mind when implementing nested navigation

Expand Down Expand Up @@ -813,12 +818,13 @@ MaterialApp.router(
return SynchronousFuture(
uri.replace(path: uri.path.replaceFirst('/prefix', '')),
);
}
}
return SynchronousFuture(uri);
}
),
);
```

**Note** for prefix stripping use the shipped-in `DeepLink.prefixStripper('prefix')`

```dart
Expand All @@ -829,7 +835,6 @@ MaterialApp.router(
);
```

```dart
### Using Deep-link Builder

Deep link builder is an interceptor for deep-links where you can validate or override deep-links coming from the platform.
Expand All @@ -856,6 +861,7 @@ MaterialApp.router(
### Deep Linking to non-nested Routes

**AutoRoute** can build a stack from a linear route list as long as they're ordered properly and can be matched as prefix, e.g `/` is a prefix match of `/products`, and `/products` is prefix match of `/products/:id`. Then we have a setup that looks something like this:

- `/`
- `/products`
- `/products/:id`
Expand Down Expand Up @@ -1055,7 +1061,7 @@ class AuthGuard extends AutoRouteGuard {
}
```

**Important**: `resolver.next()` should only be called once.
**Important**: `resolver.next()` should only be called once.

The `NavigationResolver` object contains the guarded route which you can access by calling the property `resolver.route` and a list of pending routes (if there are any) accessed by calling `resolver.pendingRoutes`.

Expand Down Expand Up @@ -1163,7 +1169,7 @@ In some cases we want to wrap our screen with a parent widget, usually to provid
```dart
@RoutePage()
class ProductsScreen extends StatelessWidget implements AutoRouteWrapper {

@override
Widget wrappedRoute(BuildContext context) {
return Provider(create: (ctx) => ProductsBloc(), child: this);
Expand All @@ -1172,8 +1178,6 @@ class ProductsScreen extends StatelessWidget implements AutoRouteWrapper {
}
```



## Navigation Observers

Navigation observers are used to observe when routes are pushed ,replaced or popped ..etc.
Expand Down Expand Up @@ -1315,7 +1319,7 @@ class BooksListPage extends State<BookListPage> with AutoRouteAwareStateMixin<Bo
// only override if this is a stack page
@override
void didPopNext() {}

// only override if this is a stack page
@override
void didPushNext() {}
Expand All @@ -1327,7 +1331,7 @@ class BooksListPage extends State<BookListPage> with AutoRouteAwareStateMixin<Bo
##### MaterialAutoRouter | CupertinoAutoRouter | AdaptiveAutoRouter

| Property | Default value | Definition |
|-----------------------------|-----------------------|-----------------------------------------------------------------------------------|
| --------------------------- | --------------------- | --------------------------------------------------------------------------------- |
| replaceInRouteName [String] | Page&#124Screen,Route | Used to replace conventional words in generated route name (pattern, replacement) |

## Custom Route Transitions
Expand Down Expand Up @@ -1364,6 +1368,7 @@ CustomRoute(
You can use your own custom route by passing a `CustomRouteBuilder` function to `CustomRoute' and implement the builder function the same way we did with the TransitionsBuilder function, the most important part here is passing the page argument to our custom route.

make sure you pass the return type <T> to your custom route builder function.

```dart
CustomRoute(
page: CustomPage,
Expand Down Expand Up @@ -1408,6 +1413,7 @@ class AppRouter extends RootStackRouter {}
```

## Configuring builders

To pass builder configuration to `auto_route_generator` we need to add `build.yaml` file next to `pubspec.yaml` if not already added.

```yaml
Expand All @@ -1421,6 +1427,7 @@ targets:
```

### Passing custom ignore_for_file rules

You can pass custom ignore_for_file rules to the generated router by adding the following:

```yaml
Expand All @@ -1435,6 +1442,7 @@ targets:
```

### Optimizing generation time

The first thing you want to do to reduce generation time, is specifying the files build_runner should process and we do that by using [globs](https://pub.dev/packages/glob). Globs are kind of regex patterns with little differences that's used to match file names. **Note:** for this to work on file level you need to follow a naming convention

```
Expand All @@ -1450,7 +1458,7 @@ let's say we have the following files tree
By default, the builder will process all of these files to check for a page with `@RoutePage()`
annotation, we can help by letting it know what files we need processed, e.g only process the files
inside the ui folder:
**Note** (**) matches everything including '/';
**Note** (\*\*) matches everything including '/';

```yaml
targets:
Expand Down Expand Up @@ -1539,12 +1547,11 @@ void initState(){
}
```


## Examples

- [Declarative Navigation](https://github.com/Milad-Akarie/auto_route_library/blob/master/auto_route/example/lib/declarative/declarative.router.dart)
- [Nested Navigation](https://github.com/Milad-Akarie/auto_route_library/blob/master/auto_route/example/lib/nested-navigation/nested_navigation.router.dart)

### Support auto_route

You can support auto_route by liking it on Pub and staring it on Github, sharing ideas on how we can enhance a certain functionality or by reporting any problems you encounter and of course buying a couple coffees will help speed up the development process
You can support auto_route by liking it on Pub and staring it on Github, sharing ideas on how we can enhance a certain functionality or by reporting any problems you encounter and of course buying a couple coffees will help speed up the development process