|
| 1 | +### Place Service |
| 2 | +#### Description |
| 3 | +Mvp4g2 instantiates a Place Service to easily manage history based on History converter. |
| 4 | + |
| 5 | +History converters have two goals: |
| 6 | + |
| 7 | +* convert event parameters to a string (to add it to the token) and/or store them (in cookie for example) when an event |
| 8 | + is stored in browser history ([see this section for more information](#Associate_an_History_Converter_to_an_event)). |
| 9 | + |
| 10 | +* convert, when history changes, a token to an event, retrieve information to build its parameters (thanks to the token, |
| 11 | + database, cookie...) and then fires the converted event to event bus. This conversion is done by convertFromToken |
| 12 | + method. |
| 13 | + |
| 14 | +This is how Mvp4g2 stores an event to the browser history: |
| 15 | + |
| 16 | + |
| 17 | + |
| 18 | +This is how Mvp4g retrieves an event from browser history: |
| 19 | + |
| 20 | + |
| 21 | + |
| 22 | +The token stored in the browser history will be built the following way: event name (or history name, if one is enter |
| 23 | +inside the event bus) + "?" + value returned by the handling method of the event. This is the default implementation of |
| 24 | +mvp4g2. |
| 25 | + |
| 26 | +Any event can be stored in history. All you have to do is to associate a history converter to an event. |
| 27 | + |
| 28 | +If you need to store event information when the event is stored in the browser history, you can do this thanks to the convertToToken conversion method. |
| 29 | + |
| 30 | +If you need to retrieve event information when browser history changes, you can do this in the convertFromToken method of the history converter. |
| 31 | + |
| 32 | +#### Create a History Converter |
| 33 | +To create a history converter, you have to: |
| 34 | + |
| 35 | +* create a class that implements HistoryConverter |
| 36 | +* have a constructor with no parameter |
| 37 | +* annotate your class with @History |
| 38 | +* have your history converter implement the event to token conversion method ([see this section for more information](#Associate_an_History_Converter_to_an_event)). |
| 39 | +``` |
| 40 | +@History |
| 41 | +public class CompanyHistoryConverter |
| 42 | + implements HistoryConverter<CompanyEventBus> {...} |
| 43 | +``` |
| 44 | +The @History annotation has also an attribute type. The event to token method that you will have to define for the event will depend on the type ([see this section for more information](#Associate_an_History_Converter_to_an_event)). |
| 45 | + |
| 46 | +#### <a name="Associate_an_History_Converter_to_an_event">Associate a History Converter to an event</a> |
| 47 | +To add a history converter to an event, you need to specify the history converter attribute of the @Event annotation that annotates the method of your event. |
| 48 | +``` |
| 49 | +@Event(..., historyConverter = CompanyHistoryConverter.class) |
| 50 | +public void goToCompany(long id); |
| 51 | +``` |
| 52 | +By defining the history converter class, Mvp4g2 will be able to find the instance of history converter class and |
| 53 | +associate it with the event. |
| 54 | + |
| 55 | +Mvp4g2 generates instances of history converter as singleton so for one class, it generates only one instance, which means that if for several events, the same history converter class is associated, then the events will share the same instance of the converter. |
| 56 | + |
| 57 | +When a history converter is associated to an event, it needs to implement the conversion method of this event. The method to define will depend on the history converter type: |
| 58 | + |
| 59 | +* NONE: parameters won't be converted, only the event's name will be stored in browser's history. |
| 60 | +* DEFAULT: the history converter needs to define the handling method of the event but this method must return a String. The returned String will be added to the token and stored in browser's history. |
| 61 | + |
| 62 | +For example for the previous event, you need to define the following method in your history converter: |
| 63 | +``` |
| 64 | +public String onGoToCompany(long id); |
| 65 | +``` |
| 66 | +* SIMPLE: the history converter needs to define one convertToToken method for each event that has a different parameters signature. This convertToToken method must return String and must have the same parameters as the event to convert plus a first String parameter. Mvp4g will use this first String parameter to pass the event's name. The returned String will added to the token and stored in browser's history. |
| 67 | + |
| 68 | +For example, if you have the following event bus: |
| 69 | +``` |
| 70 | +public interface OneEventBus ... { |
| 71 | + |
| 72 | + @Event(..., historyConverter=OneHistoryConverter.class) |
| 73 | + void event1(int i); |
| 74 | +
|
| 75 | + @Event(..., historyConverter=OneHistoryConverter.class) |
| 76 | + void event2(int i); |
| 77 | +
|
| 78 | + @Event(..., historyConverter=OneHistoryConverter.class) |
| 79 | + void event3(int i, String s); |
| 80 | +
|
| 81 | +} |
| 82 | +``` |
| 83 | +you would need to define this history converter with 2 convertToToken methods: |
| 84 | +``` |
| 85 | +public class OneHistoryConverter... { |
| 86 | +
|
| 87 | + public String convertToToken(String eventType, int i){ |
| 88 | + //called by event1 and event2 |
| 89 | + ... |
| 90 | + } |
| 91 | + |
| 92 | + public String convertToToken(String eventType, int i, String s){ |
| 93 | + //called by event 3 |
| 94 | + ... |
| 95 | + } |
| 96 | +
|
| 97 | +} |
| 98 | +``` |
| 99 | +You can define the history converter type thanks to the "type" attribute of the @History annotation: |
| 100 | +``` |
| 101 | +@History(type = HistoryConverterType.SIMPLE) |
| 102 | +public class OneHistoryConverter implements HistoryConverter { ... } |
| 103 | +``` |
| 104 | +By default, the type attribute is equals to **DEFAULT**. |
| 105 | + |
| 106 | +#### Init and NotFound events |
| 107 | +When dealing with history, two particular cases can happen: |
| 108 | + |
| 109 | +* token stored in history is null or empty (ie equals to ""). |
| 110 | +* token is incorrect (for example, user tried to modify the url and event type stored in the token is not correct). |
| 111 | + |
| 112 | +For both of these cases, Mvp4g lets you define events that can be fired if they happen. You can annotate the method defining an event in your event bus with: |
| 113 | + |
| 114 | +* @InitHistory, to manage the case when the token is empty |
| 115 | +* @NotFoundHistory, to manage the case when the token is incorrect. |
| 116 | +``` |
| 117 | +@InitHistory |
| 118 | +@Event(handlers = { RootTemplatePresenter.class, TopBarPresenter.class }) |
| 119 | +public void init(); |
| 120 | + |
| 121 | +@NotFoundHistory |
| 122 | +@Event(handlers = RootTemplatePresenter.class) |
| 123 | +public void notFound(); |
| 124 | +``` |
| 125 | +@InitHistory must be set if you have events with history converters. @NotFoundHistory is always optional. If you have events with history converters and you haven't set the @NotFoundHistory, then the event annotated with @InitHistory will be fired in case the token is incorrect. |
| 126 | + |
| 127 | +**No object can be fired with event(s) annotated with @InitHistory or @NotFoundHistory.** |
| 128 | + |
| 129 | +#### Clear History Token |
| 130 | +For some event, you may want to delete history token stored in the URL. In order to do so, you just have to associate your event to a particular HistoryConverter provided by the framework, ClearHistory. |
| 131 | +``` |
| 132 | +@Event(handlers = MainPresenter.class, historyConverter=ClearHistory.class) |
| 133 | +public void clearHistory(); |
| 134 | +``` |
| 135 | +#### History on start |
| 136 | +When you start your application, you may want to fire the current history state in order to convert any token that could be stored in the URL. |
| 137 | + |
| 138 | +In order to do so, you have to set the attribute historyOnStart of the @EventBus annotation of your event bus to true. By default this parameter is false. |
| 139 | +``` |
| 140 | +@Events(...historyOnStart = true) |
| 141 | +public interface MainEventBus extends EventBusWithLookup {...} |
| 142 | +``` |
0 commit comments