Page  1  of  11  

ActiveMatrix BPM™ Select2

Custom form control library for TIBCO AMX BPM

Business Studio Forms

Overview

This is NOT an official TIBCO Development Document. Only a first Draft Version.

Created by Pieter Hagen (ASG TIBCO EMEA)

Date: 12.11.2013

Version: 1.0

 

 Page  2  of  11  

Index  of  contents

INDEX  OF  CONTENTS   2  

CONCEPT   3  

THE  REASON  FOR  A  DIFFERENT  SELECT  BOX?   3  WHAT  IS  SELECT  2?   3  VERSION    1.0  FEATURES   3  FUTURE  EXTENSIONS   3  

AMX  BPM  VERSION  &  INSTALLATION   5  

AMX  BPM  VERSION(S)  TESTED   5  INSTALLATION  IN  BUSINESS  STUDIO  3.6.0   5  

USAGE:   6  

STANDARD  FEATURES   6  SOLUTIONS  –  SELECT2  SINGLE  SELECT   7  SOLUTIONS  –  SELECT2  MULTI  SELECT   8  SOLUTIONS  –  SELECT2  MULTI  SELECT  WITH  LOCKED    SELECTIONS   9  

BUSINESS  STUDIO  FORM  SCRIPTS   10  

OPEN  FORM    EVENT  SCRIPT  LOADING  THE  ID’S,  LABELS  &  OPTIONALLY  THE  LOCKED  ID’S   10  ON  UPDATE  EVENT  OF  CONTROL  TO  PUSH  THE  VALUE  TO  AN  OTHER  CONTROL   10  SCRIPT  PUSHING    MULTIPLE  VALUES  TO  THE  SELECT2  CONTROL   10  SCRIPT  THAT  CAN  BE  USED  TO  ENABLE/DISABLE  THE  SELECT2  CONTROL   10  

 

 Page  3  of  11  

Concept  

The  reason  for  a  different  Select  box? One of the most common issues with the standard select box is that it becomes difficult to mange if it contains a large amount of data. The select2 select box offers various features above and beyond the regular component.

with  this  :   It can replace this  :                                

A  select  box  that  includes    a  searchbox    wich  will  automaticly  refine  the  record  set  while  you  type  alowing  you  to  quickly  find  the  desired  record  in  the  numerous  options.  

It  can  also  handle  multiple  selections    and  it  will    place   them as tags in the control for easy identification of the options selected.

What  is  select  2?  Select2  is  a  jQuery  based  replacement  for  select  boxes.  It  supports  searching,  remote  data  sets,  and  infinite  scrolling  of  results.    It  can  be  found  at  http://ivaynberg.github.io/select2/  

Its  written  Igor  Vaynberg

Select2  is  licensed  under  the  Apache  Software  Foundation  License  Version  2.0  and  GPL  Version  2.0.    

Version    1.0  Features • Ability  to  search  and  refine  your  result  set  • Single  and  multiple  selections  possible  • Controlling  the  size  of  the  object  at  runtime  • Provide  text  array  for  both  labels  and  ID’s  though  Setter  functions  or  use  provide  the  values  

at  design  time  • Have  a  separate  items  for  ID’s  that  need  to  be  locked  in  a  multiple  select  (Locked  items  are  

selected  by  default  and  cannot  be  removed)  • Control  the  Disable  state  thought  property  and  setter  function.  • Set  the  placeholder  text  in  the  control  when  no  selection  is  made  

Future  Extensions • Limited amount of selection when in multiple selection mode • Control the matching to match only the beginning of the text

 

 Page  4  of  11  

• Set the minimum input for search term when using a large dataset

 

 Page  5  of  11  

 AMX  BPM  Version  &  Installation  

AMX  BPM  Version(s)  tested    The  library  has  been  developed  against  a  AMX  BPM  2.2  platform  using  Business  studio  3.6.  Currently  no  effort  has  been  taken  to  build  this  library  for  AMX  BPM  2.1  or  lower.  

Installation  in  Business  Studio  3.6.0  Version  1.0  of  the  library  is  shipped  in  MultiSelect1.0.zip  

The  library  needs  to  be  imported  into  your  workspace  from  the  above  zip  fileand  needs  to  be  set  as  a  referenced  project:

 

This  should  provide  you  with  an  additional  icon  in  the  Custom  Control  palette:      

If  you  drag  this  icon  to  you  form  it  will  place  the  following  object  placeholder:  

 

 

 

   

 

 

 

 

 Page  6  of  11  

 

 

Usage:  

Standard  features  When  placing  the  placeholder  on  your  form  and  selecting  properties  the  following  screen  will  be  shown:  

 • Control  Enabled  :     Allows  you  to  set  the  select2  control  enabled  or  disabled    • Diagram  Height  :     The  Height  at  runtime  of  the  select2  object  (*1)  • Diagram  Width   :     The  Width  at  runtime  of  the  select2  object    (*1)  • ID  Array:       Fixed  Values  for  the  ID’s  used  as  a  return  value  (  **,*2)  • Label  Array:       Fixed  Values  for  the  Label  the  user  sees  (**,*2)  • Locked  ID’s  Array:     Fixed  Values  holding  ID’s  that  are    

preselected  and  cannot  be  removed  (**,*2  *3)  • Multiple  Selections:     Presets  the  select2  box  for  single  or  multiple  usage  • The  Placeholder  for  the  select:   The  text  you  wish  to  display  in  the  select2  box    

   **  Property  Screen  with  Fixed  Value  array  editor.  

