Web Framework - Overview

Node - The common base class for both tags and attributes.
Element, HTMLElement - Used as the base classes for all tags in the page.
HtmlPage, Head, Body, Div, Input, A, Form, Button, Option, Select, Form, Span, Style.

A tag in an schtml page with an id is converted to an object instance of the given class.

Tag properties

All tag classes inherit from the same Element class, but special tag classes add additional features:

Select tag

selectedIndex - reflects the selected index and usable in forward or reverse bindings.
selectedValue - also usable in forward or reverse directions, as an alternative to selectedIndex. Set this to point to a value in the array or List for optionDataSource. It will select that item by default. When the value changes, it points to the currently selected value.
optionDataSource - set to the List to use for populating the option tags.
changeEvent - set each time the HTML 'change' event is fired, useful in reverse-only bindings to call a method, set a property or eval another expression.

Input tag

value - controls the value attribute in HTML
disabled - controls the disabled attribute in HTML
checked - controls the checked attribute for those input types which use it
liveEdit - use 'on' so that each character is sync'd immediately, or 'change' so that the value is sync'd only after changing focus or hitting enter or 'off' for a batch style form, where values are sent only after another value is changed.
changeEvent - set each time the HTML 'change' event is fired, useful in reverse-only bindings to call a method

Button tag

Just like Input but used for the button tag.

Img tag

src - relative URLs are rewritten
width
height

Option tag

selected
disabled
value
optionData - returns the value this option when optionDataSource is used on the enclosing select tag.

A tag

href - relative URLs are rewritten so that components can be used from different directories, and top-level page URLs can be changed without breaking relative links in the page.

Form tag

submitEvent - property set when the form is submitted.
submitCount - integer property incremented each time form is submitted
submitInProgress - set to true when submitFormData() has been called and the browser is in the middle of the "POST" of the form data to the server.
submitError - set to null for a successful submitFormData result or to the errorCode of the response if the POST to the specified URL fails.

Call Form.submit() method on the server or client to submit the form programmatically. This just calls the dom elements 'submit' method that will typically go to the action page.

Call Form.sendSubmitEvent() from test scripts or server code to simulate a form submit without navigating to the action page.

Call Form.submitFormData(String url) to send the FormData to the specified URL. This is in particular useful for file upload forms that should use a single-page application style. The result can be a subclass of sc.servlet.UploadPage, designed to support a simple form receiver for file upload (or other multi-part forms).

All of the methods of submitting a form from code are supported in both server tags and client/server mode.

Body, Head tags

These are 'singleton' tags - the id is the tag name.

HtmlPage tag

Specifies the top level html page.

refreshBindings - set to true in the page to refresh all bindings in the page after user interaction or changes from the server are applied. This is a somewhat expensive option to enable when there are thousands of bindings in the page but a quick way to update the page when properties are missing change events and they are difficult to add.
pageVisitCount - An integer value that's incremented once when the page is loaded. Bind to this property to run events on the initial page load, either on the server for a server-only, client for a client-only app, or both for a client-server app.

All tags: behavioral attributes

These attributes which apply to any tag affect the code generation process:

extends - refers to the type name of a tag object to use as the base class for this tag. By default, the attributes and body are both inherited but this can be controlled via the tagMerge and bodyMerge attributes.
implements - specifies a list of tags objects from which to inherit attributes and content. Also controlled by tagMerge and bodyMerge.
abstract - when true, the tag object is not instantiated in the parent page. It's a way to essentially define a tag class macro which you can extend in other instances or create using an API.
repeat - refers to a List or array of items. The tag is replicated once for each item. Use repeatVarName to specify the name of the variable to store the array element.
repeatVarName - used with repeat to define a variable name other than "repeatVar" to hold the value.
repeatWrapper - used with repeat to specify the extends class for the repeat wrapper class
repeatIndex - for each tag inside of a repeat a bindable property set to the index of that tag
replaceWith - used with an expression that evaluates to another tag object (usually a separate tag template). Use this to switch between completely different versions of content that occupy the same space. If the expression evaluates to null, the owner tag is rendered instead.
serverContent - set this to true on a tag object you do not want rendered in the client. It's similar but slightly different than exec="server". When you set exec="server", when building the client version this object is omitted entirely so it won't be present when rendering the initial .html file. Use serverContent so that this tag object but not it's children are included in the content. Use serverContent in stubs inserted into the client tag objects to represent chunks of content where we should preserve the existing innerHTML of the DOM object when the parent is being re-rendered.
exec - set to either 'client', 'server' or 'default'. This attribute is helpful when a file is shared by both client and server processes but where the tag should be included in only one version of the page object. Use 'default' for the case where you want it in the client for client-only applications and the server for client-server applications.
tagMerge - specifies how the tag and it's attributes are merged with the tag object it overrides by modifying a tag object in a previous layer, or overriding a tag object it extends or implements. A value of 'merge' is the default. Set it to 'replace' for this tag to entirely replace the previous one or set it to 'append', or 'prepend'. This attribute affects both the body and attributes unless bodyMerge is set. See the javadoc for MergeMode for more info.
bodyMerge - specifies just how the body of the tag is merged, for when you want to merge the body of the tag differently from the attributes. Same values as tagMerge.
addBefore, addAfter - set to the id of an inherited tag used to place this tag either before or after. Use this for more flexible control of individual tags during a merge of one tag body with it's inherited tag body.
orderValue - when using 'merge' mode for child tags, provides a way to reorder a given child tag with respect to the others. Tags are sorted from smaller orderValues to large ones and the default value is 0. For example, use -1 on a tag so it goes before other child tags and use 1 so it goes after.
scope - specifies the lifecycle of this tag object (similar to setting the @Scope annotation or using the 'scope' operator in sc), for example scope="session" or scope="request".
cache - turn on/off caching of content for the given tag (default is true).
visible - set to true for the tag to be displayed, false for it to be hidden. When a tag is not visible, if it has a child with the id="alt", that tag is displayed in it's place. Otherwise, the parent's body is re-rendered to omit this child if it was previously visible.
component - set to true to make this tag an @Component class in the generated code
stateless - set to true to for a tag to be put into 'stateless' mode. Otherwise, the tag is stateless if it does not have an id attribute or use any other behavior attributes like 'extends'.
bodyOnly - Controls whether or not the start and end tag are drawn or just the body. The default is 'false' to render both the start and end tag. When set to true, only the body is rendered - the start and end tag are omitted. This is a bindable property so it can be changed to true/false on the fly. It's is useful for where you need some dynamic content to be part of the body directly of the parent element, or if you want to wrap/unwrap a tag in different modes.
wrap - For repeat tags only, wrap determines whether the repeat tag itself is repeated, or whether it's rendered once and only the body of the tag is repeated. The default value is different for different tags. For most tags, wrap is false so that the tag with the repeat attribute is itself repeated. But for the dl and ul tags, only the body elements are repeated. For dl, typically the dd/dt pair of tags is repeated once for each element in the array.
changedCount - an integer property that is incremented each time the content of an input tag or text area is changed.
initScript, stopScript - used for components that use external Javascript (see Javascript Components)

