Documentation

Document Sample
Documentation Powered By Docstoc
					 Custom Buttons² Reference Documentation




   Documentation

for Custom Buttons²

         Extension
                      Custom Buttons² Reference Documentation




                             Table of Contents
Lineage:

Menu:

     Edit Button
     Delete Button
     Disable/Enable this Button
     Clone Button
     Copy as HyperLink
     Copy as BBCodeLink
     Copy to Clipboard
     Copy Button Name
     Save this Button
     Update Button
     Bookmark Button
     Update Button
     Button's Attributes
     Button Help
     Button's HomePage

Global Objects, Handlers, and Functions

     Global Clipboard Object
     Mouse Click Event Handler
     Create Message Function
     Create Debug Function
     Button Help Usage
     Mouseover

Custom Button Options
              Custom Buttons² Reference Documentation




Lineage:
   The original extension was authored by Yan as
   custombuttons. LouCypher and deepakjoshi04 contributed
   heavily by their work with userChrome.js and the
   userChrome button including further contributions from
   cblover and SCClockDr. These concepts and the code is now
   incorporated in the extension Custom Buttons².

   I SCClockDr am currently maintaining the code and authoring
   enhancements.
                       Custom Buttons² Reference Documentation


                    Documentation for Custom Buttons²



Menu:
When installed this button gives the user the following context menu options for all
Custom Buttons:




   1. Edit Button
   2. Delete Button
   3. Disable/Enable this Button
   4. Clone Button
   5. Copy to Clipboard
   6. Copy as HyperLink
   7. Copy as BBCode link
   8. Copy Button Name
   9. Save this Button
   10. Update Button
   11. Add New Button
   12. Bookmark Button
   13. Button's Attributes
   14. Button Help
                         Custom Buttons² Reference Documentation


       15. Button's HomePage
       16. Add New Button
       17. Customize

The Context Menu comes in two parts.

  I.      The primary Context menu whose Id is “custombuttons-contextpopup”

             a. It is intended for this menu to be customizable yet in full control of the
                extension.

 II.      A Sub-Context menu whose Id is “custombuttons-contextpopup-sub”

             b. This menu is NOT intended be customizable and we ask you honor that
                intension.

The procedure for modifying the Primary Context menu is as follows:

III.      Retrieve the Menu controller object from the extension by calling:
           A. custombuttons.getCbContextObj with this statement:
                   1.   this.mObj = custombuttons.getCbContextObj(this);
                          a.   Where:
                                 1.    this.mObj is mandatory because the extension
                                       needs to access this object once it is established in
                                       your button.
                                 2.    Custombuttons is the namespace the extension
                                       operates in.
                                 3.
                                 4.    getCbContextObj is the constructor function.
                   2.   Properties:
                          a.   BtnIdNum:0,
                                 1.    Houses the Button ID number portion for easy access.
                          b.   ItemIdPre:'Cb2-',
                                 1.    MenuItem prefix.
                          c.   mCtxtSub:false,
                                 1.    true = Primary context menu is modified.
                                 2.    False = Standard behavior.
                          d.   oMenu:null,
                                 1.    Holds the Primary Context menu object.
                          e.   nMenu:null,
                                 1.    Holds the Sub-Context menu object.
                          f.   Oid:'',
                                 1.    Primary Context menu id
                          g.   nId:'',
                                 1.    SubMenu Context menu id
                          h.   OurCount:{},
     Custom Buttons² Reference Documentation


             1.   Holds an instance of the counter object
                  custombuttons.gCounter
       i.   menuitems:0,
              1.  Holds the Primary menu child count.
       j.   aElements:[],
              1.  Holds the Primary menu child collection.
      k.    listener:function(){},
              1.  Holds a listener function if you provide
                  it. The context listener in the extension
                  will call this property if this object is
                  present in the button.
              2.  This property must contain a function.
       l.   aItemIdx:['id','label','image','oncommand','com
            mand','acceltext',

                  'accesskey','allowevents','autocheck','ch
                  ecked','crop',

                  'description','disabled','key',
                  'name','tabindex','type',

                  'validate','value'],

             1.   This is the list of names used to access
                  the menuitem properties.

1.   Methods:

      a.    init( oBtn )

             1.   Sets the initial state and is called by the wrapper
                  prior to presenting the object to the caller.
             2.   Obtn is the parent button.

      a.    setSub()

             1.   Sets the Sub menu on and reduces the primary
                  menu to one Custom Buttons² item "Custom
                  Button" which invokes the subMenu. If button
                  specific Items are already in the primary menu they
                  will be presented as well.

      a.    setPri()

             1.   Resets the Primary menu and kills the SubMenu. It
                  hides any button specific Items appended to the
                  primary menu.
