JavaScript widget controllers - Revision history

Beghelli: /* Notification */ Gramatical correction???

2013-04-16T02:17:05Z

‎Notification: Gramatical correction???

Beghelli: added notification doc

2013-04-16T02:15:59Z

added notification doc

Beghelli: /* Modals */ Clarification

2013-04-16T01:31:24Z

‎Modals: Clarification

Beghelli: Remove nonsense about autocomplete input sync mode

2013-04-15T19:10:55Z

Remove nonsense about autocomplete input sync mode

Beghelli: Added site handler

2013-04-15T18:20:38Z

Added site handler

Beghelli: added autocomplete controller documentation

2013-04-14T04:15:24Z

added autocomplete controller documentation

Beghelli: change multilingual input page link

2013-04-12T17:51:14Z

change multilingual input page link

Beghelli: added multilingual input widget description

2013-04-12T17:40:33Z

added multilingual input widget description

Jerico.dev: fixed action names

2011-03-18T06:17:30Z

fixed action names

Jerico.dev: Added link action start/stop events.

2011-03-18T06:17:04Z

Added link action start/stop events.

@@ Line 148: / Line 148: @@
 Those 3 controllers will always use a notification helper to finde and decide the best notification controller to re-trigger the notifyUser event (see NotificationHelper.js inline documentation to better understand). If none is found, then the SiteHandler will present the general notification.
-Though the implementation may be a little odd, the usage is simple: if you want to present in place notifications, first you have to know what type of notifications you want to show. Then you build a notification options with those parameters (like the workflow example above) and add the inPlaceNotification.tpl into the template, placing it where you want to show the notification. You also have to make sure a notifyUser event will be triggered after the action you want to show the notification. The notifyUser event is already automatically triggered by the system when dataChanged event is returned as a response to the client.
+Despite the implementation seems a little odd, the usage is simple: if you want to present in place notifications, first you have to know what type of notifications you want to show. Then you build a notification options with those parameters (like the workflow example above) and add the inPlaceNotification.tpl into the template, placing it where you want to show the notification. You also have to make sure a notifyUser event will be triggered after the action you want to show the notification. The notifyUser event is already automatically triggered by the system when dataChanged event is returned as a response to the client.
 So, for example, if you want to present a non-trivial notification after a user deleted an item inside a grid (trivial notifications will always be handled by the site handler when the notifyUser event comes inside a grid), you just have to build the parameters, place the notification template and make sure that the notification is created into the database when the user deletes the item. TBD: a better documentation about the notification system on the server side in a new page an link it here.
 If there is a case where the system is not already triggering the notifyUser event, you can return it as a server response to the client side. But those cases are unlikely to happen.

← Older revision		Revision as of 02:15, 16 April 2013
Line 140:		Line 140:

	{fbvElement type="autocomplete" autocompleteUrl=$autocompleteUrl id="dataNameToBePosted" label="any.locale.key" value='anyValueAlreadyStoredByThisField'}		{fbvElement type="autocomplete" autocompleteUrl=$autocompleteUrl id="dataNameToBePosted" label="any.locale.key" value='anyValueAlreadyStoredByThisField'}
		+
		+	== Notification ==
		+
		+	We have two different types of notification: in place and general. The notification controller is responsible for the in place ones. It will listen to the notifyUser event and it will request to the server all notifications that matches the ones defined on its options (notification type, assoc type, etc). You have to define the in place notification controller options on the php side, pass them to the template manager as a variable and use them when you add the in place notification template file to your template. See WorkflowHandler::production() and also templates/workflow/production.tpl to understand this process.
		+
		+	The notification controller will not listen to events that are comming from the DOM hierarchy, because it will never have a widget inside of it. It is meant to just listen to the notifyUser event that is always triggered by some parent widget. The widgets that really listen to the notifyUser events that comes from the other widgets are the ModalHandler, the PageHandler and the SiteHandler.
		+	Those 3 controllers will always use a notification helper to finde and decide the best notification controller to re-trigger the notifyUser event (see NotificationHelper.js inline documentation to better understand). If none is found, then the SiteHandler will present the general notification.
		+
		+	Though the implementation may be a little odd, the usage is simple: if you want to present in place notifications, first you have to know what type of notifications you want to show. Then you build a notification options with those parameters (like the workflow example above) and add the inPlaceNotification.tpl into the template, placing it where you want to show the notification. You also have to make sure a notifyUser event will be triggered after the action you want to show the notification. The notifyUser event is already automatically triggered by the system when dataChanged event is returned as a response to the client.
		+
		+	So, for example, if you want to present a non-trivial notification after a user deleted an item inside a grid (trivial notifications will always be handled by the site handler when the notifyUser event comes inside a grid), you just have to build the parameters, place the notification template and make sure that the notification is created into the database when the user deletes the item. TBD: a better documentation about the notification system on the server side in a new page an link it here.
		+
		+	If there is a case where the system is not already triggering the notifyUser event, you can return it as a server response to the client side. But those cases are unlikely to happen.

