| OLD | NEW |
| 1 Initialize | 1 Initialize |
| 2 ========== | 2 ========== |
| 3 | 3 |
| 4 This package provides a common interface for initialization annotations on top | 4 This package provides a common interface for initialization annotations on top |
| 5 level methods, classes, and libraries. The interface looks like this: | 5 level methods, classes, and libraries. The interface looks like this: |
| 6 | 6 |
| 7 abstract class Initializer<T> { | 7 abstract class Initializer<T> { |
| 8 dynamic initialize(T target); | 8 dynamic initialize(T target); |
| 9 } | 9 } |
| 10 | 10 |
| 11 The `initialize` method will be called once for each annotation. The type `T` is | 11 The `initialize` method will be called once for each annotation. The type `T` is |
| 12 determined by what was annotated. For libraries it will be the Symbol | 12 determined by what was annotated. For libraries it will be the Symbol |
| 13 representing that library, for a class it will be the Type representing that | 13 representing that library, for a class it will be the Type representing that |
| 14 class, and for a top level method it will be the Function object representing | 14 class, and for a top level method it will be the Function object representing |
| 15 that method. | 15 that method. |
| 16 | 16 |
| 17 If a future is returned from the initialize method, it will wait until the futur
e | 17 If a future is returned from the initialize method, it will wait until the futur
e |
| 18 completes before running the next initializer. | 18 completes before running the next initializer. |
| 19 | 19 |
| 20 ## Usage | 20 ## Usage |
| 21 | 21 |
| 22 ### @initMethod | 22 ### @initMethod |
| 23 | 23 |
| 24 Ther is one initializer which comes with this package, `@initMethod`. Annotate | 24 There is one initializer which comes with this package, `@initMethod`. Annotate |
| 25 any top level function with this and it will be invoked automatically. For | 25 any top level function with this and it will be invoked automatically. For |
| 26 example, the program below will print `hello`: | 26 example, the program below will print `hello`: |
| 27 | 27 |
| 28 import 'package:initialize/initialize.dart'; | 28 import 'package:initialize/initialize.dart'; |
| 29 | 29 |
| 30 @initMethod | 30 @initMethod |
| 31 printHello() => print('hello'); | 31 printHello() => print('hello'); |
| 32 | 32 |
| 33 main() => run(); | 33 main() => run(); |
| 34 | 34 |
| 35 ### Running the initializers | 35 ### Running the initializers |
| 36 | 36 |
| 37 In order to run all the initializers, you need to import | 37 In order to run all the initializers, you need to import |
| 38 `package:initialize/initialize.dart` and invoke the `run` method. This should | 38 `package:initialize/initialize.dart` and invoke the `run` method. This should |
| 39 typically be the first thing to happen in your main. That method returns a Futur
e, | 39 typically be the first thing to happen in your main. That method returns a Futur
e, |
| 40 so you should put the remainder of your program inside the chained then call. | 40 so you should put the remainder of your program inside the chained then call. |
| 41 | 41 |
| 42 import 'package:initialize/initialize.dart'; | 42 import 'package:initialize/initialize.dart'; |
| 43 | 43 |
| 44 main() { | 44 main() { |
| 45 run().then((_) { | 45 run().then((_) { |
| 46 print('hello world!'); | 46 print('hello world!'); |
| 47 }); | 47 }); |
| 48 } | 48 } |
| 49 | 49 |
| 50 ## Transformer | 50 ## Transformer |
| 51 | 51 |
| 52 During development a mirror based system is used to find and run the initializer
s, | 52 During development a mirror based system is used to find and run the initializer
s, |
| 53 but for deployment there is a transformer which can replace that with a static l
ist | 53 but for deployment there is a transformer which can replace that with a static l
ist |
| 54 of initializers to be ran. | 54 of initializers to be ran. |
| 55 | 55 |
| 56 This will create a new entry point which bootstraps your existing app. If you | 56 This will create a new entry point which bootstraps your existing app, this will |
| 57 supply an `html_entry_point` then any script tags whose src is the same as | 57 have the same file name except `.dart` with be replaced with `.initialize.dart`. |
| 58 `entry_point` will be rewritten to the bootstrapped file `new_entry_point`. | 58 If you supply an html file to `entry_points` then it will bootstrap the dart |
| 59 script tag on that page and replace the `src` attribute to with the new |
| 60 bootstrap file. |
| 59 | 61 |
| 60 Below is an example pubspec with the transformer: | 62 Below is an example pubspec with the transformer: |
| 61 | 63 |
| 62 name: my_app | 64 name: my_app |
| 63 dependencies: | 65 dependencies: |
| 64 initialize: any | 66 initialize: any |
| 65 transformers: | 67 transformers: |
| 66 - initialize: | 68 - initialize: |
| 67 entry_point: web/index.dart | 69 entry_points: web/index.html |
| 68 new_entry_point: web/index.bootstrap.dart | |
| 69 html_entry_point: web/index.html | |
| 70 | 70 |
| 71 ## Creating your own initializer | 71 ## Creating your own initializer |
| 72 | 72 |
| 73 Lets look at a slightly simplified version of the `@initMethod` class: | 73 Lets look at a slightly simplified version of the `@initMethod` class: |
| 74 | 74 |
| 75 class InitMethod implements Initializer<Function> { | 75 class InitMethod implements Initializer<Function> { |
| 76 const InitMethod(); | 76 const InitMethod(); |
| 77 | 77 |
| 78 @override | 78 @override |
| 79 initialize(Function method) => method(); | 79 initialize(Function method) => method(); |
| 80 } | 80 } |
| 81 | 81 |
| 82 You would now be able to add `@InitMethod()` in front of any function and it | 82 You would now be able to add `@InitMethod()` in front of any function and it |
| 83 will be automatically invoked when the user calls `run()`. | 83 will be automatically invoked when the user calls `run()`. |
| 84 | 84 |
| 85 For classes which are stateless, you can usually just have a single const | 85 For classes which are stateless, you can usually just have a single const |
| 86 instance, and that is how the actual InitMethod implementation works. Simply add | 86 instance, and that is how the actual InitMethod implementation works. Simply add |
| 87 something like the following: | 87 something like the following: |
| 88 | 88 |
| 89 const initMethod = const InitMethod(); | 89 const initMethod = const InitMethod(); |
| 90 | 90 |
| 91 Now when people use the annotation, it just looks like `@initMethod` without any | 91 Now when people use the annotation, it just looks like `@initMethod` without any |
| 92 parenthesis, and its a bit more efficient since there is a single instance. You | 92 parenthesis, and its a bit more efficient since there is a single instance. You |
| 93 can also make your class private to force users into using the static instance. | 93 can also make your class private to force users into using the static instance. |
| OLD | NEW |