Opened 8 years ago

Closed 8 years ago

#14994 closed enhancement (fixed)

Provide a simple example for the usage of a MappedTextBox

Reported by: Paul Christopher Owned by: haysmark
Priority: undecided Milestone: 1.8
Component: Documentation Version: 1.7.2
Keywords: Cc:
Blocked By: Blocking:

Description

Description

http://livedocs.dojotoolkit.org/dijit/form/MappedTextBox explains what a MappedTextBox is but does not show how to use it. A simple short example would be helpful.

I have set up some code, see http://jsfiddle.net/Tjm6C/ which works in a way but which is also partly wrong. Maybe we can fix the example and add it to the docs? It is a simple example that shows the difference between the displayed value and the real value and how to set these values.

Discussion

I'm new to Dojo and I had really a hard time understanding the code of MappedTextBoxan and NumberTextBox. The idea of a MappedTextBox is a good idea. However it should be explained in more detail, how to use it. And it seems to be not that trivial. Nobody on the mailing list could help me. Therefore I place it here.

Attachments (3)

exampleMappedTextBox2.html (5.1 KB) - added by Paul Christopher 8 years ago.
exampleMappedTextBox.html (6.2 KB) - added by Paul Christopher 8 years ago.
testExampleHaysmark.html (910 bytes) - added by Paul Christopher 8 years ago.

Download all attachments as: .zip

Change History (19)

comment:1 Changed 8 years ago by bill

Owner: set to Douglas Hays
Status: newassigned

comment:2 Changed 8 years ago by Paul Christopher

The basic idea of the example is as follows: You can enter an id in the textbox. Then the textbox searches for this id in a dojo memory store and displays the respective full description on blur (which is actually a car name). It's a simple example (maybe not the best one from the point of view of accessibility). But it clearly shows the difference between a real value and the displayed value and how they interact. This understanding is a prerequisit for understanding how e.g. NumberTextBox works. This understanding is also a prerequisit, if you want to write your own widget based on a MappedTextBox.

The example code works in so far that you can enter and id and onblur, the textbox shows the correct full name of the id. You can also submit the form and you will get the correct value of the widget on the server. However all the get/set methods do not work and it is unclear how to change them. _TextBoxMixin seems to possess MappedTextBox capabilities since _setValueAttr seems to be prepared for the usage of a MappedTextBox (which is actually never used in the code, since _setValueAttr is never called with a formattedValue???). But at this point, for me as a newbie, it really gets very difficult to understand the code. I would have expected to find all the necessary things for a MappedTextBox in MappedTextBox.js only (e.g. that on focus the hidden value is set as the displayed value automatically, how the validator needs to be changed therefore [since it needs to validate in two different modes of operation], how _setValueAttr, _getValueAttr, _setDisplayedValueAttr, _getDisplayedValueAttr need to be changed etc.)

comment:3 Changed 8 years ago by Douglas Hays

Milestone: tbd1.8
Owner: changed from Douglas Hays to haysmark

comment:4 Changed 8 years ago by haysmark

Resolution: fixed
Status: assignedclosed

Added comment describing minimum requirements for using a MappedTextBox?.

comment:5 Changed 8 years ago by bill

Resolution: fixed
Status: closedreopened

I see https://github.com/dojo/docs/commit/6f31fe69e72431641a7b5ccc67dcd5d188c05b0a#diff-0 but there's no example (there should be a .. code-example :: pragma in the file).

comment:6 Changed 8 years ago by haysmark

Bill, I'm withdrawing my previous doc commit. I thought users could just override serialize, but no. Furthermore, it turns out the API docs say that the MappedTextBox? widget, toString, and serialize are all protected access. Why is MappedTextBox? in the public APIs at all? It should be named _MappedTextBox like all of the other protected classes, no?

comment:7 Changed 8 years ago by haysmark

Here is an example that does not reinvent our other dijit wheels; it just converts the behind-the-scenes value to upper case to send to the server. I still don't think we should have a page at all.

<!DOCTYPE html>
<html >
<head>

	<link rel="stylesheet" href="dijit/themes/claro/claro.css">
	
<script src='dojo/dojo.js' data-dojo-config='parseOnLoad: true'></script>
<script>
require(["dojo","dijit/form/MappedTextBox"],function(dojo,MappedTextBox){
	dojo.ready(function(){
		var textbox=new MappedTextBox({
			format: function(value){
				// leave alone
				return this.get('displayedValue');
			},
			parse: function(displayedValue){
				// parse user input to send canonical value to server
				return displayedValue.toUpperCase();
			}
		},dojo.byId('textBox'));
	});
});</script>
</head>
<body class="claro">
    <div id="textBox" />
</body>
</html>

comment:8 Changed 8 years ago by bill

Why is MappedTextBox in the public APIs at all?

I guess for the same reason that _FormWidgetMixin, _WidgetBase, etc. are: people may want to use the class. Like the guy that wrote this ticket.

It should be named _MappedTextBox like all of the other protected classes, no?

Dijit often uses underscores for base classes and mixins (as opposed to widgets that may appear directly on the page) but that's neither here nor there. In other words, the underscore on class names doesn't mean protected.

