Skip to content

Update README.md #12

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

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

Update README.md #12

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
74 changes: 36 additions & 38 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,5 +1,5 @@
<p align="center">
<img height="120px" src="https://github.com/jamesblasco/flutter_preview/blob/master/screenshots/flutter_preview.jpg?raw=true" />
<img height="120px" src="https://github.com/jamesblasco/Flutter_preview/blob/master/screenshots/Flutter_preview.jpg?raw=true" />
</p>


Expand All @@ -8,45 +8,45 @@
Create samples of your widgets and preview them in real time
<br/>
<br/>
<img width="640px" src="https://github.com/jamesblasco/flutter_preview/blob/master/screenshots/flutter_preview_header.png?raw=true" />
<img width="640px" src="https://github.com/jamesblasco/Flutter_preview/blob/master/screenshots/Flutter_preview_header.png?raw=true" />

</p>

This project is experimental but safe to use as not code is added during compilation.
This project is experimental but safe to use as no code is added during compilation.
It won't be stable until Flutter web or desktop reaches a stable version too.


## Getting Started

### Install
### Installation

- Install the vscode Flutter Preview extension. [Instructions here](https://marketplace.visualstudio.com/items?itemName=jamesblasco.flutter-preview)
- Add the `preview package` to your flutter project. [Instructions here](https://pub.dev/packages/preview#-installing-tab-)
- Install the VS Code Flutter Preview extension. [Instructions here](https://marketplace.visualstudio.com/items?itemName=jamesblasco.Flutter-preview)
- Add the `preview` package to your Flutter project. [Instructions here](https://pub.dev/packages/preview#-installing-tab-)

### Run the preview
### Run the Preview

<img align="right" height="200px" src="https://github.com/jamesblasco/flutter_preview/blob/master/screenshots/preview_button.jpg?raw=true" />
<img align="right" height="200px" src="https://github.com/jamesblasco/Flutter_preview/blob/master/screenshots/preview_button.jpg?raw=true" />

- Open a dart file in vscode and the preview button will appear
- Open a dart file in VS Code and the preview button will appear

- Click the button to launch Flutter Preview

- If a devices is not active yet, it will ask you to select the device where you want to run Flutter Preview.
Read more about [how to choose a device](https://github.com/jamesblasco/flutter_preview/issues/7) to run Flutter Preview.
- If a device is not active yet, it will ask you to select the device where you want to run Flutter Preview.
Read more about [how to choose a device](https://github.com/jamesblasco/Flutter_preview/issues/7) to run Flutter Preview.


<img align="right" height="100px" src="https://github.com/jamesblasco/flutter_preview/blob/master/screenshots/macos_helper.png?raw=true" />
<img align="right" height="100px" src="https://github.com/jamesblasco/Flutter_preview/blob/master/screenshots/macOS_helper.png?raw=true" />

> **Using macos?**
> We use the local network layer to communicate between the preview and the damenon service. Macos limits all network requets by default and so you will need to allow it during debug by adding:
> **Using macOS?**
> We use the local network layer to communicate between the preview and the daemon service. macOS limits all network requests by default and so you will need to allow it during debug by adding:
> <key>com.apple.security.network.client</key> <true/>
> to macos/Runner/DebugProfile.entitlements
> to macOS/Runner/DebugProfile.entitlements



### Adding a preview

A vscode snippet is availabe for creating a preview, just type `preview` and it will appear.
A VS Code snippet is available for creating a preview, just type `preview` and it will appear.

- Create a new class that extends PreviewProvider

Expand All @@ -62,7 +62,7 @@ It won't be stable until Flutter web or desktop reaches a stable version too.
}
```

- Add as many Preview widgets as samples you want to display
- Add as many Preview widgets as samples that you want to display
```dart
List<Preview> get previews {
return [
Expand All @@ -79,34 +79,34 @@ It won't be stable until Flutter web or desktop reaches a stable version too.

```

And and the examples will appear in the preview window as soon as you save your file.
The examples will appear in the preview window as soon as you save your file.

They will appear there every time you come back to that file.

## Taking the most of Flutter Preview

### Preview Widget

The `Preview` widget allows you to give default values that will impact your widget inside. The current availabe values are:
The `Preview` widget allows you to give default values that will impact your widget inside. The currently available values are:
- theme: Add your app theme to see your widget with your styles.
- height, width: Set the size you want to set to the widget in case the widget has not size specified.
- frame: See widget in different device scenarios: an android phone? or maybe an apple watch? More than 20 models and you can create your own
- height, width: Set the size you want to set to the widget in case the widget's size has not been specified.
- frame: See your widget in different device scenarios: Want to see it on an Android phone? How about an Apple Watch? There are more than 20 device models and you can create your own!
(This is done thanks to the amazing package [device_frame](https://pub.dev/packages/device_frame) built by Aloïs Deniel
- Need more? We are working to add more in a close future: Locale, Brightness, constraints...

Also you can set a update mode for each preview from hot-reload to hot-restart;
You can also set an update mode for each preview from hot-reload to hot-restart;

### PreviewProvider


You can use multiple classes that extend `PreviewProvider` and they will be displayed in different tabs.

By default the name of the tab will be the class name but you can override the `title` param to customize it.
By default, the name of the tab will be the class name but you can override the `title` param to customize it.

### Custom Providers

PreviewProvider allows you to group different `Previews` in a single file. While this can be enough for most, you might want to create your own previews.
For that you can extend any widget that extends `StatelessWidget` and make it implement the mixin `Previewer`;
For that you can extend any widget that extends `StatelessWidget` and make it implement the `Previewer` mixin;

```dart
class MyCustomPreview extends StatelessWidget with Previewer {
Expand All @@ -117,9 +117,9 @@ class MyCustomPreview extends StatelessWidget with Previewer {
}
```

It is important to add `with Previewer` always when extending any class, otherwise it won't be recognized by Flutter Preview.
It is important to always add `with Previewer` when extending any class, otherwise, it won't be recognized by Flutter Preview.

A already built-in custom provider is `ResizablePreviewProvider` that gives you the freedom to resize a widget to see how it could look in different scenarios.
`ResizablePreviewProvider` is an already built-in custom provider that gives you the freedom to resize a widget to see how it will look in different scenarios.

```dart
class Resizable extends ResizablePreviewProvider with Previewer {
Expand All @@ -138,9 +138,9 @@ class Resizable extends ResizablePreviewProvider with Previewer {
}
```

You can build any other previews or use any packages if you respect this two important rules
- All preview providers except the default one needs to have `with Previewer`
- They need to have an empty constructor without any params.
You can build any other previews or use any packages if you respect these two important rules
- All preview providers except the default one need to have `with Previewer`
- They need to have an empty constructor without any parameters.

Let's see a cool example using the [device_preview](https://pub.dev/packages/device_preview) package
<table>
Expand All @@ -165,27 +165,25 @@ class DevicePreviewProvider extends StatelessWidget with Previewer {

</td>

<td> <img align="right" height="300" width="383" src="https://github.com/jamesblasco/flutter_preview/blob/master/screenshots/custom_preview.png?raw=true" /> </td>
<td> <img align="right" height="300" width="383" src="https://github.com/jamesblasco/Flutter_preview/blob/master/screenshots/custom_preview.png?raw=true" /> </td>
</tr>

</table>


### Using sample assets

Adding sample assets to your flutter can increase the app without no need.
Adding sample assets to your Flutter app can needlessly increase the app size.

For images, you can NetworkImage as before.

But if you want to use local images, don't add them to your flutter project!
For images, you can continue to use NetworkImage, but if you want to use local images, don't add them to your Flutter project!

You can use PreviewImage instead.

```dart
//DON'T
// DON'T
AssetImage('images/example.png')

//DO
// DO
PreviewImage('debug_images/example.png')
```

Expand All @@ -196,11 +194,11 @@ assets:

</code></pre>

Other assets will be supported soon
Other assets will be supported soon.

## Something is not working as expected?

Create a [new issue](https://github.com/jamesblasco/flutter_preview/issues/new) and I will take it a look
Create a [new issue](https://github.com/jamesblasco/Flutter_preview/issues/new) and I will take it a look.