blueshoes php application framework and cms            javascript_components
[ class tree: javascript_components ] [ index: javascript_components ] [ all elements ]

Class: Bs_Dropdown

Source Location: /components/dropdown/Bs_Dropdown.class.js.php

Class Overview


JavaScript Editable Dropdown Component.


Author(s):

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 88]
JavaScript Editable Dropdown Component.

Browsers don't offer this functionality yet (mid-2003).

Features:

  • IE6 and NS(Mozilla7) compliant.
  • Simulates a normal HTML-form text input field; so your form-hanling will not change.
  • Works over frames: Imagine you have a top frame (for a toolbar) and a main frame for the content. Now in the top frame you place a dropdown. it should go over the bottom frame; this works with this class, but not with domapi.
Includes (+Dependences):

1 <script type="text/javascript" src="/_bsJavascript/core/lang/Bs_Misc.lib.js"></script>
2 <script type="text/javascript" src="/_bsJavascript/core/lang/Bs_Array.class.js" ></script>
3 <script type="text/javascript" src="/_bsJavascript/core/form/Bs_FormUtil.lib.js"></script>
4 <script type="text/javascript" src="/_bsJavascript/core/form/Bs_FormFieldSelect.class.js"></script>
5 <script type="text/javascript" src="/_bsJavascript/core/components/Bs_Dropdown.class.js"></script>

How to use:

  1. Have a look at the example (see example link below)
  2. Create a function in the HTML-header called init(). Place the javascript code that instanciates and inits this component into init().
  3. Place an 'onLoad' in your body-tag: e.g. <body onLoad="init();">
  4. In the HTML body: Place a div- or span-tag with an unique ID where you want the componet to be.
How it works:
  • [After instanciating and initializing the object]. Call the drawInto([tag id]) methode. This will search the HTML code for a tag with the given id and insert HTML- and JS- code dynamically (using DOM) to display the component and handle it.
  • This class generates a normal HTML text input field and saves the value in there. When used in a form, it will be submitted like any other HTML-form-field.
What is returned to the server:
  +------------------------+--------------------------------------------------+
  | DropdownName +"_select"| string, What the user selected                   |
  +------------------------+--------------------------------------------------+
  | DropdownName +"_input" | string, If no changes were made, same as above;  |
  |                        | otherwise what the user filed in.                |
  +------------------------+--------------------------------------------------+

Event-Handling (see attachEvent()):

  • You can attach code or a callback function for certain events onto this component (events are things like onClick, onChange ... aso) See attachEvent() for a list of supported events and more details.
Snipit 1) Attaching a callback function:

1 var myDropDown_1 = new Bs_Dropdown();
2 myDropDown_1.attachEvent('onChange', yourCallbackFunctionName);
The function you pass should be able to receive a object as parameter. The object is an instance of this class and allows you to access it the component that triggered the event:

1 function yourCallbackFunctionName(componentObj){
2 // do some stuff.
3 }
= = = =
Snipit 2) Attaching JS code:

1 var checkBox = new Bs_Checkbox();
2 checkBox.attachOnClick("yourFunctionName('foo', 'bar'); alert('hello');");

Customized images:

  • Set the path to your image-dir imgDir
  • Following images must be created.
         arrow.gif
     




Tags:

copyright:  blueshoes.org
author:  andrej arn <at blueshoes dot org>
example:  example not found


[ Top ]


Class Variables

$autoAdd =  true

[line 106]

If set to TRUE, a new text string gets automatically added to the select list.

default is true.




Tags:

access:  public

Type:   bool


[ Top ]

$classInput =

[line 181]

Customize look. When using a CSS you may add a CSS class name that will be used when rendering the field.



Tags:

access:  public

Type:   string


[ Top ]

$classSelect =

[line 182]

Customize look. When using a CSS you may add a CSS class name that will be used when rendering the field.



Tags:

access:  public

Type:   string


[ Top ]

$disabled =  false

[line 156]

Dropdown can be disabled. then it's value cannot be changed.



Tags:

var:  (default is false)
see:  Bs_Dropdown::$guiNochange
access:  public

Type:   bool


[ Top ]

$guiNochange =

[line 165]

If set to true then the user cannot change things by clicking.

Changes through the api functions (for the coder, you) are still possible.




Tags:

see:  Bs_Dropdown::$disabled
access:  public

Type:   bool


[ Top ]

$imgDir =  '/_bsJavascript/components/dropdown/img/win2k/'

[line 174]

Directory where the images are.

Feel free to create your own images, put them into another directory (by using the same file names, etc.) See header for more info.




Tags:

access:  public

Type:   string


[ Top ]

$maxLength =

[line 134]

the max length (chars) values can have. not set means no limit.



Tags:

var:  maxLength
access:  public

Type:   int


[ Top ]

$rememberNewInCookie =

[line 119]

if you want newly added elements to be stored in a cookie so that if the page is reloaded, or the user comes back, ... the user-typed option is in the list as well. without the need to code something server-side to include the option.



