cObject
---cWebObject
------cWebBaseUIObject
---------cWebBaseDEOServer
------------cWebBaseControl
---------------cWebHtmlBox
Use the cWebHTMLBox class to insert one or more HTML elements within a web view or web dialog (cWebView, cWebModalDialog).
Usually, the client-side HTML of your web application is generated by client JavaScript objects which are, in-turn, generated by your server-side DataFlex web objects. In this scenario, you do not have control over the generated HTML, since this is performed by the JavaScript engine. An HTML box allows you to write an HTML string that will be sent to the client and inserted in the client web page in the location determined by the position of the cWebHTMLBox object.
The HTML elements you insert with this control are wrapped inside the framework's web control HTML element structure. This sandboxes the inserted HTML in a way that it should conform to the framework's column layout system, control labels (psLabel) and application theme support (psTheme).
Despite this sandboxing, it is always possible to write an HTML string that will 'abuse' the client HTML generated and managed by your web application. You should test the HTML that you are inserting and understand its impact on the rest of your application's HTML.
The HTML box provides special support for server-side OnClick events associated with a clickable link. Server OnClick events are achieved by setting the 'data-ServerOnClick' attribute inside the element(s) that will process the user's mouse click.
HTML boxes are ideal for:
- Creating your own clickable elements and processing the click events on the server.
- Displaying text with assorted style attributes applied to individual words.
- Inserting object elements in your view or dialog for displaying special media types.
- Adding HTML to your web view or dialog that is not otherwise possible with other web controls.
- Adding a text link to a web page.
If you wish to embed an entire HTML document via an IFrame, then you should use the cWebIFrame class instead.
Object oHtmlBox1 is a cWebHtmlBox
Set psHtml to ('<ul style="list-style: inside circle">' + ;
'<li><a data-ServerOnClick="option" ' + ;
'data-OnClickParam="1">' + ;
'Option 1</a></li>' + ;
'<li><a data-ServerOnClick="option" ' + ;
'data-OnClickParam="2">' + ;
'Option 2</a></li>' + ;
'<li><a data-ServerOnClick="close">' + ;
'Close</a></li>' + ;
'</ul>')
Set pbServerOnClick to True
Procedure OnClick String sId String sParam
If (sId = "option") Begin
Send ShowInfoBox to ghoWebApp ("sID = " + sId + " sParam = " + sParam)
End
Else If (sId = "close") Begin
Send Hide
End
End_Procedure
End_Object
In the above example an HTML box is used to display an unsorted list. The HTML required to create the list is added to the psHTML property. Each list item contains a link element containing the special data attributes: 'data-ServerOnClick' and 'data-OnClickParam'. These attributes ensure that whenever the user clicks on one of the a (anchor) elements, then an OnClick event is sent to the server passing the two attribute values as the sID and sParam parameters. The OnClick event then interprets these parameters such that if sID = "option", then an info box is shown, if sID = "close", then the Hide message is sent to close the host view or dialog.
Note that in the HTML string the ul (bulleted list) element is given an inline style attribute to position the list buttons 'inside' and to set the list type to 'circle'. This is to overcome styles and margin size inherited from the theme CSS. Your embedded HTML will always need to consider the CSS that is applied to it via the application's theme.
The Web Framework uniquely identifies each web object via a combination of the object hierarchy (object nesting), and object name. This means that web object names must be unique within their parent (i.e. each sibling web object must have a unique name).
HTML box controls must be placed within a web container (e.g. cWebPanel, cWebView or cWebModalDialog).
HTML box controls may not be nested inside other web controls. You may not mix web panels and web controls as sibling objects.
Set psHTML to set the initial HTML string you wish to insert for the HTML box.
For performance tuning purposes, psHTML is not synchronized with the client. This means that you cannot WebSet psHTML to change the control's HTML code. If you wish to change the control's HTML code, send the UpdateHTML message instead.
Object oHtmlBox2 is a cWebHtmlBox
Set psHtml to '<div>Hello World!</div>'
End_Object
Object oByeBtn is a cWebButton
Set psCaption to 'Bye'
Procedure OnClick
Send UpdateHTML of oHtmlBox2 '<div>Goodbye World!</div>'
End_Procedure
End_Object
This sample shows how to add a hyperlink to a web site to the WebOrderMobile sample application's login dialog (login.wo):
Object oHtmlLink is a cWebHtmlBox
Set piColumnSpan to 10
Set piColumnIndex to 2
Set psHtml to 'Click <a data-ServerOnClick="openview" data-OnClickParam="order">here</a> to visit our web site'
Set pbServerOnClick to True
Procedure OnClick String sId String sParam
// open web site
Send NavigateToPage "http://www.dataaccess.com/" btNewTab
End_Procedure
End_Object
Special support for server-side OnClick events is provided. Server OnClick events are achieved by setting the 'data-ServerOnClick' attribute inside the element(s) that will process the user's mouse click. An additional parameter can be passed to the OnClick event by also setting the 'data-OnClickParam' attribute.
Example HTML:
<div data-ServerOnClick="open" data-OnClickParam="order">click here</div>
Example OnClick event:
Set pbServerOnClick to True
Procedure OnClick String sId String sParam
If (sID = "open" and sParam = "order") Begin
Send Show of oOrderView
End
End_Procedure
Web controls are positioned by HTML flow layout (left to right, top to bottom). The relative position of the control in this flow is determined by the location of the object declaration in your code.
In addition to the flow layout, each web container is divided into a fixed number of equal-width columns (piColumnCount). Child controls are aligned to these columns to determine their horizontal position and width.
Set piColumnIndex to position an HTML box control in a particular column of the parent container.
Set piColumnSpan to determine the width of the HTML box control i.e., the number of columns occupied by the control. The actual width is determined by the number of columns and the width of the parent container.
For more information, see Positioning and Layout of Controls.
Each HTML box control has a pre-determined minimum height according to the web application's CSS theme (psTheme). Set piHeight to set the HTML box control to a fixed pixel height. You can also instruct an HTML box control to occupy all available vertical height in its parent container by setting pbFillHeight to true.
The piHeight and pbFillHeight properties are mutually exclusive and should not be used together in the same object.
By default a portion of the control's width is reserved to display a descriptive label. By default, the label is displayed to the left of the control and consumes approximately 120px of the total width.
Set psLabel to the text string you want to display as a label.
Set peLabelAlign to position the label text to the left, right or center of the space allocated to the control's label (alignLeft, alignRight, alignCenter).
Set peLabelPosition to change the position of the space allocated to the control's label. By default, the label is positioned to the left of the control (lpLeft). The label can also be positioned above or to the right of the control (lpTop, lpRight).
Set piLabelOffset to change the amount of space that is consumed by the control's label. By default, the label consumes approximately 120px.
The label's text color is determined by the web application's CSS theme (psTheme). Set psLabelColor to directly override the label's CSS themed color.
Set pbShowLabel to False to hide the label and remove space used the control's label. By default, pbShowLabel is true.
This control can be used as a valid drop target by registering it as such in a cWebDragDropHelper object.
The supported actions for this control are:
- C_WebDropOnControl
This allows the control to accept data dragged from elsewhere in the control (if configured that way) and can also be used to accept files when registered within a cWebDragDropFileHelper.
The color of an HTML box control is determined by the web application's CSS theme (psTheme). You can define additional or replacement CSS styles in your web application's application.css file. Set psCSSClass to the CSS class name you would like to be applied to an HTML box control.
Set psBackgroundColor and psTextColor to directly override the control's CSS themed color.
Set pbScroll to True to show a vertical scroll bar when the HTML box's content exceeds its size. If set to True, and the cWebHtmlBox is inside a cWebCard, it will prevent swiping on mobile devices.
Set pbShowBorder to True to draw a border around the HTML box.