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

Class: Bs_Checkbox

Source Location: /components/checkbox/Bs_Checkbox.class.js.php

Class Overview


A Checkbox Component.


Author(s):

Copyright:

  • blueshoes.org

Variables

Methods


Inherited Variables

Inherited Methods


Class Details

[line 90]
A Checkbox Component.

Features:

  • IE6 and NS(Mozilla7) compliant.
  • Simulates a normal HTML-form checkbox; so your form-hanling will not change.
  • Uses images for the checkbox. (You may use your customized images).
  • Able to deactivate a checkbox, thus visible but not changeable (by the user).
  • Can have 3 states: 'Checked', 'Not Checked' AND 'Partly Checked'
  • Able to attach onClick- and onChange-events to execute your JS-code when chicked/changed.
  • Able to have rollover effects.
Includes (+Dependences):

1 <script type="text/javascript" src="/_bsJavascript/core/lang/Bs_Misc.lib.js"></script>
2 <script type="text/javascript" src="/_bsJavascript/components/checkbox/Bs_Checkbox.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 checkbox input field and saves it's state in there. It's not visible because it is set to display:none (invisible) but (when used in a form) will be submitted like any other HTML-form-field.
  • Note: HTML checkboxs that have a value of 0 are not returned to the browser.
What is returned to the server:
  +----------------------+----------------------------------------------------+
  | checkboxName         | int, 1 or 2 (0 is not returned, assume not checked)|
  +----------------------+----------------------------------------------------+

Event-Handling: (see attachOnClick(), attachOnChange())

  • You can attach code or a callback function for certain events onto this component (events are things like onClick, onChange ... aso)
Snippet 1) Attaching a callback function:

1 var checkBox = new Bs_Checkbox();
2 checkBox.attachOnClick(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 }
= = = =
Snippet 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. The numbers stand for 0(= not checked), 1(=partly) or 2(=completely).
       Disabled GIFs:
         disable_0.gif,disable_1.gif, disable_2.gif  ()
       Enabled GIFs:
         enable_0.gif,enable_1.gif, enable_2.gif  ()
       Rollover GIFs:
         enable_0_over.gif,enable_1_over.gif, enable_2_over.gif
     




Tags:

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


[ Top ]


Class Variables

$caption =

[line 176]

if a caption is used then it will be clickable (if the checkbox is not disabled).

currently you can assign any html value, examples:

   yourObj.caption = "foobar";
   yourObj.caption = "<span id='foobar' class='foobar'>foobar</span>";
 
so you can hack in styles etc. this may change in the future, a text string only would be cleaner.




Tags:

access:  public

Type:   string


[ Top ]

$checkboxName =

[line 126]

When submitting the form, you'll receive the checkbox value under this name.

In other words you'll receive the data back to the server as if you had placed


1 <input type=checkbox name="[the checkboxName]" id="[the checkboxName]" value="[the value]">

into your HTML-form. If you omit setting the checkboxName it will be genarated as follows:

checkboxName = "checkbox" + tag-Id




Tags:

access:  public

Type:   string


[ Top ]

$disabled =  false

[line 152]

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



Tags:

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

Type:   bool


[ Top ]

$guiNochange =  false

[line 160]

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:

var:  guiNochange
see:  Bs_Checkbox::$disabled
access:  public

Type:   bool


[ Top ]

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

[line 185]

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 ]

$imgHeight =  '20'

[line 197]



Tags:

var:  image hight
access:  public

Type:   string


[ Top ]

$imgStyle =  ''

[line 203]



Tags:

var:  image style (css style string)
access:  public

Type:   string


[ Top ]

$imgWidth =  '20'

[line 191]



Tags:

var:  image width
access:  public

Type:   string


[ Top ]

$noPartly =  false

[line 145]

if set to true then the 'partly' thing won't be used, thus a value of 1 is treated like 2.



Tags:

since:  bs4.3
see:  Bs_Checkbox::$value
access:  public

Type:   mixed


[ Top ]

$useMouseover =  false

[line 219]

you may use the built in onMouseOver event to switch the icon.

NOTE:

  • if you use this one, it's wise to create all icons, even those which are never used. consider just using spacer-gif's for them. because if an icon does not exist, the server returns a 404 not found. and then the client (the users browser) goes and re-requests those files again and again, on each click (checkbox status change), to see if they're now available, even if never used. btw, i'm speaking of the "partly checked" icons.




Tags:

access:  public

Type:   bool


[ Top ]

$value =  0

[line 137]

checkbox checked?

 0 = no
 1 = partly
 2 = completely
 




Tags:

var:  (default is 0)
access:  public

Type:   int


[ Top ]

$_constructor =

[line 527]


Type:   mixed


[ Top ]



Class Methods


method attachOnChange [line 475]

void attachOnChange( mixed globalFunctionName)

Attaches an onChange event. (currently overwrites any previosly attached function)

This one fires after onClick() AND setTo().




Tags:



Parameters:

mixed   globalFunctionName   A globalFunctionName OR string of javascript to be evaled (using JS's eval())

[ Top ]

method attachOnClick [line 461]

void attachOnClick( mixed globalFunctionName)

Attaches an onClick event. (currently overwrites any previosly attached function)

This one fires after onClick().




Tags:



Parameters:

mixed   globalFunctionName   A globalFunctionName OR string of javascript to be evaled (using JS's eval())

[ Top ]

method convertField [line 360]

void convertField( string fieldId)

converts an existing standard checkbox field into a Bs_Checkbox field on the fly.



Tags:



Parameters:

string   fieldId   fieldId (the id of the checkbox field)

[ Top ]

method draw [line 332]

void draw( string tagId)

DEPRECATED.

Use drawInto()




Tags:

see:  Bs_Checkbox::drawInto()
deprecated:  use drawInto()


Parameters:

string   tagId   tagId (id of the span tag.)

[ Top ]

method drawInto [line 318]

void drawInto( string tagId)

Renders the checkbox 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 onClick [line 406]

void onClick( )

Fires on an onclick event you'd better use setTo().

We added this method to the public API for the advanced user. It's half-private :).




Tags:

see:  Bs_Checkbox::setTo()
access:  public


[ Top ]

method render [line 263]

string render( string tagId)

Renders this compnent (generates html code).

We added this method 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_Checkbox::drawInto()
access:  public


Parameters:

string   tagId   tagId (id of the tag.)

[ Top ]

method setTo [line 442]

void setTo( int value, bool cancelEventOnChange)

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

The value will be changed AND redrawn, showing the new state/data. Usfull for other JS-code (tree-like structure of checkboxes, ya know...)

NOTE:

  • attached attachOnChange() event will fire but *not* the attachOnClick() event.




Tags:



Parameters:

int   value   value (0, 1 or 2)
bool   cancelEventOnChange   cancelEventOnChange (set this to true if you don't want the eventOnChange to fire.)

[ Top ]


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