h1. Grails
[Grails|http://www.grails.org]is a leading productive development framework based on JAVA famous technologies Spring, Hibernate and Groovy. Grails brings a public plugin repository, allowing developpers to simply retrieve framework dependencies when they want.
You can get ICEpush capabilities in your application with the following [Grails plugin|http://www.grails.org/plugin/icepush], just type :
{code}
grails install-plugin icepush
{code}
Without more configuration you will have access to :
# [Dynamically injected methods|#dynamics] in grails artefacts which provide a simple access to ICEpush API
# A set of [GSP tags|#tags] that can be included in the page to register pushIDs or manage regions of dynamic content.
# [ICEfaces 2 plugin push|#icefaces2] capabilities and collaborative application 'scaffolding'
h2. {anchor:tags}GSP Tags
h3. {{<icep:bridge>}}
Includes ICEpush library in the current page.
{code}
<html>
<head>
...
<icep:bridge />
</head>
...
</html>
{code}
h3. {{<icep:pushId>}}
Creates and outputs a pushId.
{code}
<g:set var='pushId_1' value="${icep:pushId}" />
{code}
h3. {{<icep:register>}}
The {{register}} tag creates a unique pushID if not specified and registers a JavaScript callback with it. It optionally declares a group that the pushID belongs to.
{code}
<icep:register callback="myScript" group="myGroup" />
{code}
|| Attribute || Required || Description ||
| {{callback}} | (+) | A JavaScript callback function capable of handling notifications to the assigned pushID. |
| {{group}} | (-) | A group name that the pushID will be registered with. If the group is not supplied it defaults to the pushID itself, resulting in a unique group of 1 for the pushID. |
| {{pushid}}| (-) | A specified pushId to use instead of creating a new one |
h3. {{<icep:region>}}
The {{region}} tag creates a unique pushID if not specified and associates it with a specific included page. The dynamic page content is included initially when the page loads, and is reloaded using an ajax {{GET}} when notifications occur to the pushID. The group name is included as a parameter to the {{GET}} request, so it is available to the included page. It optionally declares a {{<div>}} id for the updated region, a group that the pushID belongs to, and a notifier bean responsible for triggering notifications.
{code}
<icep:region group="chatGroup" controller="chat" action="messages"/>
{code}
|| Attribute || Required || Description ||
| {{wrapperid}} | (-) | ID of the {{<div>}} that will form the region and contain the dynamic content. If defined, it must be unique to the page. If not defined, it defaults to the unique pushID. |
| {{group}} | (-) | A group name that the pushID will be registered with. If the group is not supplied it defaults to the pushID itself, resulting in a unique group of 1 for the pushID. |
| {{action}} | (-) | the name of the action to use in the include |
| {{controller}} | (-) | the name of the controller to use in the include |
| {{id}} | (-) | the id to use in the include |
| {{view}} | (-) | The name of the view to use in the include |
| {{params}} | (-) | a map containing request parameters |
| {{evalJS}} | (-) | Determines whether any embedded scripts in the content that is fetched after a Push notification are evaluated (default true). Evaluating embedded scripts does carry some client-side overhead that the developer should be aware of. If the region tag is fetching areas of large content that is known not to have any embedded scripts (eg. a large amount of table data), then performance may be improved by setting {{evalJS}} to false. Please note, that if it is required to nest region tags, the outer tags will have to have evalJS=true (default) for the rendered JavaScript of the inner region tags to be evaluated, which is required for the proper functioning of the region tag. |
| {{pushid}} | (-) | A specified pushId to use instead of creating a new one |
h3. {{<icep:page>}}
The {{page}} tag causes a full page refresh to occur to the named group. Like {{region}} tag, it targets a set of Grails request attributes like 'action' or 'controller'.
{code}
<icep:region group="breakingNews" controller="news" action="alert"/>
{code}
|| Attribute || Required || Description ||
| {{group}} | (-) | A group name that the pushID will be registered with. If the group is not supplied it defaults to the pushID itself, resulting in a unique group of 1 for the pushID. |
| {{action}} | (-) | the name of the action to use in the include |
| {{controller}} | (-) | the name of the controller to use in the include |
| {{id}} | (-) | the id to use in the include |
| {{view}} | (-) | The name of the view to use in the include |
| {{params}} | (-) | a map containing request parameters |
| {{pushid}}| (-) | A specified pushId to use instead of creating a new one |
h3. {{<icep:push>}}
The {{push}} tag causes a push notification to occur to the named group, on when the page loads.
{code}
<icep:push group="myGroup"/>
{code}
|| Attribute || Required || Description ||
| {{group}} | (+) | A group name to receive periodic push notifications. |
h2. {anchor:notification}Notification
For notifications to occur, the notification business logic must have a valid {{PushContext}} to use. While in a normal or ajax-based request/response cycle the {{PushContext}} is readily available using the {{ServletContext}}. In Grails controllers, services or beans you can access it by typing {{pushContext}} :
{code}
def action = {
if(pushContext)
...
}
{code}
If, however, notification triggers are to occur outside a request/response cycle, the notifying thread of execution still needs a valid {{PushContext}} to use.
h2. {anchor:dynamics}Dynamic Methods and Properties
h3. {{pushContext}}
Access to the actual PushContext instance.
{code}
pushContext{code}
h3. {{pushId}}
Return a new PushId on each call, to be used inside a request/response cycle.
{code}
def myId = pushId{code}
h3. {{addToPushGroup(String group, String pushId?)}}
Add a pushId to specified group. If pushId is not specified, a new one is created and returned.
{code}
//One paramater syntax, returns a new pushId
def newId = addToPushGroup('chat')
//Two parameters syntax, reuse a specified pushId
addToPushGroup('news',newId)
{code}
h3. {{removeFromPushGroup(String group, String pushId)}}
Remove the provided pushId from the specified group.
{code}
//retrieve a pushId from a parameter
def _pushId = params.pushId
removeFromPushGroup('chat', _pushId){code}
h3. {{push(String group)}}
Notify target group.
{code}
serviceMethod(){
...
push 'chat'
}
{code}
h2. Group Naming
Group naming employees application-specific strategies. While group naming is orthogonal to JSP bean scopes, they can effectively be associated with a scope.
* Window-scoped groups are not named, and use only the unique pushID assigned during registration. These names/pushIDs will change each time the page is loaded.
* Session-scoped groups include the session ID: {{group="$\{session.id\}.myGroup"}}
* Application-scoped groups have static names: {{group="myGroup"}}
* Deployment-scoped groups have static names beginning with a "/": {{group="/myGroup"}}
{note}Deployment scope is only available in multi-application deployments with Enterprise Push Server.{note}
h2. {anchor:icefaces2} ICEfaces 2 Plugin Push capabilities
You can combine ICEpush plugin and ICEfaces2 plugin to leverage outstanding collaborative applications.
ICEfaces 2 plugin is not yet available, more informations will be provided when it will be released.
[Grails|http://www.grails.org]is a leading productive development framework based on JAVA famous technologies Spring, Hibernate and Groovy. Grails brings a public plugin repository, allowing developpers to simply retrieve framework dependencies when they want.
You can get ICEpush capabilities in your application with the following [Grails plugin|http://www.grails.org/plugin/icepush], just type :
{code}
grails install-plugin icepush
{code}
Without more configuration you will have access to :
# [Dynamically injected methods|#dynamics] in grails artefacts which provide a simple access to ICEpush API
# A set of [GSP tags|#tags] that can be included in the page to register pushIDs or manage regions of dynamic content.
# [ICEfaces 2 plugin push|#icefaces2] capabilities and collaborative application 'scaffolding'
h2. {anchor:tags}GSP Tags
h3. {{<icep:bridge>}}
Includes ICEpush library in the current page.
{code}
<html>
<head>
...
<icep:bridge />
</head>
...
</html>
{code}
h3. {{<icep:pushId>}}
Creates and outputs a pushId.
{code}
<g:set var='pushId_1' value="${icep:pushId}" />
{code}
h3. {{<icep:register>}}
The {{register}} tag creates a unique pushID if not specified and registers a JavaScript callback with it. It optionally declares a group that the pushID belongs to.
{code}
<icep:register callback="myScript" group="myGroup" />
{code}
|| Attribute || Required || Description ||
| {{callback}} | (+) | A JavaScript callback function capable of handling notifications to the assigned pushID. |
| {{group}} | (-) | A group name that the pushID will be registered with. If the group is not supplied it defaults to the pushID itself, resulting in a unique group of 1 for the pushID. |
| {{pushid}}| (-) | A specified pushId to use instead of creating a new one |
h3. {{<icep:region>}}
The {{region}} tag creates a unique pushID if not specified and associates it with a specific included page. The dynamic page content is included initially when the page loads, and is reloaded using an ajax {{GET}} when notifications occur to the pushID. The group name is included as a parameter to the {{GET}} request, so it is available to the included page. It optionally declares a {{<div>}} id for the updated region, a group that the pushID belongs to, and a notifier bean responsible for triggering notifications.
{code}
<icep:region group="chatGroup" controller="chat" action="messages"/>
{code}
|| Attribute || Required || Description ||
| {{wrapperid}} | (-) | ID of the {{<div>}} that will form the region and contain the dynamic content. If defined, it must be unique to the page. If not defined, it defaults to the unique pushID. |
| {{group}} | (-) | A group name that the pushID will be registered with. If the group is not supplied it defaults to the pushID itself, resulting in a unique group of 1 for the pushID. |
| {{action}} | (-) | the name of the action to use in the include |
| {{controller}} | (-) | the name of the controller to use in the include |
| {{id}} | (-) | the id to use in the include |
| {{view}} | (-) | The name of the view to use in the include |
| {{params}} | (-) | a map containing request parameters |
| {{evalJS}} | (-) | Determines whether any embedded scripts in the content that is fetched after a Push notification are evaluated (default true). Evaluating embedded scripts does carry some client-side overhead that the developer should be aware of. If the region tag is fetching areas of large content that is known not to have any embedded scripts (eg. a large amount of table data), then performance may be improved by setting {{evalJS}} to false. Please note, that if it is required to nest region tags, the outer tags will have to have evalJS=true (default) for the rendered JavaScript of the inner region tags to be evaluated, which is required for the proper functioning of the region tag. |
| {{pushid}} | (-) | A specified pushId to use instead of creating a new one |
h3. {{<icep:page>}}
The {{page}} tag causes a full page refresh to occur to the named group. Like {{region}} tag, it targets a set of Grails request attributes like 'action' or 'controller'.
{code}
<icep:region group="breakingNews" controller="news" action="alert"/>
{code}
|| Attribute || Required || Description ||
| {{group}} | (-) | A group name that the pushID will be registered with. If the group is not supplied it defaults to the pushID itself, resulting in a unique group of 1 for the pushID. |
| {{action}} | (-) | the name of the action to use in the include |
| {{controller}} | (-) | the name of the controller to use in the include |
| {{id}} | (-) | the id to use in the include |
| {{view}} | (-) | The name of the view to use in the include |
| {{params}} | (-) | a map containing request parameters |
| {{pushid}}| (-) | A specified pushId to use instead of creating a new one |
h3. {{<icep:push>}}
The {{push}} tag causes a push notification to occur to the named group, on when the page loads.
{code}
<icep:push group="myGroup"/>
{code}
|| Attribute || Required || Description ||
| {{group}} | (+) | A group name to receive periodic push notifications. |
h2. {anchor:notification}Notification
For notifications to occur, the notification business logic must have a valid {{PushContext}} to use. While in a normal or ajax-based request/response cycle the {{PushContext}} is readily available using the {{ServletContext}}. In Grails controllers, services or beans you can access it by typing {{pushContext}} :
{code}
def action = {
if(pushContext)
...
}
{code}
If, however, notification triggers are to occur outside a request/response cycle, the notifying thread of execution still needs a valid {{PushContext}} to use.
h2. {anchor:dynamics}Dynamic Methods and Properties
h3. {{pushContext}}
Access to the actual PushContext instance.
{code}
pushContext{code}
h3. {{pushId}}
Return a new PushId on each call, to be used inside a request/response cycle.
{code}
def myId = pushId{code}
h3. {{addToPushGroup(String group, String pushId?)}}
Add a pushId to specified group. If pushId is not specified, a new one is created and returned.
{code}
//One paramater syntax, returns a new pushId
def newId = addToPushGroup('chat')
//Two parameters syntax, reuse a specified pushId
addToPushGroup('news',newId)
{code}
h3. {{removeFromPushGroup(String group, String pushId)}}
Remove the provided pushId from the specified group.
{code}
//retrieve a pushId from a parameter
def _pushId = params.pushId
removeFromPushGroup('chat', _pushId){code}
h3. {{push(String group)}}
Notify target group.
{code}
serviceMethod(){
...
push 'chat'
}
{code}
h2. Group Naming
Group naming employees application-specific strategies. While group naming is orthogonal to JSP bean scopes, they can effectively be associated with a scope.
* Window-scoped groups are not named, and use only the unique pushID assigned during registration. These names/pushIDs will change each time the page is loaded.
* Session-scoped groups include the session ID: {{group="$\{session.id\}.myGroup"}}
* Application-scoped groups have static names: {{group="myGroup"}}
* Deployment-scoped groups have static names beginning with a "/": {{group="/myGroup"}}
{note}Deployment scope is only available in multi-application deployments with Enterprise Push Server.{note}
h2. {anchor:icefaces2} ICEfaces 2 Plugin Push capabilities
You can combine ICEpush plugin and ICEfaces2 plugin to leverage outstanding collaborative applications.
ICEfaces 2 plugin is not yet available, more informations will be provided when it will be released.