Custom Buttons² Reference Documentation


 a.   getItem()
       1.   Retrieves an object with named properties. Which
            the user populates with the item data specific to
            their application. Fields not populated will not alter
            the menuitem when populated. Arg. Id is
            REQUIRED and if ommitted a default will be
            substituted. the Id's structure is: "Cb2-##-
            YourID++"

       1.   Where:
              a.   ## is the button's id number.
              b.   ++ is a 0 based sequential number
       2.   Menuseparators are invoked by omitting the label
            property

 a.   insertBefore( oNew, oChildNode )

       1.   Inserts a menuitem to the primary Context menu
            before the menuitem specified in arg2. Requires the
            populated getItem Object (oNew) as an arg and a
            reference menuitem as arg 2.

 a.   insertAfter( oNew, oChildNode )

       1.   Inserts a menuitem to the primary Context menu
            after the menuitem specified in arg2. Requires the
            populated getItem Object as an arg and a reference
            menuitem as arg 2.

 a.   addItem( oNew )

       1.   Prepends a menuitem to the primary Context menu.
            Requires the populated getItem Object as an arg.

 a.   populate( oData, mItem )

       1.   Populates the menuitem (mItem) with the data
            supplied (oData).

 a.   getItemsById( id )

       1.   Returns the menu element specified by (id).

 a.   RemItem( id )
                          Custom Buttons² Reference Documentation


                                 1.   Removes the specified item (by id) from the
                                      Primary Context Menu.
                                 2.   If id is null or not passed, ALL items associated
                                      with the button will be removed.
        B.     How It is used:
this.mObj = custombuttons.getCbContextObj(this);


       This sets up the menu object and initializes it.
x.mObj.listener = function(x){x.getIndex();};


       This establishes a listener function ( Optional ).
x.mObj.setSub();


       This tells custombuttons to implement the sub-menu.
var nItem = {};


       This this will contain the item to be submitted to add/insert methods.
var mItem = {};


       This this will contain the item returned by the add/insert methods.
document.getElementById(CB2const.sCBCtxtMenu).setAttribute("oncommand",
"event.stopPropagation()");


       This stops event propagation to avoid unintended behavior.



       These next statements can be placed in a loop for implementing several
       menuitems.
nItem = new x.mObj.getItem();


       This sets up nItem to populate with the data we wish.
nItem.id = 'MyId';

nItem.label = My Label;

nItem.value = 'Some Data';

nItem.checked = false;


       Here we set some attributes for the menuitem.
mItem = x.mObj.insertBefore( nItem , x.mObj.oMenu.lastChild);
                       Custom Buttons² Reference Documentation


       This will insert a new menuitem before the last child. Mitem will be a different
       object than nItem.
mItem.setAttribute( 'oncommand','document.popupNode.setIndex(this);' )


       Due to scoping this must be setup here and not within the object. Arg2 is whatever
       you need to implement.
mItem.setAttribute( 'type','checkbox')

mItem.setAttribute( 'checked',false)

mItem.setAttribute( 'autocheck',false )


       Here we set some attributes directly.



       Now to create and insert a separator.
x.mObj.getItem();

nItem = x.mObj.getItem();

nItem.id = 'Note';

this.separator = x.mObj.insertBefore( nItem , x.mObj.oMenu.lastChild);.


              Note we did not set the label with anything.

That completes the setup. Now the extension will do the rest.

        B.    Why go to all this trouble?
               1.   Custombuttons provides a means to disable a button via it's context
                    menu. When the button is disabled the menu should not provide
                    the normal options because the button is disabled.
               2.   When authors implemented their own context manipulation they
                    usually modified the context menu's id. From that point on the
                    extension looses control of it's menu and can no longer disable its
                    menuitems when the button is disabled.
               3.   Also this implements more consistency in button behavior.



Edit Button
                     Custom Buttons² Reference Documentation


     The Edit Button option opens the custombuttons edit dialog. Allowing the author
     to edit the code that controls the button's function.



     The Code Field contains code that executes on a left click by default. Pressing F9
     while in this field caused the code to execute and focus to return to the Edit dialog
     when the execution is complete.



     The Initialization code field contains code that executes on button initialization
     and on mouse clicks when an on click handler is specified.

Delete Button



     The Delete Button option Removes the button from localstore.rdf and
     buttonsoverlay.xul.

Disable/Enable this Button



     The Disable/Enable this Button option toggles the active state of the button, sets
     the opacity to 0.3, prevents focus, and toggles context menu options.

Clone Button



     The Clone Button option clones the target button and positions the clone to the
     right on the same toolbar. All attributes are duplicated with the exception of the
     button.id

Copy as HyperLink



     The Copy as HyperLink option places a html custombutton URL and places it in
     the system clipboard

