The SBApplicationModel is the superclass for all applications written in seaBreeze. Each application generated using the ApplicationWizard will contain such a new subclass, along with a FileLibrary subclass, each contained in a new, application specific namespace.
Lets pretend that you created application 'MyTestApp'. The resulting SBApplicationModel subclass is MTAMyTestApp, which is contained in Namespace MyTestApp. If the template for the page layout was the empty template, then class MTAMyTestApp will contain a windowSpec class method, defining the empty web page for this application.
In addition to the windowSpec class-method, there is the description, the canBeRoot, and the initialize method.
While the description method simply returns the string you entered into the wizards input field, the initialize-method is an active player for your application. Because the application was generated by the SeaBreeze-Wizard, class MTAMyTestApp is registered under the application name with SeaSide Dispatcher; this is done by the intialize-method.
The canBeRoot-method returns true for all wizard-generated applications, allowing such applications to run as stand-alone applications; in contrast to components, which may only be embedded into applcations, but more about that later.
Up till here, the applictaion is registered with the Dispatcher, and may be started with a simple click from there. The empty page layout will ensure that the browser shows a white page.
In the following, we want to show you how the application is enhaced with seaBreeze elements (widgets), how the widgets interact with the SBApplicationModel, and some more secrets about the start-up of an application.
Adding seaBreeze Elements to the Application
seaBreeze elements are added to the page of an application in the seaBreeze-Editor. The Palette offers a wide range of elements organized in different categories.See the chapter about the palette for details about the elements.
seaBreeze Elements and the SBApplicationModel All the elements have attributes, which allow an interaction with the application object (which is an instance of your subclass of SBApplicationModel, in our example: an instance of MTAMyTestApp). E.g. an SBTextElement may have a constant text, which is fixed, or may fetch the text to display from the application using its Aspect attribute, which will be a method name (a Symbol). This is not only true for the SBTextElement, but many others can fetch their contents from the application object this way, using their Aspect-symbol and send it as a message to the application object. Of course, a method with this name has to be implemented or inherited by the application object, and the method has to return an appropriate object for the calling element.
In case of the SBTextElement, the aspect method has to return a plain String. But if it is a SBStyledTextElement, the aspect method may return an HTML-String; the programmer has to ensure that it is strict HTML, and that it works in any browser himself!
Another kind of interaction with the applictaion object is through Action methods. Elements like the SBAnchorElement or the SBSubmitButton provide this configuration option. Again, the Action-attribute should be configured with a method name (a Symbol, like #logoutAction). Both example elements (the anchor and the button) perform the action method when they get clicked or pressed, but under different conditions:
- while the SBAnchorElement calls the method from any location on the web page,
- the SBSubmitButton can only work from within a Form element.
This difference is significant, because a Form is normaly only available in data-collecting applications, while anchors are also well known in data-presentation applications. A submit button click will transfere all data from the Form element it is located in back to the server; in our case: the application object.
So an anchor provides a more light-weight call of an action method, while the button performs a more sophisticated action operation.
However, the Form-submit includes another kind of element-to-application interaction, and that is the transfer of data from the web page back to the application. An SBTextInputElement also provides the Aspect-attribute as a configuration option. This time, the symbol entered here is not only used to fetch some data from the application object, the symbol is also used to pass any contents of the input field back to it. The seaBreeze-Editor in these cases provides for code generation support:
- add (e.g.) an SBTextInputElement to your web page, an SBFormElement is added, containing the input element right away,
- configure the Aspect attribute of the input element with the symbol: #name
- the ElementEditor will now display a small, red arrow to the right of the aspect symbol.
- the red color indicates that the aspect is not implemented by the application right now
- otherwise, it would be a black arrow!
- pressing the red arrow will create the following code in the application
- an instance variable 'name'
- an accessor method 'name', to read the value of instance variable 'name', and
- a mutator method 'name:', to write a value back into the instance variable 'name'.
You don't have to use the red arrow for each element in your form, it is possible to add a bunch of input fields and alike to your web page, configure their aspect attributes, and then create all models (the methods along with the variables) using the ToolBar button 'Define Models for all aspects'. An upcoming dialog gives you the chance to select each of the undefined aspects, if you want to skip code generation for some.
'Submit' versus 'Use Ajax'
So we are right at the explanation of how forms and the transfere of user input to our application object works.
Each SBFormElement lets you choose which way the data of the input fields of the form will take back to the application. A checkbox in the ElementEditor for the SBFormElement makes the difference: 'use Ajax'. If unchecked (default), the content of the fields in the Form is only transfered to the application, when a submit button inside (??) the Form is pressed. If the checkbox is checked, each field of the Form will transfere its data to the application, when it either looses keyboard focus (e.g. input fields), or when the state is changed by a mouse click (e.g. radio button, checkbox, submit button etc.).
- Standard: Data sent on 'Submit'
- the whole form along with the rest of the page is send to the server
- all field values are put into their aspects
- the action of the submit button is executed
- after this, the whole page is sendback to the browser, which is similar to a redraw of the application. Any change performed during the submit action, which may have added or changed the underlying data in any way, will be displayed because of this 'redraw' activity.
- pro: easy wo setup, easy to extend, no special updates necessary (see below),
- cons: a full page redraw is expensive, the more complex an application gets.
- Special: Data sent using Ajax calls
- each field change triggers a data send back to the application,
- although all field values are included, the request does not contain the full page
- this way, every mutator method of the involved aspects are invoked, without the submit button being triggered!
- this allows you to perform activities (checks, data fetches based on entered data etc.) in a mutator
- you may reject the entered data, e.g.
- a mutator may trigger a dedicated update of an area of the page (see below)
- the action of the submit button is ony triggered, if the button was clicked
- the method can rely on validated data, or unchanged data
- the submit action may update a dedicated area of the page
- pro: much less data transfered between browser and server, local updates of screen areas possible, less flicker,
- cons: more thinking for the setup, more coding for individual mutator methods.
To update a specific screen area, all components of a seaBreeze web page have IDs. In your Ajax-Callback, that is the action- or the mutator-method, you may trigger an update of one of those elements, if you happen to know its ID. The expression:
SBElementUpdater updateElementWithId: #PersonCollectionTable
will trigger an update of the container of the element with ID #PersonCollectionTable. The description is very important, because the parent container might include other elements you don't want to refresh, which might leed to unwanted activities.
Anyway, the decision between submit or Ajax driven applications is yours, be carefull to choose the right way for your application!
The Start-Up of a seaBreeze Application
If you click on the application entry in the SeaSide Dispatcher, an instance of your application will be created and initialized. There are three methods which are called during the build phase of the application instance, ready for you to implement in your application class. By default, the methods will be called and do nothing. Only if your class re-implements one, the code will be executed. All three are called with a builder object as the argument, which gives you access to the elements on you page in different stages of the build process.
- preBuildWith:
- this method is called before the elements for the web page are created, the builder object does not know about the windowSpec yet.
- postBuildWith:
- when this method is called, the builder just received the windowSpec, thus he knows about all the elements on the web page.
- because the elements have not been sent to the browser, you may configure them in this method.
- another opportunity is to fetch an element from the builder in order to modify its state or style later during application processing.
- at this stage, the elements have their original elementID, the one specified in the seaBreeze editor.
- to access an element, just send elementWithId: along with the ID as a String to the application object.
- see below for some details about what you can do to an element in this stage.
- postOpenWith:
- this method is not called after the page has been sent to the browser, it is just the moment before this would happen.
- by and large, the same activities could happen here as in postBuildWith: