Class QControlBase
QControlBase is the base class of all QControls and shares their common properties.
Not every control will utilize every single one of these properties.
All Controls must implement the following abstract functions:
A QControl conceptually is an object in an html form that manages data or that can be controlled via PHP. In the early days of the internet, this was simply an html input or select tag that was submitted via a POST. As the internet has evolved, so has QControl, but its basic idea is the same. Its an object on the screen that you would like to either control from PHP, or receive information from. The parts of a QControl that are sent to the browser are: - The base tag and its contents, as returned by GetControlHtml(). This would be an Input tag, or a Button, or even just a div. Many Javascript widget libraries will take a div and add to it to create a control. The tag will include an id in all cases. If you do not assign one, a unique id will be created automatically. - An optional Name, often sent to the browser in a Label tag. - Optional instructions - Optional validation error text - Optional Javascript attached to the control as part of its inherint functionality, or to control settable options that are handled by a jQuery wrapper function of some kind. - Optional Javascript attached to the control through the AddActions mechanism.
You control how these parts are rendered by implementing Render* methods in your own QControl class. Some basic ones are included in this class for you to start with.
Depending on the control, and the implementation, the control might need or want to be rendered with a wrapper tag, which is controlled by the blnUseWrapper member. For example, if you want to have a form object with a name, instructions and error text, a wrapper might be needed to make sure all these parts redraw when something changes in the control. Bootstrap's formObjectGroup is an example of a control that would have all these parts. Also, if you know that a javascript widget library is going to wrap your html in additional html, you should include a wrapper here so the additional html is included inside your wrapper, and thus the entire control will get redrawn on a refresh (jQueryUI's Dialog is an example of this kind of widget.)
QControls are part of a tree type hierarchy, whose parent can either be a QForm, or another QControl.
The QControl system is designed to manage the process of redrawing a control automatically when something about the control changes. You can force a redraw by using the Refresh command from outside of a control, or by setting the blnModified member variable from a subclass. You can also use the QWatcher mechanism to automatically redraw when something in the database changes.
QControls are the base objects for actions to be attached to events. When attaching actions to multiple objects of the same type, considering attaching the event to a parent object and using event delegation for your action, as it can be more efficient in certain cases.
QControls can trigger validation and are part of the validation system. QControls that are not Enabled or not Visible will not go through the form's Validation routine.
Controls can be made visible using either the Visible or Display PHP parameters. Both are booleans. - Setting Visible to false completely removes the control from the DOM, leaving either just its wrapper or a an invisible span stub in its place. When the control is made visible again, it is entirely redrawn. - Setting Display to false leaves the control in the DOM, but simply sets its display property to 'none' in CSS. Show and hide are much faster.
- QBaseClass
- QHtmlAttributeManagerBase
- QHtmlAttributeManager
- QControlBase
Direct known subclasses
QControlIndirect known subclasses
CalculatorWidget, MyControl, QActionControl, QResizable, QResizableBase, QResizableGen, QSampleControl, QSelectable, QSelectableBase, QSelectableGen, QSelectMenu, QSelectMenuBase, QSelectMenuGen, QAutocomplete, QSlider, QSliderBase, QSliderGen, QSortable, QSortableBase, QSortableGen, QSpinner, QSpinnerBase, QSpinnerGen, QTabs, QAutocompleteBase, QTabsBase, QTabsGen, QTestControl, QTextBox, QTextBoxBase, QTreeNav, QUrlTextBox, QWaitIcon, QWriteBox, RecordsSummary, QAutocompleteGen, SampleComposite, SelectableLabel, QBlockControl, QButton, QButtonBase, QCalendar, QCheckBox, QCheckBoxList, NavPanel, QControlLabel, QControlProxy, QCsvTextBox, QDataGrid, QDataGridBase, QDataGridLegacy, QDataGridLegacyBase, QDataGridLegacyRow, QDataRepeater, QDatepicker, PersonEditPanel, QDatepickerBase, QDatepickerBox, QDatepickerBoxBase, QDatepickerBoxGen, QDatepickerGen, QDateTimePicker, QDateTimeTextBox, QDialog, QDialogBase, QDialogBox, ProjectEditPanel, QDialogGen, QDraggable, QDraggableBase, QDraggableGen, QDroppable, QDroppableBase, QDroppableGen, QEmailTextBox, QFieldset, QFileAsset, ProjectPickerListBox, QFileAssetBase, QFileAssetDialog, QFileControl, QFloatTextBox, QHListControl, QHtmlTable, QHtmlTableBase, QImageBase, QImageBrowser, QImageBrowserBase, ProjectViewPanel, QImageBrowserNav, QImageBrowserThumbnails, QImageButton, QImageControl, QImageControlBase, QImageFileAsset, QImageLabel, QImageLabelBase, QImageRollover, QIntegerTextBox, QAccordion, QJqButton, QJqButtonBase, QJqButtonGen, QJqCheckBox, QJqCheckBoxBase, QJqCheckBoxGen, QJqRadioButton, QJqRadioButtonBase, QJqRadioButtonGen, QJsTimer, QAccordionBase, QJsTimerBase, QLabel, QLinkButton, QListBox, QListBoxBase, QListControl, QMenu, QMenuBase, QMenuGen, QModelConnectorEditDlg, QAccordionGen, QNumericTextBox, QPaginatedControl, QPaginator, QPaginatorBase, QPanel, QProgressbar, QProgressbarBase, QProgressbarGen, QRadioButton, QRadioButtonList
public
|
#
__construct(
Creates a QControlBase object This constructor will generally not be used to create a QControlBase object. Instead it is used by the classes which extend the class. Only the parent object parameter is required. If the option strControlId parameter is not used, QCubed will generate the id. |
abstract public
|
|
abstract public
boolean
|
|
public
|
#
_WriteState( )
Save the state of the control to restore it later, so that if the user comes back to this page, the control will be in the showing the same thing. Subclasses should put minimally important information into the state that is needed to restore the state later. |
public
|
|
protected
mixed
|
|
protected
|
|
public
|
|
public
|
#
GetTemplatePath( $strTemplate )
A utility function to convert a template file name into a full path. |
public
string
|
#
EvaluateTemplate( string $strTemplate )
This function evaluates a template and is used by a variety of controls. It is similar to the function found in the QForm, but recreated here so that the "$this" in the template will be the control, instead of the form, and the protected members of the control are available to draw directly. |
public static
mixed
|
#
_ProcessActionParams(
This function passes control of action parameter processing to the control that caused the action, so that the control can further process the action parameters. It also saves additional information in the returned parameter array. This is useful for widgets that need to pass more information to the action than just a simple string, and allows actions to get more information as well. This also allows widgets to modify the action parameter, while preserving the original action parameter so that the action can see both. |
protected
mixed
|
#
ProcessActionParameters(
Breaks down the action parameter if needed to more useful information. Subclasses should override, call the parent, and then modify the "param" item in the returned array if needed. This also provides additional information to the action about the triggering control. |
public static
|
#
_CallActionMethod(
Used by the QForm engine to call the method in the control, allowing the method to be a protected method. |
public
|
|
public
|
|
public static
mixed
|
#
SleepHelper(
A helper function to fix up a 'callable', a formObj, or any other object that we would like to represent in the serialized stream differently than the default. If a QControl, make sure this isn't the only instance of the control in the stream, or have some other way to serialize the control. |
public static
mixed
|
#
WakeupHelper(
A helper function to restore something possibly serialized with SleepHelper. |
public
|
|
public
|
|
public
|
|
public
|
|
public
|
#
RemoveChildControl( string $strControlId, boolean $blnRemoveFromForm )
Removes the child control with the given id |
public
|
|
public
|
|
public
|
|
public
|
#
GetAllActions( string $strEventType, string $strActionType = null )
Returns all actions that are connected with specific events |
public
|
|
public
string
|
|
public
|
|
public
|
#
SetCustomStyle( string $strName, string $strValue )
Adds a custom style property/value to the html style attribute |
public
string
|
|
public
|
|
public
|
#
AddJavascriptFile( string $strJsFileName )
Add javascript file to be included in the form. The include mechanism will take care of duplicates, and also change the given URL in the following ways: - If the file name begins with 'http', it will use it directly as a URL - If the file name begins with '/', the url will be relative to DOCROOT . VIRTUAL_DIRECTORY - If the file name begins with anything else, the url will be relative to JS_ASSETS |
public
|
#
AddPluginJavascriptFile( string $strPluginName, string $strJsFileName )
Add javascript file to be included from a plugin. Plugins should use this function instead of AddJavascriptFile. The include mechanism will take care of duplicates, and also change the given URL in the following ways: - If the file name begins with 'http', it will use it directly as a URL - If the file name begins with '/', the url will be relative to the DOCROOT . VIRTUAL_DIRECTORY directory. - If the file name begins with anything else, the url will be relative to PLUGIN_ASSETS/pluginName/js/ |
public
|
#
AddCssFile( string $strCssFileName )
Add style sheet file to be included in the form. The include mechanism will take care of duplicates, and also change the given URL in the following ways: - If the file name begins with 'http', it will use it directly as a URL - If the file name begins with '/', the url will be relative to the _DOCROOT . VIRTUAL_DIRECTORY - If the file name begins with anything else, the url will be relative to CSS_ASSETS |
public
|
#
AddPluginCssFile( string $strPluginName, string $strCssFileName )
Add style sheet file to be included from a plugin. Plugins should use this function instead of AddCssFile. The include mechanism will take care of duplicates, and also change the given URL in the following ways: - If the file name begins with 'http', it will use it directly as a URL - If the file name begins with '/', the url will be relative to the PLUGIN_ASSETS directory. - If the file name begins with anything else, the url will be relative to PLUGIN_ASSETS/pluginName/css/ |
public
string
|
|
public
string
|
|
public
string
|
#
RenderHtmlAttributes( null|string $attributeOverrides = null, null|string $styleOverrides = null )
Returns the html for the attributes for the base control of the QControl. Allows the given arrays to override the attributes and styles before rendering. This inserts the control id into the rendering of the tag. |
public
string
|
|
public
null|string
|
|
public
string
|
|
public
null|
|
|
public
|
|
public
|
|
protected
string
|
#
GetWrapperStyleAttributes( boolean $blnIsBlockElement = false )
Returns all wrapper-style-attributes Similar to GetStyleAttributes, but specifically for CSS name/value pairs that will render within a "wrapper's" HTML "style" attribute |
public
string
|
#
RenderCssStyles( null $styleOverrides = null )
Overrides the default CSS renderer in order to deal with a special situation: Since there is the possibility of a wrapper, we have to delegate certain CSS properties to the wrapper so that the whole control gets those properties. Those are mostly positioning properties. In this override, we detect when we do NOT have a wrapper, and therefore have to copy the positioning properties from the wrapper styler down to the control itself. |
protected
string
|
#
GetWrapperAttributes( array $attributeOverrides = null )
Returns an array of the wrapper attributes to be used for drawing, including CSS styles. Makes sure the control is hidden if display is off. |
protected
string
|
#
RenderWrappedOutput( $strOutput, $blnForceAsBlockElement = false )
Renders the given output with the current wrapper. |
protected
|
#
RenderHelper( mixed $mixParameterArray, string $strRenderMethod )
RenderHelper should be called from all "Render" functions FIRST in order to check for and perform attribute overrides (if any). All render methods should take in an optional first boolean parameter blnDisplayOutput (default to true), and then any number of attribute overrides. Any "Render" method (e.g. Render, RenderWithName, RenderWithError) should call the RenderHelper FIRST in order to:
Proper usage within the first line of any Render() method is: $this->RenderHelper(func_get_args(), __FUNCTION__); See QControl::RenderWithName() as example. |
protected
|
|
public
|
|
public
|
|
public
|
|
public
string
|
#
GetEndScript( )
Returns and fires the JavaScript that is associated with this control. The html for the control will have already been rendered, so refer to the html object with "\$j(#{$this->ControlId})". You should do the following: - Return any script that attaches a JavaScript widget to the the html control. - Use functions like ExecuteControlCommand to fire commands to execute AFTER all controls have been attached. |
public
|
#
RenderAttributeScripts( )
Return one-time scripts associated with the control. Called by the form during an ajax draw only if the entire control was not rendered. |
public
|
#
AddAttributeScript( string $strMethod, string $args )
Executes a java script associated with the control. These scripts are specifically for the purpose of changing some attribute of the control that would also be taken care of during a refresh of the entire control. The script will only be executed in ajax if the entire control is not redrawn. |
public
|
#
GetEndHtml( )
For any HTML code that needs to be rendered at the END of the QForm when this control is INITIALLY rendered. |
public
|
|
protected
string
|
#
RenderOutput( string $strOutput, boolean $blnDisplayOutput, $blnForceAsBlockElement = false )
RenderOutput should be the last call in your custom RenderMethod. It is responsible for the following: - Creating the wrapper if you are using a wrapper, or - Possibly creating a dummy control if not using a wrapper and the control is hidden. - Generating the control's output in one of 3 ways: - Generate straight html if drawing the control as part of a complete page refresh - Generate straight html if in an ajax call, but a parent is getting redrawn, which requires this whole control to get drawn - If in an ajax call and we are the top level control getting drawn, then generate special code that out javascript will read and put into the control's spot on the page. Requires coordination with the code in qcubed.js. |
abstract protected
string
|
#
GetControlHtml( )
This method will render the control, itself, and will return the rendered HTML as a string |
public
string
|
#
Render( boolean $blnDisplayOutput = true /* ... */ )
This render method is the most basic render-method available. It will perform attribute overiding (if any) and will either display the rendered HTML (if blnDisplayOutput is true, which it is by default), or it will return the rendered HTML as a string. |
public
array[]
|
#
RenderAjax( )
RenderAjax will be called during an Ajax rendering of the controls. Every control gets called. Each control is responsible for rendering itself. Some objects automatically render their child objects, and some don't, so we detect whether the parent is being rendered, and assume the parent is taking care of rendering for us if so. |
public
boolean
|
|
protected
string
|
|
public
string
|
#
RenderWithError( boolean $blnDisplayOutput = true )
This render method will render the control with additional output of any validation errors, that might occur |
public
string
|
|
public
string
|
|
public
mixed
|
#
RenderExtensionRenderer( $classname, $methodname, array $args = array() )
Helper method to render the control using some other class/method. |
public
boolean
|
#
ValidateControlAndChildren( )
Validate self + child controls. Controls must mark themselves modified, or somehow redraw themselves if by failing the validation, they change their visual look in some way (like by adding warning text, turning red, etc.) |
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
|
|
public
mixed
|
|
public
string
|
#
GetJqControlId( )
Used by jQuery UI wrapper controls to find the element on which to apply the jQuery function |
public
|
|
public
|
#
MakeCurrent( )
Make this control current as of the latest changes so that it will not refresh on the next draw. |
public
boolean
|
#
IsDescendantOf( $objControl )
Returns true if the given control is anywhere in the parent hierarchy of this control. |
public
null|
|
#
GetControlFromHierarchyByMethodName( string $strMethodName, boolean $blnIncludeCurrentControl = true )
Searches the control and it's hierarchy to see if a method by given name exists. This method searches only in the current control and its parents and so on. It will not search for the method in any siblings at any stage in the process. |
public
|
|
public
mixed
|
|
public
mixed|
|
|
public static
|
#
GetModelConnectorParams( )
Returns a description of the options available to modify by the designer for the code generator. |
OverrideAttributes(),
__call()
|
string |
CommentStart
|
#
'Begin'
|
string |
CommentEnd
|
#
'End'
|
protected
|
$objWrapperStyler
|
#
null
|
protected
mixed
|
$mixCausesValidation
Controls how this control will effect the validation system |
#
false
|
protected
boolean
|
$blnRequired
Is it mandatory for the control to receive data on a POST back for the control to be called valid? |
#
false
|
protected
integer
|
$strValidationError
Tab-index |
#
null
|
protected
boolean
|
$blnVisible
Should the control be visible or not (it normally effects whether Render method will be called or not) |
#
true
|
protected
boolean
|
$blnDisplay
should the control be displayed? |
#
true
|
protected
string
|
$strPreferredRenderMethod
Preferred method to be used for rendering e.g. Render, RenderWithName, RenderWithError |
#
'Render'
|
protected
string
|
$strHtmlBefore
HTML to rendered before the actual control |
#
null
|
protected
string
|
$strHtmlAfter
HTML to rendered after the actual control |
#
null
|
protected
string
|
$strInstructions
the Instructions for the control (useful for controls used in data entry) |
#
null
|
protected
string
|
$strWarning
Same as validation error message but is supposed to contain custom messages |
#
null
|
protected
|
$objDraggable
When initialized, it implements the jQuery UI Draggable capabilities on to this control. |
#
null
|
protected
|
$objResizable
When initialized, it implements the jQuery UI Resizable capabilities on to this control. |
#
null
|
protected
|
$objDroppable
When initialized, it implements the jQuery UI Droppable capabilities on to this control. |
#
null
|
protected
null|string
|
$strControlId
The control ID of this control. Used to represent the control internally and used for the HTML 'id' attribute on the control. |
|
protected
|
$objForm
Redundant copy of the global $_FORM variable. |
#
null
|
protected
|
$objParentControl
Immediate parent of this control |
#
null
|
protected
|
$objChildControlArray
Controls which have this control as their parent |
#
array()
|
protected
string|null
|
$strName
Name of the control - used as a lable for the control when RenderWithName is used to render |
#
null
|
protected
boolean
|
$blnRendered
Has the control already been rendered? |
#
false
|
protected
boolean
|
$blnRendering
Is the control mid-way the process of rendering? |
#
false
|
protected
boolean
|
$blnOnPage
Is the control available on page? Useful when 're-rendering' a control that has children |
#
false
|
protected
boolean
|
$blnModified
Has the control been modified? Used mostly in Ajax or Server callbacks |
#
false
|
protected
boolean
|
$blnWrapperModified
Has the control's wrapper been modified? Used in Ajax or Server callbacks |
#
false
|
protected
string
|
$strRenderMethod
Render method to be used |
|
protected
string|null
|
$strCustomAttributeArray
Custom HTML attributes for the control |
#
null
|
protected
string|null
|
$strCustomStyleArray
Custom CSS style attributes for the control |
#
null
|
protected
array
|
$objActionArray
Array containing the list of actions set on the control (for different events) |
#
array()
|
protected
string| |
$mixActionParameter
The action parameter (typically small amount of data) for the Ajax or Server Callback |
#
null
|
protected
boolean
|
$blnUseWrapper
Should the wrapper be used when rendering? |
#
true
|
protected
string
|
$strAttributeScripts
One time scripts associated with the control. |
#
null
|
protected
string
|
$strCssClass
The INITIAL class for the object. Only subclasses should set this before calling the parent constructor. |
#
null
|
protected
boolean
|
$blnMinimize
Force this control, and all subcontrols to draw minimized. This is important when using inline-block styles, as not doing so will cause spaces between the objects. |
#
false
|
protected
string
|
$strJavaScripts
List of JavaScript files to be attached with the control when rendering |
#
null
|
protected
string
|
$strStyleSheets
List of CSS files to be attaches with the control when rendering |
#
null
|
protected
string
|
$strFormAttributes
Form attributes for the control |
#
null
|
protected
boolean
|
$blnActionsMustTerminate
Should the default action be stopped from the being triggerred when an even occurrs? e.g.:
This variable stops the default behavior (navigation to link / form submission) when set to true. Modification of this variable is to be done by using 'ActionMustTerminate' property exposed as a property |
#
false
|
protected
boolean
|
$blnScriptsOnly
True if this control only generates javascripts and not html. |
#
false
|
protected
boolean
|
$blnIsBlockElement
Is this control a block type element? This determines whether the control will be wrapped in a div or a span if blnUseWrapper is true. For example, if |
#
false
|
protected
|
$objWatcher
Stores information about watched tables. |
#
null
|
protected
|
$objLinkedNode
Used by designer to associate a db node with this control |
|
protected
boolean
|
$blnWrapLabel
| null For controls that also produce built-in labels (QCheckBox, QCheckBoxList, etc.) True to wrap the checkbox with the label (the Bootstrap way). False to put the label next to the checkbox (the jQueryUI way). |
#
false
|
protected
boolean
|
$blnSaveState
true to remember the state of this control to restore if the user comes back to it. |
#
false
|
protected
boolean
|
$blnAutoRender
true to have the control be automatically rendered without an explicit "Render..." call. This is used by QDialogs, and other similar controls that are controlled via javascript, and generally start out hidden on the page. These controls are appended to the form after all other controls. |
#
false
|
$attributes,
$styles
|
public
mixed
|
$ActionParameter
This property allows you to pass your own parameters to the handlers for actions applied to this control. this can be a string or an object of type QJsClosure. If you pass in a QJsClosure it is possible to return javascript objects/arrays when using an ajax or server action. |
public
mixed
|
$CausesValidation
flag says whether or not the form should run through its validation routine if this control has an action defined and is acted upon |
public
string
|
$HtmlAfter
HTML that is shown after the control QControl::RenderWithName |
public
string
|
$HtmlBefore
HTML that is shown before the control QControl::RenderWithName |
public
string
|
$Instructions
instructions that is shown next to the control's name label QControl::RenderWithName |
public
boolean
|
$Moveable
|
public
boolean
|
$Resizable
|
public
string
|
$Name
sets the Name of the Control (see QControl::RenderWithName) |
public
string
|
$PreferredRenderMethod
carries the name of the function, which were initially used for rendering |
public
boolean
|
$Required
specifies whether or not this is required (will cause a validation error if the form is trying to be validated and this control is left blank) |
public
string
|
$ValidationError
is the string that contains the validation error (if applicable) or will be blank if (1) the form did not undergo its validation routine or (2) this control had no error |
public
boolean
|
$Visible
specifies whether or not the control should be rendered in the page. This is in contrast to Display, which will just hide the control via CSS styling. |
public
string
|
$Warning
is warning text that will be shown next to the control's name label QControl::RenderWithName |
public
boolean
|
$UseWrapper
defaults to true |
public
|
$LinkedNode
A database node that this control is directly editing |
public
string
|
$WrapperCssClass
|
public
boolean
|
$WrapLabel
For checkboxes, radio buttons, and similar controls, whether to wrap the label around the control, or place the label next to the control. Two legal styles of label creation that different css and JS frameworks expect. |
public
boolean
|
$Minimize
True to force the entire control and child controls to draw minimized. This is helpful when drawing inline-block items to prevent spaces from appearing between them. |
public
boolean
|
$AutoRender
true to have the control be automatically rendered without an explicit "Render..." call. This is used by QDialogs, and other similar controls that are controlled via javascript, and generally start out hidden on the page. These controls are appended to the form after all other controls. |
public read-only
boolean
|
$ActionsMustTerminate
Prevent the default action from happenning upon an event trigger. See documentation for "protected $blnActionsMustTerminate" below. |
public read-only
boolean
|
$ScriptsOnly
Whether the control only generates javascripts and not html. |
public read-only
string
|
$ControlId
returns the id of this control |
public read-only
|
$Form
returns the parent form object |
public read-only
array
|
$FormAttributes
|
public read-only
string
|
$JavaScripts
|
public read-only
boolean
|
$Modified
indicates if the control has been changed. Used to tell Qcubed to rerender the control or not (Ajax calls). |
public read-only
boolean
|
$OnPage
is true if the control is connected to the form |
public read-only
|
$ParentControl
returns the parent control |
public read-only
boolean
|
$Rendered
|
public read-only
boolean
|
$Rendering
|
public read-only
string
|
$RenderMethod
carries the name of the function, which were initially used for rendering |
public read-only
string
|
$StyleSheets
|
public read-only
boolean
|
$WrapperModified
|
public write-only
boolean
|
$SaveState
set to true to have the control remember its state between visits to the form that the control is on. |
$AccessKey,
$AltText,
$BackColor,
$BorderCollapse,
$BorderColor,
$BorderStyle,
$BorderWidth,
$CssClass,
$Cursor,
$Data,
$Display,
$DisplayStyle,
$Enabled,
$FontBold,
$FontItalic,
$FontNames,
$FontOverline,
$FontSize,
$FontStrikeout,
$FontUnderline,
$ForeColor,
$Height,
$HorizontalAlign,
$Left,
$Margin,
$NoWrap,
$Opacity,
$OrderedListType,
$Overflow,
$Padding,
$Position,
$ReadOnly,
$TabIndex,
$ToolTip,
$Top,
$UnorderedListStyle,
$VerticalAlign,
$Width
|