Tags:

var:  rememberNewInCookie
since:  bs4.5
see:  var this.autoAdd
access:  public

Type:   string


[ Top ]

$selectOrder =  1

[line 148]

How the options in the select field should be ordered.

   1 = new options at the end (default)
   2 = new options at the begin
   3 = alphabetically descending
   4 = alphabetically ascending
 




Tags:

todo:  code support for this.
access:  public

Type:   int


[ Top ]

$_constructor =

[line 790]


Type:   mixed


[ Top ]



Class Methods


method addOption [line 325]

bool addOption( string str, bool addToCookie)

Add an option to the list.

NOTE:

  • Options will be merged case-insensitive, otherwise we'd have too much crap.




Tags:

return:  (true if it got added, false if it was already there.)
see:  Bs_Dropdown::attachEvent(), this.rememberNewInCookie
access:  public


Parameters:

string   str   str
bool   addToCookie   addToCookie (used internally only)

[ Top ]

method attachEvent [line 517]

void attachEvent( string trigger, mixed yourEvent)

Attaches an event like onChange, onMouseOver, onClickCaption ... a.s.o.

Supported events are:

  • 'onChange'




Tags:

see:  _attachedEvents
access:  public


Parameters:

string   trigger   trigger (for example 'onChange')
mixed   yourEvent   A globalFunctionName OR string of javascript to be evaled (using JS's eval())

[ Top ]

method convertField [line 483]

void convertField( string fieldId)

takes an existing html form field (of type text) and converts it into a Bs_Dropdown field.



Tags:

access:  public


Parameters:

string   fieldId   fieldId

[ Top ]

method drawInto [line 470]

void drawInto( string tagId)

Renders the dropdown component and places it into the tag specified.



Tags:

access:  public


Parameters:

string   tagId   tagId id of the tag. (Hint: use a <div> or <span>.)

[ Top ]

method fireEvent [line 546]

void fireEvent( string trigger)

Fires the events for the trigger specified.

(used internally, but feel free to trigger events yourself...)




Tags:

access:  public


Parameters:

string   trigger   trigger (for example 'onClickCaption')

[ Top ]

method getValue [line 284]

string getValue( )

Returns the current value.



Tags:

access:  public


[ Top ]

method hasEventAttached [line 535]

bool hasEventAttached( string trigger)

Tells if an event is attached for the trigger specified.



Tags:

access:  public


Parameters:

string   trigger   trigger

[ Top ]

method render [line 390]

string render( string tagId)

Renders this component (generates html code).

We added this methode to the public API for the advanced user. It's half-private :). This is a call for the advanced user, who would like to fetch the html- / js- that is rendered to make this component running.
The average user will normally use drawInto(), that will render and place the code into the site in one simple step.




Tags:

see:  Bs_Dropdown::drawInto()
access:  public


Parameters:

string   tagId   tagId (id of the tag.)

[ Top ]

method setSize [line 372]

void setSize( int value, string unit)

sets the size (width) of the fields.

you can define the width by using css classes, see this.classInput and this.classSelect. that is a safe bet. note that the width of the input field should be the one of the select field -20 (for the arrow icon). example 1 demonstrates this: http://www.blueshoes.org/_bsJavascript/components/dropdown/examples/example1.html

if you use an existing text field, and convert it, like in example 2 http://www.blueshoes.org/_bsJavascript/components/dropdown/examples/example2.html then the "size" attribute of your text field is used. note that if you use css classes, and they have a width defined, the browser ignores this "size". css is stronger.

if none of the above apply for your case, you can define the size by calling this method BEFORE rendering the dropdown. the param "value" is a number. the param "unit" can be "char" or "pixel". examples: yourObj.setSize(40, 'char') => the input field will use "size=40" as attribute. yourObj.setSize(200, 'pixel') => the select field will use a style setting of 200px. the input field has one with 180px (-20 for the arrow icon).




Tags:

access:  public


Parameters:

int   value   value
string   unit   unit

[ Top ]

method setValue [line 301]

void setValue( string value, bool addToCookie)

If you wish to change the value of this component, call this method.

If the value is not an option yet, it will be added to the options array.

NOTE:

  • Attached onChange events will *not* fire.




Tags:



Parameters:

string   value   value
bool   addToCookie   addToCookie (used internally only)

[ Top ]

method _selectFieldOnKeyDown [line 704]

void _selectFieldOnKeyDown( )

Fires on typing in the select input field.



Tags:

since:  bs4.4


[ Top ]

method _textFieldOnBlur [line 652]

void _textFieldOnBlur( )

Fires when the text input field loses focus. used internally.



Tags:

since:  bs4.4


[ Top ]

method _textFieldOnKeyDown [line 672]

void _textFieldOnKeyDown( )

Fires on typing in the text input field.



Tags:

since:  bs4.4


[ Top ]


Documentation generated on Mon, 29 Dec 2003 22:18:20 +0100 by phpDocumentor 1.2.3