Copy as BBCodeLink
                     Custom Buttons² Reference Documentation


     The Copy as BBCodeLink option creates a BBCode tagged custombutton URL
     and places it in the system clipboard.

Copy to Clipboard



     The Copy to Clipboard option creates a custombutton URL and places it in the
     system clipboard.

Copy Button Name



     The Copy Button Name option places button label, version, and status in the
     system clipboard.

Save this Button



     The Save this Button option creates an HTML page containing the button's
     HyperLink information and various Attributes.



Update Button



     The Update Button option inserts new parameters into the target button which are
     in the clipboard. All 4 fields are replaced and the copied link need not be the same
     button as the target.



Bookmark Button



     The Bookmark Button creates a bookmark of the target button



Update Button
                      Custom Buttons² Reference Documentation




      The Update Button option inserts new parameters into the target button which are
      in the clipboard. All 4 fields are replaced and the copied link need not be the same
      button as the target.



Button's Attributes



      The Button's Attributes option displays a dialog containing the button's Attributes
      information and, also, places the information on the Windows System Clipboard.




Button Help



      The Button Help option displays a dialog containing the Button's help Attribute
      information.
                       Custom Buttons² Reference Documentation




Button's HomePage

        The Button's HomePage option directs the browser to the URL contained in the
        homepage Attribute.




Global Objects, Handlers, and Functions
Global Clipboard Object

Property

sRead is an array container to house internal clipboard like data.

Methods

   1.   gClipboard.write(str) stuffs the system clipboard with the argument str
   2.   gClipboard.read returns the contents of the system clipboard
   3.   gClipboard.clear stuffs the system clipboard with “”
   4.   gClipboard.Write(str) stuffs the internal clipboard with the argument str
   5.   gClipboard.Read returns the contents of the internal clipboard

        This Object can be instanced but there remains one and only one system
        clipboard; var myClipBoard = new Object(gClipboard); is an example of this
        object being instanced.
                      Custom Buttons² Reference Documentation



Mouse Click Event Handler

     gQuot = function(evt, cButton)

     Args: evt - Mouse click event used to direct code execution based on the button
     clicked and any extra state keys held during the event.

     cButton - Object of the calling button used to appropriately locate the context
     menu.

     Returns: Nothing.

     How this works: On a click the calling button is strobed via the
     this.setAttribute("onclick", "gQuot(event, this);"); statement in the button's
     Initialization Code section. This passes the event and button object (this) to the
     event handler.

     Execution:

  1. Execution proceeds to check for a click event function presence in the calling
     button.
         a. Testing progresses down the tree till it arrives at a function with no extra
             key qualifier.
         b. The first found function is called within the calling button. It passes the
             event object to the called function to provide the button author with the
             event object for further processing.
  2. If no matches are found then gShowPopup(cButton) is called passing it the button
     object.

     Calls:

              Ctrl+LeftClick example:



  1. cButton.cleftclick(evt) calls the button object function cleftclick. It passes the click
     event object to the button and expects nothing in return.
  2. When control returns to gQuot function, program flow will encounter a break and
     the function exits to the button's calling attribute "onclick" statement.
  3. Handling of the event is now complete.
                       Custom Buttons² Reference Documentation



Create Message Function



      createMsg = function(title)



      Args: title - Optional

      Returns: New Message Object with title property initialized if provided.



      How this works: createMsg uses the Object constructor method to create an object
      Msg

Properties:

   1. prompts
   2. check
   3. sTitle

Methods:

      Msg.aMsg(str,title)

              1. arg - str is the passed message string
              2. arg - title is the optional dialog title



      Calls: this.prompts.confirmEx();



      Setup: MyObj = createMsg(['title']);



      Use: MyObj.aMsg('a message here'); // Display message



      Example :
Custom Buttons² Reference Documentation
                       Custom Buttons² Reference Documentation



Create Debug Function



      createDebug = function(bttn)



      Args: bttn - Button Object

      Returns: New Message Object for Debugging.



      How this works: createDebug uses the Object constructor method to create an
      object gMsg



Properties:

   1. prompts : Mozilla container for confirmex service
   2. strs : String Array()
   3. sdebug : Debug Title - ' ---------- DE-BUG MESSAGE ----------\n\n',
   4. swarn : Warning Title - ' +++++ WARNING +++++\n\n',
   5. strerr : Error Array
   6. sVer : Holds Button version Attribute data.
   7. check : Object with value property : boolean. Used by Mozilla service.
   8. bugon : Object with value property : boolean. True = DeBug is on.
   9. bugonlp : Object with value property : boolean. True = DeBug loop is on.
   10. Func : Holds function name if set.
   11. Name : Holds Button label if set.

Methods:

   1. finit : function(btn)

      arg - btn is the passed button Object

      task - Initialize the object with Button version & label data

      returns - Nothing
                    Custom Buttons² Reference Documentation


