com.gwtplatform.mvp.client.proxy

Interface PlaceManager

All Superinterfaces:

HasHandlers

All Known Implementing Classes:

DefaultPlaceManager, PlaceManagerImpl

public interface PlaceManager
extends HasHandlers

Place managers work as an intermediary between the GWT History API and ProxyPlaceAbstract. It sets up event listener relationships to synchronize them.

Author:

David Peterson, Philippe Beaudoin, Christian Goudreau

Method Summary

Methods

Modifier and Type	Method and Description
String	buildHistoryToken(PlaceRequest request) Builds a string corresponding to the history token to reveal the specified PlaceRequest.
String	buildRelativeHistoryToken(int level) Builds a string corresponding to the history token to reveal the specified place from the current place hierarchy.
String	buildRelativeHistoryToken(PlaceRequest request) Builds a string corresponding to the history token to reveal the specified PlaceRequest as a child of the current place hierarchy.
String	buildRelativeHistoryToken(PlaceRequest request, int level) Builds a string corresponding to the history token to reveal the specified PlaceRequest relative to the other places in the current place hierarchy.
List<PlaceRequest>	getCurrentPlaceHierarchy() Access the current place hierarchy, with the current PlaceRequest being the last element of this list.
PlaceRequest	getCurrentPlaceRequest() Access the current place request, that is, the tail of the place request hierarchy.
void	getCurrentTitle(SetPlaceTitleHandler handler) Retrieves the title of the currently displayed place, or null if it doesn't have a title.
EventBus	getEventBus() Makes it possible to access the EventBus object associated with that presenter.
int	getHierarchyDepth() Retrieves the number of elements in the place hierarchy.
void	getTitle(int index, SetPlaceTitleHandler handler) Retrieves the title of a specific place within the place hierarchy.
boolean	hasPendingNavigation() Checks if the PlaceManager has to perform any pending navigation that were not immediately executed because it was requested while the navigation was locked.
void	navigateBack() Calls History#back().
void	revealCurrentPlace() Reveals the place corresponding to the current value of the history token in the URL bar.
void	revealDefaultPlace() Reveals the default place.
void	revealErrorPlace(String invalidHistoryToken) Reveals the place to display when a user tries to access an invalid place.
void	revealPlace(PlaceRequest request) Programmatically reveals the specified place, updating the browser URL in the process.
void	revealPlace(PlaceRequest request, boolean updateBrowserUrl) Programmatically reveals the specified place.
void	revealPlaceHierarchy(List<PlaceRequest> placeRequestHierarchy) Programmatically reveals the specified hierarchy of places place, updating the browser URL in the process.
void	revealRelativePlace(int level) Programmatically reveals the specified place from the current place hierarchy.
void	revealRelativePlace(PlaceRequest request) Programmatically reveals the specified place as a child of the current place hierarchy.
void	revealRelativePlace(PlaceRequest request, int level) Programmatically reveals the specified place relative to the other places in the current place hierarchy.
void	revealUnauthorizedPlace(String unauthorizedHistoryToken) Reveals the place to display when a user has been refused the access to a specific place.
void	setOnLeaveConfirmation(String question) Sets the question that will be displayed whenever the user tries to navigate away from the current page.
void	unlock() Resets the navigation lock if it is currently set.
void	updateHistory(PlaceRequest request, boolean updateBrowserUrl) Updates History without firing a ValueChangeEvent.

Methods inherited from interface com.google.gwt.event.shared.HasHandlers

fireEvent

Method Detail

buildHistoryToken

String buildHistoryToken(PlaceRequest request)

Builds a string corresponding to the history token to reveal the specified PlaceRequest. This can be used with a Hyperlink.

Invoking this history token will discard all the place hierarchy, effectively revealing the request as a top-level place. To keep the place hierarchy, see buildRelativeHistoryToken(com.gwtplatform.mvp.shared.proxy.PlaceRequest), buildRelativeHistoryToken(com.gwtplatform.mvp.shared.proxy.PlaceRequest, int) or buildRelativeHistoryToken(int).

Parameters:

request - The PlaceRequest corresponding to the place for which to build a history token.

Returns:

The history token.

See Also:

revealPlace(com.gwtplatform.mvp.shared.proxy.PlaceRequest)

buildRelativeHistoryToken

String buildRelativeHistoryToken(int level)

Builds a string corresponding to the history token to reveal the specified place from the current place hierarchy.

Examples, suppose the current hierarchy is requestA > requestB > requestC