Anyway, I think your example looks fine to add to the doc page, except it's still referencing the dojo global via dojo.ready().

Last edited 8 years ago by bill (previous) (diff)

comment:9 Changed 8 years ago by Paul Christopher

Attached you can find another short, very simple example: The user can input a car name and the car name is then converted to a car id that is sent to the server. This pattern is mainly the pattern some kind of select like widget might use (here: without the hasDropDown class).

Yes, Bill is right. I have added this ticket here since I want to reuse MappedTextBox and write my own select like widgets based on that. I also need to enhance NumberTextBox to enable the user to do simple calculations within the box (e.g. 5+2). Therefore I need to understand how NumberTextBox works. However I never really figured it out since things get more complicated there: If you click in the textbox, the displayedValue gets changed to the hidden value (see exampleMappedTextBox.html).

This ticket is about providing short realistic examples of a MappedTextBox which allow for the understanding of the basic patterns of select like widgets and NumberTextBox like widgets. This knowledge is the prerequisit for working successfully with the given components of dijit. At least my experience is: Every customer has special needs, and up to now, I always had to modifiy the given dijit components in a way. Therefore you need to understand how they work.

Thus my request is to provide two short realistic examples of a MappedTextBox (whereas I have already attached two basic examples here!):

  • One for a simple select like use (see exampleMappedTextBox2.html)
  • One for a NumberTextBox like use (see exampleMappedText.html, alas not working correctly so far)

These examples should clearly outline the very basic programming patterns behind the above mentioned widget archetypes.

Changed 8 years ago by Paul Christopher

Attachment: exampleMappedTextBox2.html added

comment:10 in reply to:  8 ; Changed 8 years ago by haysmark

Bill, MappedTextBox? is a mixin. Hence why you need so much boilerplate code to make it useful. Regarding the example, the dojo reference comes from the require statement so it should be OK.

Paul, why users should use MappedTextBox? in these examples over FilteringSelect??

comment:11 Changed 8 years ago by bill

I wouldn't call MappedTextBox a mixin, because it (indirectly) extends _WidgetBase. You may have a different definition of mixin than me, but anyway, it doesn't matter whether it's classified as a mixin or not.

As for the "dojo" dependency in your example, that will work for now, but it's deprecated. dojo/main will presumably disappear in 2.0. That's why our other example code has been upgraded to use minimal dependencies.

Last edited 8 years ago by bill (previous) (diff)

comment:12 in reply to:  10 Changed 8 years ago by Paul Christopher

Replying to haysmark:

Paul, why users should use MappedTextBox in these examples over FilteringSelect?

Sometimes customers have very special needs and if they want their house the be painted pink they get it painted pink! To put it short: For several reasons I could not use FilteringSelect or ComboBox or Select. At the moment I have to write my own select like widget which I derived from MappedTextBox and HasDropDown. Since it needs to have a drop down menu with focus, I didn't use the _AutoCompleterMixin (which is foucsless) but dijit.Select's _SelectMenu.

This works fine and it makes a lot of fun to work with the existing "building blocks". But you can only make your own widgets if you understand how to use the given components, and MappedTextBox caused me a lot of trouble documented since it is so sparsely. And nobody on the mailing list could help me. That's why it places this ticket here.

I never got the idea how NumberTextBox works. It is a MappedTextBox but if you click in it, the hidden value is displayed. It would be great to have some simple uses cases of MappedTextBox.

The reson is: In most cases you cannot use the core components and need to modify them. Bankers e.g. would like to enter not just numbers but do simple calculations within a NumberTextBox. People form the tourism industry want to be able to input dates without separators, e.g. 11212 is 01/12/2012 and 1112 is 11/12/2012 etc.

Changed 8 years ago by Paul Christopher

Attachment: exampleMappedTextBox.html added

comment:13 Changed 8 years ago by Paul Christopher

I could now fix the NumberTextBox like example, see exampleMappedTextBox.html. At least it does something similar... ;-)

comment:14 Changed 8 years ago by Paul Christopher

I have just tested haysmark's example code: textbox.set('value', 'FOO') doesn't work there, see attached test case.

Changed 8 years ago by Paul Christopher

Attachment: testExampleHaysmark.html added

comment:15 Changed 8 years ago by haysmark

Try:

require(['dojo/ready','dijit/form/MappedTextBox'],function(ready,MappedTextBox){
	ready(function(){
		var textbox=new MappedTextBox({
			format: function(value){
				// format set value to display to user.
				var displayed=this.get('displayedValue');
				if(value.toUpperCase()==displayed.toUpperCase()){
					// leave user input alone 
					return displayed;
				}else{
					// update to new value
					return value;
				}
			},
			parse: function(displayedValue){
				// parse user input to send canonical value to server
				return displayedValue.toUpperCase();
			}
		},'textBox');
		 textbox.set('value', 'HI');
	});
});

comment:16 Changed 8 years ago by haysmark

Resolution: fixed
Status: reopenedclosed
Note: See TracTickets for help on using tickets.