Don't understand the realValue of getDataSetForValueList

[nick1461658753]

When you have a valuelist and use a global method, you get this code snippet.
I get how the first two work and when they are called. But don't understand when and how the third option (realValue != null ) works, can someone plz explain or give me a link with an explenation because I don't seem to find it.

Code: Select all

/**
* Called when the valuelist needs data, it has 3 modes.
* real and display params both null: return the whole list
* only display is specified, called by a typeahead, return a filtered list
* only real value is specified, called when the list doesnt contain the real value for the give record value, this will insert this value into the existing list
*
* @param {String} displayValue The value of a lookupfield that a user types
* @param realValue The real value for a lookupfield where a display value should be get for
* @param {JSRecord} record The current record for the valuelist.
* @param {String} valueListName The valuelist name that triggers the method. (This is the FindRecord in find mode, which is like JSRecord has all the columns/dataproviders, but doesn't have its methods)
* @param {Boolean} findMode True if foundset of this record is in find mode
* @param {Boolean} rawDisplayValue The raw displayValue without being converted to lower case
*
* @return {JSDataSet} A dataset with 1 or 2 columns display[,real]
*
* @properties={typeid:24,uuid:"AA41BF59-E584-4A46-B446-B1A8BFA5E2C4"}
*/
function getDataSetForValueList( displayValue, realValue, record, valueListName, findMode, rawDisplayValue ) {
   var args = null;
   var query = datasources.db.example_data.employees.createSelect( );
   /** @type  {JSDataSet} */
   var result = null;
   if ( displayValue == null && realValue == null ) {
      // TODO think about caching this result. can be called often!
      // return the complete list
      query.result.add( query.columns.firstname.concat( ' ' ).concat( query.columns.lastname ) ).add( query.columns.employeeid );
      result = databaseManager.getDataSetByQuery( query, 100 );
   }
   else if ( displayValue != null ) {
      // TYPE_AHEAD filter call, return a filtered list
      args = [displayValue + "%", displayValue + "%"];
      query.result.add( query.columns.firstname.concat( ' ' ).concat( query.columns.lastname ) ).add( query.columns.employeeid ).root.where.add( query.or.add( query.columns.firstname.lower.like( args[0] + '%' ) ).add( query.columns.lastname.lower.like( args[1] + '%' ) ) );
      result = databaseManager.getDataSetByQuery( query, 100 );
   }
   else if ( realValue != null ) {
      // TODO think about caching this result. can be called often!
      // real object not found in the current list, return 1 row with display,realvalue that will be added to the current list
      // dont return a complete list in this mode because that will be added to the list that is already there
      args = [realValue];
      query.result.add( query.columns.firstname.concat( ' ' ).concat( query.columns.lastname ) ).add( query.columns.employeeid ).root.where.add( query.columns.employeeid.eq( args[0] ) );
      result = databaseManager.getDataSetByQuery( query, 1 );
   }
   return result;

}

[patrick]

For value lists with display/real values you have these situations:

1. nothing is in the field (displayValue == null, realValue == null): you want to show the whole list
2. the field is still empty (no real value), but the user starts typing (displayValue != null, realValue == null): you want to show a filtered list depending on what is entered up to know
3. the field is not empty (a real value is already in the field): you want to resolve that value and show the displayValue for the realValue in the field

That last one is the very usual case when a value is already set but the user is not editing, he is just looking at the (resolved) value. Once the user clears the (display) value and starts editing, you are back in situation 2.

[nick1461658753]

Ok I think I get it now, thanks