Each  of  these  options  has  a  corresponding  Getter  and  Setter  function  that  can  be  used  in  the  various  scripts  in  your  form.  The  TIBCO  Forms  Content  Assist  ability  in  Business  Studio  will  provide  you  with  the  names  of  the  functions  if  you  use  the  code-­‐completion  shortcut  ‘Ctrl+Space’.    The  control  returns  the  ID  selected  as  text  in  single  mode  or  an  array  of  ID  as  text  when  in  Multiple  mode.  

 

 Page  7  of  11  

(*1)  If  the  control  is  used  in  multiple  mode,  the  tags  representing  the  selection  can  grow  beyond  the  height  and  cover  information  in  controls  below.  

(*2)  if  you  leave  these  empty  you  need  to  pass  the  Id’s  &  Labels  though  the  corresponding  Setter  function.    

(*3)  The  availability  of  data  in  the  fixed  value  Locked  ID’s  array  or  in  the  setLockedArray()  function  forces  the  select2  box  to  preselect  and  lock  the  items.  

In  Single  Select  mode  the  locked  array  Id’s  have  no  function  and  will  not  force  an  item  to  be  locked.  

   

 

 

Solutions  –  Select2  Single  select  In  the  following  example  we  are  using  a  Select2  box  with  fixed  variables.  The  Multi  Select  option  is  set  to  false  And  the  place  holder  is  set  to  “Select  your  destination  ……”  

 

In  the  form  this  will  be  represented  by  the  following  select2  box  :  

 When  the  user  clicks  on  the  select2  box  it  will  roll  out  and  shows  the  search  box  on  top    

     

As  soon  as  the  user  start  typing  the  Selet2  box  will  search  in  the  array  and  show  the  matching  items  in  the  drop  down.  

   

Once  the  user  has  selected  a  entry  the  box  will  show  :    

 

 Page  8  of  11  

 

Solutions  –  Select2  multi  select  In  the  following  example  we  are  using  a  Select2  box  with  fixed  variables.  The  Multi  Select  option  is  set  to  true  And  the  placeholder  is  set  to  “Select  your  destination  ……”  

 In  the  form  this  will  be  represented  by  the  following  select2  box  :    

   When  the  user  clicks  on  the  select2  box  it  will  roll  out  .  

     As  soon  as  the  user  start  typing  the  Selet2  box  the  select  box  will  show  and  starts  searching  in  the  array  and  show  the  matching  items  in  the  drop  down.  

     Once  the  user  has  selected  the  entry  the  box  will  show  the  selction:  

 When  the  user  selects  a  new  entry  the  drop  down  box  will  continue  to  show  the  previous  selction  

 

 

 Page  9  of  11  

Ones  the  selection  is  completed  the  Select2  box  will  show    the  selections:      

(*)  Note  -­‐  Currently  the  selection  box  can  grow  longer,  then  the  size  set  in  properties  

Solutions  –  Select2  multi  select  with  locked    selections  In  the  following  example  we  are  using  a  Select2  box  with  fixed  variables.  The  Multi  Select  option  is  set  to  true  We  provide    two  record  in  the  locked  array  that  are  going  to  be  selected  and  locked,  And  the  placeholder  is  set  to  “Select  your  destination  ……”  

 In  the  form  this  will  be  represented  by  the  following  select2  box  :    

   When  the  user  clicks  on  the  select2  box  it  will  roll  out  and  still  show  the  locked  selections.  

       As  soon  as  the  user  start  typing  the  Selet2  box  the  select  box  will  show  and  starts  searching  in  the  array  and  show  the  matching  items  in  the  drop  down.  

       Once  the  user  has  selected  the  entry  the  box  will  show  the  selection:    

 The  user  can  only  remove  the  tag  with  the  small  x.      Searching  and  selecting  additional  items  works  as  seen    above.  

 

 Page  10  of  11  

 

Business  Studio  Form  Scripts  

Open  Form    Event  Script  loading  the  ID’s,  Labels  &  optionally  the  locked  Id’s  /** * This script is used to set the basic arrays on the Select2 object **/ control.multiselectwithLock.setIDArray(data.getID()); control.multiselectwithLock.setLabelArray(data.getNames()); // uncomment next line to lock ID’s in the select2 object //control.multiselectwithLock.setIsLockedArray(data.getLocked());

On  Update  Event  of  control  to  push  the  value  to  an  other  control  /** * This script is used to get the value from the Select2 object * on the Update Event fired by the control **/ control.result.setValue(control.multiselectwithLock.getValue());

Script  pushing    multiple  values  to  the  Select2  control  /** * This script show how to push multiple values to the control **/  var inner = data.getOthervalues();  

inner.push ("Roger Moore"); inner.push("George Lazenby"); data.setOthervalues(inner); control.multiselectwithLock.setValue(data.getOthervalues());

Script  that  can  be  used  to  Enable/Disable  the  Select2  control  /** * This script show how to toggle the Enabled state of the Select2 * control (Used here on a button called MultiSelectDisablerButton) **/  if (control.multiselectwithLock.getControl_enabled() ){ control.multiselectwithLock.setControl_enabled(false); control.multiSelectDisablerButton.setLabel("Enable"); } else { control.multiselectwithLock.setControl_enabled(true);

 

 Page  11  of  11  

control.multiSelectDisablerButton.setLabel("Disable"); }