updating quick start

doc/quick-start.md

@@ -7,66 +7,81 @@ Zefyr project consists of two packages:
 
 ### Installation
 
-Add `zefyr` package as a dependency to your `pubspec.yaml`:
+> We assume that you already installed [Flutter](https://flutter.dev/docs/get-started/install) and created a [project](https://flutter.dev/docs/get-started/test-drive).
+
+Add `zefyr` package as a dependency to `pubspec.yaml` of your project:
 
 ```yaml
 dependencies:
   zefyr: [latest_version]
 ```
 
-And run `flutter packages get` to install. This installs both `zefyr`
-and `notus` packages.
+And run `flutter packages get`, this installs both `zefyr` and `notus` packages.
 
 ### Usage
 
-There are 4 main objects you would normally interact with in your code:
-
-* `NotusDocument`, represents a rich text document and provides high-level methods for manipulating the document's state, like inserting, deleting and formatting of text. Read [documentation](concepts/data-and-document.md) for more details on Notus document model and data format.
-* `ZefyrEditor`, a Flutter widget responsible for rendering of rich text on the screen and reacting to user actions.
-* `ZefyrController`, ties the above two objects together.
-* `ZefyrScaffold`, allows embedding Zefyr toolbar into any custom layout.
-
-Note that `ZefyrEditor` depends on presence of `ZefyrScaffold` somewhere up the
-widget tree.
-
-Normally you would need to place `ZefyrEditor` inside of a
-`StatefulWidget`. Shown below is a minimal setup required to use the
-editor:
+We start by creating a `StatefulWidget` that will be responsible for handling
+all the state and interactions with Zefyr. In this example we'll assume
+that there is dedicated editor page in our app:
 
 ```dart
 import 'package:flutter/material.dart';
+import 'package:quill_delta/quill_delta.dart';
 import 'package:zefyr/zefyr.dart';
 
-class MyWidget extends StatefulWidget {
+class EditorPage extends StatefulWidget {
   @override
-  MyWidgetState createState() => MyWidgetState();
+  EditorPageState createState() => EditorPageState();
 }
 
-class MyWidgetState extends State<MyWidget> {
+class EditorPageState extends State<EditorPage> {
+  /// Allows to control the editor and the document.
   ZefyrController _controller;
+
+  /// Zefyr editor like any other input field requires a focus node.
   FocusNode _focusNode;
 
   @override
   void initState() {
     super.initState();
-    // Create an empty document or load existing if you have one.
-    // Here we create an empty document:
-    final document = new NotusDocument();
+    // Here we must load the document and pass it to Zefyr controller.
+    final document = _loadDocument();
     _controller = new ZefyrController(document);
     _focusNode = new FocusNode();
   }
 
   @override
   Widget build(BuildContext context) {
-    return ZefyrScaffold(
-      child: ZefyrEditor(
-        controller: _controller,
-        focusNode: _focusNode,
+    // Note that the editor requires special `ZefyrScaffold` widget to be
+    // present somewhere up the widget tree.
+    return Scaffold(
+      appBar: AppBar(title: Text("Editor page")),
+      body: ZefyrScaffold(
+        child: ZefyrEditor(
+          padding: EdgeInsets.all(16),
+          controller: _controller,
+          focusNode: _focusNode,
+        ),
       ),
     );
   }
+
+  /// Loads the document to be edited in Zefyr.
+  NotusDocument _loadDocument() {
+    // For simplicity we hardcode a simple document with one line of text
+    // saying "Zefyr Quick Start".
+    final Delta delta = Delta()..insert("Zefyr Quick Start\n");
+    // Note that delta must always end with newline.
+    return NotusDocument.fromDelta(delta);
+  }
 }
 ```
 
-This above is required minimum to include Zefyr in your Flutter app and start
-writing some rich text.
+In the above example we created a page with an AppBar and Zefyr editor in its
+body. We also initialize editor with a simple one-line document. Here is how
+it might look when we run the app and navigate to editor page:
+
+<img src="https://github.com/memspace/zefyr/raw/gitbook/assets/quick-start-screen-01.png" width="375">
+
+At this point we can already edit the document and apply styles, however if
+we navigate back from this page our changes will be lost. Let's fix this.

packages/zefyr/example/lib/main.dart

@@ -2,8 +2,10 @@
 // for details. All rights reserved. Use of this source code is governed by a
 // BSD-style license that can be found in the LICENSE file.
 import 'package:flutter/material.dart';
+
 import 'src/form.dart';
 import 'src/full_page.dart';
+import 'src/quick_start.dart';
 import 'src/view.dart';
 
 void main() {
@@ -16,12 +18,13 @@ class ZefyrApp extends StatelessWidget {
     return MaterialApp(
       debugShowCheckedModeBanner: false,
       title: 'Zefyr Editor',
-      theme: ThemeData(primarySwatch: Colors.cyan),
+//      theme: ThemeData(primarySwatch: Colors.cyan),
       home: HomePage(),
       routes: {
         "/fullPage": buildFullPage,
         "/form": buildFormPage,
         "/view": buildViewPage,
+        "/quick-start": buildQuickStart,
       },
     );
   }
@@ -37,6 +40,10 @@ class ZefyrApp extends StatelessWidget {
   Widget buildViewPage(BuildContext context) {
     return ViewScreen();
   }
+
+  Widget buildQuickStart(BuildContext context) {
+    return EditorPage();
+  }
 }
 
 class HomePage extends StatelessWidget {
@@ -71,6 +78,12 @@ class HomePage extends StatelessWidget {
             color: Colors.lightBlue,
             textColor: Colors.white,
           ),
+          FlatButton(
+            onPressed: () => nav.pushNamed('/quick-start'),
+            child: Text('Quick Start Tutorial'),
+            color: Colors.lightBlue,
+            textColor: Colors.white,
+          ),
           Expanded(child: Container()),
         ],
       ),

packages/zefyr/example/lib/src/quick_start.dart

@@ -0,0 +1,50 @@
+import 'package:flutter/material.dart';
+import 'package:quill_delta/quill_delta.dart';
+import 'package:zefyr/zefyr.dart';
+
+class EditorPage extends StatefulWidget {
+  @override
+  EditorPageState createState() => EditorPageState();
+}
+
+class EditorPageState extends State<EditorPage> {
+  /// Allows to control the editor and the document.
+  ZefyrController _controller;
+
+  /// Zefyr editor like any other input field requires a focus node.
+  FocusNode _focusNode;
+
+  @override
+  void initState() {
+    super.initState();
+    // Here we must load the document and pass it to Zefyr controller.
+    final document = _loadDocument();
+    _controller = new ZefyrController(document);
+    _focusNode = new FocusNode();
+  }
+
+  @override
+  Widget build(BuildContext context) {
+    // Note that the editor requires special `ZefyrScaffold` widget to be
+    // present somewhere up the widget tree.
+    return Scaffold(
+      appBar: AppBar(title: Text("Editor page")),
+      body: ZefyrScaffold(
+        child: ZefyrEditor(
+          padding: EdgeInsets.all(16),
+          controller: _controller,
+          focusNode: _focusNode,
+        ),
+      ),
+    );
+  }
+
+  /// Loads the document to be edited in Zefyr.
+  NotusDocument _loadDocument() {
+    // For simplicity we hardcode a simple document with one line of text
+    // saying "Zefyr Quick Start".
+    final Delta delta = Delta()..insert("Zefyr Quick Start\n");
+    // Note that delta must always end with newline.
+    return NotusDocument.fromDelta(delta);
+  }
+}