| javascript_components

# Class: Bs_Checkbox Source Location: /components/checkbox/Bs_Checkbox.class.js.php
### Class Overview
A Checkbox Component. #### Author(s): andrej arn <at blueshoes dot org> #### Copyright: blueshoes.org | ### Variables $caption $checkboxName $disabled $guiNochange $imgDir $imgHeight $imgStyle $imgWidth $noPartly $useMouseover $value $_constructor | ### Methods attachOnChange attachOnClick convertField draw drawInto onClick render setTo
### 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: Have a look at the example (see example link below) Create a function in the HTML-header called init(). Place the javascript code that instanciates and inits this component into init(). Place an 'onLoad' in your body-tag: e.g. <body onLoad="init();"> 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:
see: | Bs_Checkbox::setTo(), Bs_Checkbox::attachOnClick()
access: | public
#### 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:
see: | Bs_Checkbox::setTo(), Bs_Checkbox::attachOnChange()
access: | public
#### 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:
see: | see example 2 at http://www.blueshoes.org/_bsJavascript/components/checkbox/examples/example2.html
access: | public
#### 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:
see: | Bs_Checkbox::attachOnChange(), Bs_Checkbox::attachOnClick()
access: | public
#### 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