• Calling revealRelativePlace(-1) will make a link to requestA > requestB
• Calling revealRelativePlace(1) will make a link to requestA
• Calling revealRelativePlace(0) will make a link to requestA > requestB > requestC
• Calling revealRelativePlace(-3) or less will make a link to ""
• Calling revealRelativePlace(3) or more will make a link to requestA > requestB > requestC

Parameters:

level - If negative, take back that many elements from the tail of the hierarchy. If positive, keep only that many elements from the head of the hierarchy. Passing 0 makes a link to the current place.

See Also:

revealRelativePlace(int)

buildRelativeHistoryToken

String buildRelativeHistoryToken(PlaceRequest request)

Builds a string corresponding to the history token to reveal the specified PlaceRequest as a child of the current place hierarchy. Identical to calling buildRelativeHistoryToken(PlaceRequest, int) with a level of 0.

To get the history token for revealing as a top-level place, see buildHistoryToken(com.gwtplatform.mvp.shared.proxy.PlaceRequest). To navigate back to a specific place in the hierarchy, see buildRelativeHistoryToken(int).

Parameters:

request - The PlaceRequest corresponding to the place for which to build a history token.

Returns:

The history token.

See Also:

revealRelativePlace(PlaceRequest)

buildRelativeHistoryToken

String buildRelativeHistoryToken(PlaceRequest request,
                               int level)

Builds a string corresponding to the history token to reveal the specified PlaceRequest relative to the other places in the current place hierarchy.

To get the history token for revealing as a top-level place, see buildHistoryToken(com.gwtplatform.mvp.shared.proxy.PlaceRequest). To navigate back to a specific place in the hierarchy, see buildRelativeHistoryToken(int).

Examples, suppose the current hierarchy is requestA > requestB > requestC

• Calling buildRelativeHistoryToken(requestD, 0) will make a link to requestA > requestB > requestC > requestD
• Calling buildRelativeHistoryToken(requestD, -1) will make a link to requestA > requestB > requestD
• Calling buildRelativeHistoryToken(requestD, 1) will make a link to requestA > requestD
• Calling buildRelativeHistoryToken(requestD, -3) will make a link to requestD
• Calling buildRelativeHistoryToken(requestD, 3) will make a link to requestA > requestB > requestC > requestD

Parameters:

request - The PlaceRequest corresponding to the place for which to build a history token.

level - If 0, then simply appends the request to the current page hierarchy. If negative, take back that many elements from the tail of the hierarchy before appending the request. If positive, keep only that many elements from the head of the hierarchy before appending the request.

Returns:

The history token.

See Also:

revealRelativePlace(PlaceRequest, int)

getCurrentPlaceHierarchy

List<PlaceRequest> getCurrentPlaceHierarchy()

Access the current place hierarchy, with the current PlaceRequest being the last element of this list.

Returns:

The current PlaceRequest.

See Also:

getCurrentPlaceRequest()

getCurrentPlaceRequest

PlaceRequest getCurrentPlaceRequest()

Access the current place request, that is, the tail of the place request hierarchy. If the hierarchy is empty this returns an empty PlaceRequest.

Returns:

The current PlaceRequest, or an empty one if the hierarchy is empty.

See Also:

getCurrentPlaceHierarchy()

getTitle

void getTitle(int index,
            SetPlaceTitleHandler handler)
              throws IndexOutOfBoundsException

Retrieves the title of a specific place within the place hierarchy.

Instead of returning the title directly, this method accepts a callback and will call SetPlaceTitleHandler.onSetPlaceTitle(java.lang.String) as soon as the title is available. This makes it possible for the user to query the title from the server based on the PlaceRequest parameters, for example.

Parameters:

index - The index of the place for which to get a title, 0 is the top-level class, getHierarchyDepth()-1 is the current place.

handler - The SetPlaceTitleHandler to invoke when the place title is available. This will be invoked with null if the place doesn't have a title.

Throws:

IndexOutOfBoundsException - If the index is less than 0 or greater or equal to getHierarchyDepth().

See Also:

getCurrentTitle(SetPlaceTitleHandler)

getCurrentTitle

void getCurrentTitle(SetPlaceTitleHandler handler)

Retrieves the title of the currently displayed place, or null if it doesn't have a title. Same as calling getTitle(int, SetPlaceTitleHandler) with a level of getHierarchyDepth()-1.

Instead of returning the title directly, this method accepts a callback and will call SetPlaceTitleHandler.onSetPlaceTitle(java.lang.String) as soon as the title is available. This makes it possible for the user to query the title from the server based on the PlaceRequest parameters, for example.

Parameters:

handler - The SetPlaceTitleHandler to invoke when the place title is available. This will be invoked with null if the place doesn't have a title.