Javascript components

It's possible to use standard Javascript libraries with SC tag objects. Set the 'initScript' property to a JS code snippet to be executed when the component is first initialized. Set the 'stopScript' property to a script that is run code when the tag is removed from the DOM.

Both tags are run where the 'this' object for the JS code snippet is set to the tagObject itself. That means you can call access the 'id' property, or set other properties on that object.

For examples, see the HtmlTextEditor components provided in the coreFrameworks bundle.

DOM Events

There are properties in the tag object for each of the DOM events that are available on any element. Use reverse-only bindings to call a method when an event is fired. A reverse-only binding can also perform an assignment. These expressions can refer to the value of the Event being fired to the timestamp, currentTarget, button pressed, etc. using properties in the event.

Here is the list of event properties that are supported:

clickEvent, dblClickEvent, mouseDownEvent mouseMoveEvent, mouseOverEvent, mouseOutEvent, mouseUpEvent, keyDownEvent, keyPressEvent, keyUPEvent, submitEvent, changeEvent, focusEvent, blurEvent, and a special combo event: mouseDownMoveUp for tracking click, drag, release.

It can sometimes be helpful to be notified of the size change for an element. Each tag object exposes bindable properties for: clientWidth, clientHeight, offsetWidth, offsetHeight, scrollWidth, and scrollHeight.

URL annotation

The URL annotation is set on an html page tag object to expose that page as a web URL. In the default html.schtml framework layer, it is set on the HtmlPage tagObject used by default for pages that contain an html tag.

pattern - set on an html page tagObject to expose it with a web address. It can be a fixed string for fixed URLs, or contain variables that can be mapped onto properties of the page object. When the URL is requested, the property on the tag object is populated. And while the page's tag object is active, if the property is changed, the page's URL in the browser is updated.
dynContent - set this to false for pages that do not need the typical setup for a dynamic page. For example a page that is downloading a static file can set this to true for a faster and simpler request handling process.
resource - set to true for css, images other files that are assets of the main page object. A resource that is generated dynamically won't create a new application scope based on the URL but instead uses the application of it's referring page.
mimeType - set the mime type for the response of this tagObject
subTypesOnly - use this in framework layers to define an @URL annotation that applies to instances of subclass only. This attribute is used for example by the HtmlPage.schtml in the html.schtml framework layer to establish the default for how html pages are handled.
realTime - set to true or false to turn on or off the auto-sync behavior in a page that lets the page use real time features. It always makes sense to set this on the logout page or any other page that terminates the session explicitly. Otherwise the page creates a new anonymous session as part of the next sync.
testURLs - a list of test URL paths to use from test scripts from this page. Use this for URLs that take parameters to provide default values for those parameters that make sense in an automated test. They only affect the code when testMode is true in the application. These URLs are available from the layeredSystem via a list of URLPath objects and used by the TestPageLoader in the web framework for a quick way to assemble automated tests and to create a navigation page for testing the application. Because @URL can be set in a testing layer to modify pages in a base-layer, it's possibe to create custom test configurations by modiyfing the @URL annotation to add testURLs that apply for a specific testing layer.
testScripts - a list of test scripts to run as part of an automated test script for this page. Once the page is loaded, the list of test scripts is run in order. If there is a single test script with the name "none", that page is omitted from the auto-test.