@@ Line 27: / Line 27: @@
 In order to being able to use the modal without creating too close of a coupling to other unrelated widgets, we introduced an "event bridge" that effectively forwards well-defined events to the calling context. It would badly break encapsulation if a modal would update a grid directly, for example. The modal would have to "know" about specific grids which would drastically reduce it's potential for re-use.
-The event bridge resolves reduces the necessary coupling. If, for example, you open the modal from a link action in a grid then modal events can be forwarded via the event bridge to the link action and thereby bubble into the grid which makes it possible for the grid to react to events generated by the modal. If the modal updates an element of the grid, then a grid refresh event can be forwarded to the grid so that the grid "knows" it has to update itself. This is a much looser coupling of modal and grid than if the modal had to update the grid itself.
+The event bridge resolves reduces the necessary coupling. If, for example, you open the modal from a link action in a grid then modal events can be forwarded via the event bridge to the link action and thereby bubble into the grid which makes it possible for the grid to react to events generated by the modal. If the modal changes the data presented on the grid, then a grid refresh event can be forwarded to the grid so that the grid "knows" it has to update itself. This is a much looser coupling of modal and grid than if the modal had to update the grid itself.
 For performance reasons we cannot forward all events triggered inside the modal, though. This means that if you need an event generated inside the modal in the calling context then you have to "publish" it. While this still creates a certain amount of unwanted "upwards" coupling between the modal, it seems an acceptable compromise between performance and maintenance requirements. Coupling is kept to a minimum so that in practice we can maintain very broad re-usability of our modal widget. You'll have to remember, though, to publish your events if you want them to be forwarded. Please have a look at the ModalHandler object's constructor for examples (page redirection, grid refresh, ...) how to do that.
 == Forms ==

@@ Line 133: / Line 133: @@
 '''Sycronized with user typing''' (DEFAULT)
-No matter if user used an option of the result JSON query or not, the controller will always update what user types into the visible field to the hidden field value. That way you can let your users entering different data other than the options that you pre selected to them. Because of its nature, this mode will NOT support the label and value response distinction. It will always use the label value, that is, what is being shown into the field.
+No matter if user used an option of the result JSON query or not, the controller will always update what user types into the visible field to the hidden field value. That way you can let your users entering different data other than the options that you pre selected to them. This mode will NOT support the label and value response distinction yet. It will always use the label value, that is, what is being shown into the field.
 '''Restricted to a set of values'''

← Older revision		Revision as of 18:20, 15 April 2013
Line 69:		Line 69:
	The default implementation of the wizard does not do any validation checks. It provides default event handlers that automatically advance the wizard to the next step when the user clicks the "continue" button and closes the wizard after the last step.		The default implementation of the wizard does not do any validation checks. It provides default event handlers that automatically advance the wizard to the next step when the user clicks the "continue" button and closes the wizard after the last step.

		+
		+	== Site Handler ==
		+
		+	This controller is attached to the body element and it is the first one into the widgets hierarchy. The handler represents the content of the entire site, which includes the header, side bars and footer. It listen to many events, related to notifications, redirection, sidebar and header refreshing, helper system, changes not saved warning and it also apply plugins to some elements.
		+

	== Page Handler ==		== Page Handler ==