getEventBus

EventBus getEventBus()

Makes it possible to access the EventBus object associated with that presenter.

Returns:

The EventBus associated with that presenter.

getHierarchyDepth

int getHierarchyDepth()

Retrieves the number of elements in the place hierarchy. The title of each of these elements can be obtained through getTitle(int, SetPlaceTitleHandler).

Returns:

The depth of the place hierarchy.

navigateBack

void navigateBack()

Calls History#back(). This may cause the user's browser to leave your application, if case you call this method from the first page visited.

updateHistory

void updateHistory(PlaceRequest request,
                 boolean updateBrowserUrl)

Updates History without firing a ValueChangeEvent. Only the last PlaceRequest of the place request hierarchy is modified.

This method will only work if the passed PlaceRequest has the same name token as the current place request (see getCurrentPlaceRequest().

If true is passed as a second parameter, then this method causes a new token to be added to the browser history, affecting the behavior of the browser's back button.

Parameters:

request - The PlaceRequest to display in the updated history.

updateBrowserUrl - true If the browser URL should be updated, false otherwise.

revealCurrentPlace

void revealCurrentPlace()

Reveals the place corresponding to the current value of the history token in the URL bar. This will result in a PlaceRequestInternalEvent being fired.

revealDefaultPlace

void revealDefaultPlace()

Reveals the default place. This is invoked when the history token is empty and no places handled it. Application-specific place managers should build a PlaceRequest corresponding to their default presenter and call revealPlace(PlaceRequest, boolean) with it. Consider passing false as the second parameter of revealPlace, otherwise a new token will be inserted in the browser's history and hitting the browser's back button will not take the user out of the application.

Important! Make sure you build a valid PlaceRequest and that the user has access to it, otherwise you might create an infinite loop.

revealErrorPlace

void revealErrorPlace(String invalidHistoryToken)

Reveals the place to display when a user tries to access an invalid place. This is invoked when the history token was not handled by any place within the application. Application-specific place managers should build a PlaceRequest corresponding to the desired presenter and call revealPlace(PlaceRequest, boolean) with it. Consider passing false as the second parameter of revealPlace, otherwise a new token will be inserted in the browser's history and hitting the browser's back button will take the user back to the invalid page he initially tried to access.

The default implementation is simply to call revealDefaultPlace().

Important! Make sure you build a valid PlaceRequest and that the user has access to it, otherwise you might create an infinite loop.

Parameters:

invalidHistoryToken - The history token that was not recognised.

revealUnauthorizedPlace

void revealUnauthorizedPlace(String unauthorizedHistoryToken)

Reveals the place to display when a user has been refused the access to a specific place. This is invoked when the history token is valid but the corresponding place's Place.canReveal() returned false. Application-specific place managers should build a PlaceRequest corresponding to the desired presenter and call revealPlace(PlaceRequest, boolean) with it. Consider passing true as the second parameter of revealPlace if you navigate, say, to a login page and want the user to be able to navigate back to the unauthorized page after login. If you are displaying a page that simply mentions the error you may want to pass false, otherwise a new token will be inserted in the browser's history and hitting the browser's back button will take the user back to the unauthorized page he initially tried to access.

The default implementation is simply to call revealErrorPlace(String).

Important! Make sure you build a valid PlaceRequest and that the user has access to it, otherwise you might create an infinite loop.

Parameters:

unauthorizedHistoryToken - The history token that was not authorized.

setOnLeaveConfirmation

void setOnLeaveConfirmation(String question)

Sets the question that will be displayed whenever the user tries to navigate away from the current page. Navigating away can happen either occur by changing the program state (the history token), by entering an external URL or by closing the window. All cases will be handled.

If the user indicates that he doesn't accept the navigation, then the navigation will be cancelled, NavigationRefusedEvent will be triggered and the current page will remain.

Parameters:

question - The question to display. Pass null to accept navigation directly, without asking a question.

revealPlace

void revealPlace(PlaceRequest request)

Programmatically reveals the specified place, updating the browser URL in the process. If you don't want the browser's URL to be updated see revealPlace(PlaceRequest, boolean).

This discards the current place hierarchy, effectively revealing the request as a top-level place. To keep the current place hierarchy, see revealRelativePlace(PlaceRequest), revealRelativePlace(PlaceRequest, int) or revealRelativePlace(int). To reveal an entire place hierarchy, see revealPlaceHierarchy(java.util.List<com.gwtplatform.mvp.shared.proxy.PlaceRequest>).

Parameters:

request - The PlaceRequest corresponding to the place to reveal.

See Also:

buildHistoryToken(PlaceRequest)

revealPlace

void revealPlace(PlaceRequest request,
               boolean updateBrowserUrl)

Programmatically reveals the specified place.

This discards the current place hierarchy, effectively revealing the request as a top-level place. To keep the current place hierarchy, see revealRelativePlace(PlaceRequest), revealRelativePlace(PlaceRequest, int) or revealRelativePlace(int). To reveal an entire place hierarchy, see revealPlaceHierarchy(java.util.List<com.gwtplatform.mvp.shared.proxy.PlaceRequest>).

Parameters:

request - The PlaceRequest corresponding to the place to reveal.

updateBrowserUrl - true If the browser URL should be updated, false otherwise.

See Also:

buildHistoryToken(PlaceRequest)

revealPlaceHierarchy

void revealPlaceHierarchy(List<PlaceRequest> placeRequestHierarchy)

Programmatically reveals the specified hierarchy of places place, updating the browser URL in the process.

This discards the current place hierarchy, replacing it with the specified place hierarchy. To keep the current place hierarchy, see revealRelativePlace(PlaceRequest), revealRelativePlace(PlaceRequest, int) or revealRelativePlace(int). To reveal a single Place instead of a hierarchy, see revealPlace(com.gwtplatform.mvp.shared.proxy.PlaceRequest).

revealRelativePlace

void revealRelativePlace(int level)

Programmatically reveals the specified place from the current place hierarchy.

Examples. Suppose the current hierarchy is requestA > requestB > requestC:

• Calling revealRelativePlace(-1) makes it requestA > requestB
• Calling revealRelativePlace(1) makes it requestA
• Calling revealRelativePlace(0) makes it requestA > requestB > requestC
• Calling revealRelativePlace(-3) or less calls revealDefaultPlace()
• Calling revealRelativePlace(3) or more makes it requestA > requestB > requestC

Parameters:

level - If negative, take back that many elements from the tail of the hierarchy. If positive, keep only that many elements from the head of the hierarchy. Passing 0 reveals the current place.

See Also:

buildRelativeHistoryToken(int)

revealRelativePlace

void revealRelativePlace(PlaceRequest request)

Programmatically reveals the specified place as a child of the current place hierarchy. Identical to calling revealRelativePlace(PlaceRequest, int) with a level of 0. This will result in a PlaceRequestInternalEvent being fired.

To reveal as a top-level place, see revealPlace(com.gwtplatform.mvp.shared.proxy.PlaceRequest). To navigate back to a specific place in the hierarchy, see revealRelativePlace(int).

Parameters:

request - The PlaceRequest corresponding to the place to reveal.

See Also:

buildRelativeHistoryToken(PlaceRequest)

revealRelativePlace

void revealRelativePlace(PlaceRequest request,
                       int level)

Programmatically reveals the specified place relative to the other places in the current place hierarchy. This will result in a PlaceRequestInternalEvent being fired.

To reveal as a top-level place, see revealPlace(com.gwtplatform.mvp.shared.proxy.PlaceRequest). To navigate back to a specific place in the hierarchy, see revealRelativePlace(int).

Examples. Suppose the current hierarchy is requestA > requestB > requestC:

• Calling revealRelativePlace(requestD, 0) makes it requestA > requestB > requestC > requestD
• Calling revealRelativePlace(requestD, -1) makes it requestA > requestB > requestD
• Calling revealRelativePlace(requestD, 1) makes it requestA > requestD
• Calling revealRelativePlace(requestD, -3) or less makes it requestD
• Calling revealRelativePlace(requestD, 3) or more makes it requestA > requestB > requestC > requestD

Parameters:

request - The PlaceRequest corresponding to the place to reveal.

level - If 0, then simply appends the request to the current page hierarchy. If negative, take back that many elements from the tail of the hierarchy before appending the request. If positive, keep only that many elements from the head of the hierarchy before appending the request.

See Also:

buildRelativeHistoryToken(PlaceRequest, int)

unlock

void unlock()

Resets the navigation lock if it is currently set. You should usually not call this directly, instead it is meant to be used with presenters that use manual reveal via ProxyPlace.manualReveal(com.gwtplatform.mvp.client.Presenter) and ProxyPlace.manualRevealFailed().

See Also:

Presenter.useManualReveal(), ProxyPlace.manualReveal(com.gwtplatform.mvp.client.Presenter), ProxyPlace.manualRevealFailed()

hasPendingNavigation

boolean hasPendingNavigation()

Checks if the PlaceManager has to perform any pending navigation that were not immediately executed because it was requested while the navigation was locked.

Returns:

true if there are any pending navigation requests, false otherwise.