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 |