← Older revision		Revision as of 04:15, 14 April 2013
Line 115:		Line 115:

	See [[multilingual input]] user interface example.		See [[multilingual input]] user interface example.
		+
		+	== Autocomplete inputs ==
		+
		+	Inputs that will give users options while they are typing. It uses ajax requests to server to query the options that matches what users already typed.
		+
		+	To work with an autocomplete field you should tell the controller which operation should be used to query the suggestions, while user is typing. You define this inside the FBV tab, using the autocompleteUrl option. You can build the url using the smarty function url (see PKPTemplateManager::smartyUrl()) or you can build it into the php handler and pass it to the template manager in a variable.
		+
		+	The server operation should return a JSON message with an array containing all the values that should be presented. You must return an array with items containing another array with two keys: label and value. The label will only be used to visualization and the value will be the data that the form will send to the server on a form submit action. Eg.:
		+	array(array('label' => 'Label 1', 'value' => 1), array('label' => 'Label 2', 'value' => 2))
		+
		+	This widget supports two modes of operation:
		+
		+	'''Sycronized with user typing''' (DEFAULT)
		+	No matter if user used an option of the result JSON query or not, the controller will always update what user types into the visible field to the hidden field value. That way you can let your users entering different data other than the options that you pre selected to them. Because of its nature, this mode will NOT support the label and value response distinction. It will always use the label value, that is, what is being shown into the field.
		+
		+	'''Restricted to a set of values'''
		+	Users will not be able to submit any value other than the ones returned by the query request. They will have to select one of those that appears from the query based on what they are typing. If no option appears or if one appears but users don't select it but just continues typing, then the hidden field will not be updated and no data will be submitted to the server on form submission. Use this when you want to restrict what users can choose as data for this input. To use this option, you have to add the option disableSync=true into the FBV method, inside the template.
		+
		+	You also have to define the name of the variable that will be posted to the server on form submit, so you can get the data the user has selected or typed. You can define this using the id option, inside the autocomplete FBV method, also inside the template. A common autocomplete FBV definition inside template should be:
		+
		+	{fbvElement type="autocomplete" autocompleteUrl=$autocompleteUrl id="dataNameToBePosted" label="any.locale.key" value='anyValueAlreadyStoredByThisField'}

← Older revision		Revision as of 17:51, 12 April 2013
Line 114:		Line 114:
	The multilingual input also works with tiny mce editor.		The multilingual input also works with tiny mce editor.

−	See [[multilingual input UI]].	+	See [[multilingual input]] user interface example.

← Older revision		Revision as of 17:40, 12 April 2013
Line 105:		Line 105:
	* actionStart		* actionStart
	* actionStop		* actionStop
		+
		+	== Multilingual inputs ==
		+
		+	Multilingual-capable fields will show all available locale fields for a data at once when the first one is focused. The first one presents always the data into the user interface locale. As soon as no other localized field is focused, all the others will be hidden and just the first one is visible again.
		+
		+	To use it just add the multilingual=true parameter inside the fbv tag, inside the template file. The js controller will be automatically attached to the html and, if you are in a multilingual scenario, you will see the other fields as soon as you focus the first one.
		+
		+	The multilingual input also works with tiny mce editor.
		+
		+	See [[multilingual input UI]].

@@ Line 103: / Line 103: @@
 Link actions emit two events which you can use, e.g. to trigger a throbber while the link action is active:
-* linkActionStart
+* actionStart
-* linkActionStop
+* actionStop

← Older revision		Revision as of 06:17, 18 March 2011
Line 101:		Line 101:

	The downside of this flexibility is that you have to understand quite a bit of abstract code to introduce new link actions if you cannot use one of the existing action types. The easiest way to do so is to configure some [http://www.xdebug.org/ PHP debugger] on the server side and use FireBug on the client side to step through the code.		The downside of this flexibility is that you have to understand quite a bit of abstract code to introduce new link actions if you cannot use one of the existing action types. The easiest way to do so is to configure some [http://www.xdebug.org/ PHP debugger] on the server side and use FireBug on the client side to step through the code.
		+
		+	Link actions emit two events which you can use, e.g. to trigger a throbber while the link action is active:
		+	* linkActionStart
		+	* linkActionStop