05. Browser History Support
Mvp4g2 instantiates a Place Service to easily manage history based on History converter.
History converters have two goals:
-
convert event parameters to a string (to add it to the token) and/or store them (in cookie for example) when an event is stored in browser history (see this section for more information).
-
convert, when history changes, a token to an event, retrieve information to build its parameters (thanks to the token, database, cookie...) and then fires the converted event to event bus. This conversion is done by convertFromToken method.
This is how Mvp4g2 stores an event to the browser history:
This is how Mvp4g retrieves an event from browser history:
The token stored in the browser history will be built the following way: event name (or history name, if one is enter inside the event bus) + "?" + value returned by the handling method of the event. This is the default implementation of mvp4g2.
Any event can be stored in history. All you have to do is to associate a history converter to an event.
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.
If you need to retrieve event information when browser history changes, you can do this in the convertFromToken method of the history converter.
To create a history converter, you have to:
- create a class that implements HistoryConverter
- have a constructor with no parameter
- annotate your class with @History
- have your history converter implement the event to token conversion method (see this section for more information).
@History
public class CompanyHistoryConverter
implements HistoryConverter<CompanyEventBus> {...}
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).
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.
@Event(..., historyConverter = CompanyHistoryConverter.class)
public void goToCompany(long id);
By defining the history converter class, Mvp4g2 will be able to find the instance of history converter class and associate it with the event.
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.
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:
- NONE: parameters won't be converted, only the event's name will be stored in browser's history.
- 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.
For example for the previous event, you need to define the following method in your history converter:
public String onGoToCompany(long id);
- 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.
For example, if you have the following event bus:
public interface OneEventBus ... {
@Event(..., historyConverter=OneHistoryConverter.class)
void event1(int i);
@Event(..., historyConverter=OneHistoryConverter.class)
void event2(int i);
@Event(..., historyConverter=OneHistoryConverter.class)
void event3(int i, String s);
}
you would need to define this history converter with 2 convertToToken methods:
public class OneHistoryConverter... {
public String convertToToken(String eventType, int i){
//called by event1 and event2
...
}
public String convertToToken(String eventType, int i, String s){
//called by event 3
...
}
}
You can define the history converter type thanks to the "type" attribute of the @History annotation:
@History(type = HistoryConverterType.SIMPLE)
public class OneHistoryConverter implements HistoryConverter { ... }
By default, the type attribute is equals to DEFAULT.
When dealing with history, two particular cases can happen:
- token stored in history is null or empty (ie equals to "").
- token is incorrect (for example, user tried to modify the url and event type stored in the token is not correct).
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:
- @InitHistory, to manage the case when the token is empty
- @NotFoundHistory, to manage the case when the token is incorrect.
@InitHistory
@Event(handlers = { RootTemplatePresenter.class, TopBarPresenter.class })
public void init();
@NotFoundHistory
@Event(handlers = RootTemplatePresenter.class)
public void notFound();
@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.
No object can be fired with event(s) annotated with @InitHistory or @NotFoundHistory.
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.
@Event(handlers = MainPresenter.class, historyConverter=ClearHistory.class)
public void clearHistory();
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.
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.
@Events(...historyOnStart = true)
public interface MainEventBus
extends IsEventBus {
...
}
When you store you event in the browser history, you may want the event url to be crawlable by search engine. To have crawlable url, you need to add a "!" before the token (https://developers.google.com/webmasters/ajax-crawling/ see Making AJAX Applications Crawlable for more information): www.mysite.com/#!displayCompany?id=1234.
You can ask the history converter to add this "!" by having the isCrawable method returns true:
public class OneCrawlableHistoryConverter
implements HistoryConverter<MainEventBus> {
public boolean isCrawlable() {
return true;
}
}
Mvp4g takes care of making the url crawlable but you will still have to configure your server to handle pages requested by the crawler (see part 2).
Mvp4g will react the same way to crawlable and not crawable urls. It means that the 2 following urls will produce the same result: www.mysite.com/#!displayCompany?id=1234. www.mysite.com/#displayCompany?id=1234.