2. setErr : function (estr)

   arg - estr is the passed message string

   task - push new error string into the error string array

   returns - index number to the passed error string



3. bug : function (str)

   arg - str is the passed message string

   task - Display Debug dialog with the passed message.

   Forces bugonlp to true so next loop will be debugged.

    Toggle off debug mode if requested by operator.
   returns – Nothing
                   Custom Buttons² Reference Documentation



4. bugloop : function (str)

   arg - str is the passed message string

   task - Display loop Debug dialog with the passed message.

   Requires bugon & bugonlp to be true for the dialog to display.

   Toggle off either debug mode or debug loop mode if requested by operator.

   returns – Nothing




4. warn : function (str)

   arg - str is the passed message string

   task - Display Warning dialog with the passed message.

   Can be used to warn the operator of conditions

   you the programmer wish to inform the operator about.

   Can be used with try/catch to display caught errors.

   returns – Nothing
                      Custom Buttons² Reference Documentation




   4. err : function (nerr)

       arg - nerr is the passed error message number

       task - Display Error dialog with the numbered error message.

       Can be used to warn the operator of conditions

       you the programmer wish to inform the operator about

       using a numbered error system.

       returns - Nothing




Calls: this.prompts.confirmEx();



       Setup & Use:

       de = createDebug(bttn);
                Custom Buttons² Reference Documentation


de.bug('My test');

loop {de.bugloop('My Loop Test');}



The following if Warning stuff wanted:

de.warn('Some Warning');



The following if Error stuff wanted:

var errNum = de.seterr('error string') // repeat as necessary

if (some error) {de.err(4)} // would display error # 4 message
                       Custom Buttons² Reference Documentation



Button Help Usage:

     The structure of the help attribute is “n,test,n+1,text” & so on.
     The uChelpButton function splits the help attribute string into array elements &
      then accesses the second element to display the text string if it exists.
     This construct allows for the implementation of a context sensitive or structured
      help system within your button code.
     For events where the developer wants specific help all that is needed is to retrieve
      the attribute string.
     Split it into array elements.
     Perform an indexOf method on the array specifying the index No. such as:

      var astr = this.getAttribute('help').split(',');

      alert(astr[astr.indexOf('3')+1]); // the arg for indexOf is a string numeral.

     Would display the string associated with index 3.
     If the help Attribute is missing or a zero length string then a default message is
      displayed for the “Button Help” CB context menu item.

Mouseover:

      Two methods are provided for implementing a mouseover effect.

     ButtonBrt( e )
     ButtonDim( e )

      If these methods are used they will toggle the button's opacity between 0.65
      standard level and 0.99 during mouseover.


Custom Button Options:
       A.     Editor Dialog Options:
               1.    Editor Apply Button
                           Un-checked will omit the apply button from the editor
                            dialog
                           Checked will present an apply button on the lower left of
                            the editor dialog. Which will apply any changes made since
                            the lase apply and not close the dialog.
                                   For Add New Button each apply will create a new
                                    button.
       B.     New Button Creation Options:
               1.    Add New Button Behavior
                       Custom Buttons² Reference Documentation


                             Un-checked will prevent the following button options from
                              being applied.
                           Checked will open the following button options to be
                              applied.
                2.    Mouse Click Handler Functions
                           Un-checked will omit the mouse click handler functions
                              from new buttons when created..
                           Checked will add the mouse click handler functions to new
                              buttons when created
                3.    Show Focus Attributes
                           Un-checked will omit the mouse over/out functions from
                              new buttons when created..
                           Checked will add the mouse over/out functions to new
                              buttons when created
                4.    Documentation Attributes
                           Un-checked will omit Attribute documentation from new
                              buttons when created..
                           Checked will add Attribute documentation to new buttons
                              when created
                5.    Debug Alert Object
                           Un-checked will omit the Debug Alert Object from new
                              buttons when created..
                           Checked will add the Debug Alert Objec to new buttons
                              when created
        C.     Tool Tip Options:
                1.    Include Buttton ID Number in ToolTip
                           Un-checked, the button id number will be omitted from the
                              default tooltip.
                           Checked, the button id number will be inserted into the
                              default tooltip.
        D.     Button Attribute Data
                1.    Specify the default strings you wish to be inserted into a new
                      button when it is created from the Add new Button menu item.
                          0. Default Author
                          1. Button Dependancies
                          2. Default Development Status
                          3. Public Button
                          4. Button Help Text

This is still a work in progress so please feel free to post additions, corrections or
suggestions to the extension support forum.

				
DOCUMENT INFO
Shared By:
Categories:
Tags:
Stats:
views:18
posted:3/30/2012
language:
pages:23