| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one or more |
| contributor license agreements. See the NOTICE file distributed with |
| this work for additional information regarding copyright ownership. |
| The ASF licenses this file to you under the Apache License, |
| Version 2.0 (the "License"); you may not use this file except in |
| compliance with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| <document id="data-binding"> |
| <properties> |
| <title>Data Binding</title> |
| </properties> |
| |
| <body> |
| <p> |
| Data binding refers to the process of automatically populating or extracting data from |
| a set of user interface elements. In Pivot, data binding is driven primarily by two |
| methods of the <tt>Component</tt> class: <tt>load()</tt> and <tt>store()</tt>. Each |
| method takes an <tt>Object</tt> argument called the "context". The context is either an |
| instance of a Java bean class or an instance of |
| <tt>org.apache.pivot.collections.Dictionary</tt>. Calling <tt>load()</tt> causes data |
| from the context to be "loaded" into the component; calling <tt>store()</tt> performs |
| the reverse operation and "stores" data from the component into the context. A third |
| method, <tt>clear()</tt> allows a caller to reset any bindings. |
| </p> |
| |
| <p> |
| Components that support data binding provide "key" properties that allow a caller to |
| associate a property value with a value in the bind context. For example, the |
| <tt>Label</tt> class provides a "textKey" property that maps the label's "text" property |
| to a value provided by the context. |
| </p> |
| |
| <p> |
| The following application demonstrates data binding. It allows the user to load a form |
| with address data either from a JSON file or from a Java bean object, as well as clear |
| the form. Note that binding to a Java bean is accomplished by wrapping the bean in an |
| instance of <tt>org.apache.pivot.beans.BeanAdapter</tt> before passing it to the |
| <tt>load()</tt> method: |
| </p> |
| |
| <application class="org.apache.pivot.wtk.ScriptApplication" width="430" height="280"> |
| <libraries> |
| <library>core</library> |
| <library>wtk</library> |
| <library>wtk-terra</library> |
| <library>tutorials</library> |
| </libraries> |
| |
| <startup-properties> |
| <src>/org/apache/pivot/tutorials/databinding/data_binding.bxml</src> |
| </startup-properties> |
| </application> |
| |
| <p> |
| The BXML simply sets up the form structure and the bind keys: |
| </p> |
| |
| <source type="xml" location="org/apache/pivot/tutorials/databinding/data_binding.bxml"> |
| <![CDATA[ |
| <databinding:DataBinding title="Data Binding" maximized="true" |
| xmlns:bxml="http://pivot.apache.org/bxml" |
| xmlns:databinding="org.apache.pivot.tutorials.databinding" |
| xmlns="org.apache.pivot.wtk"> |
| <Border styles="{padding:6}"> |
| <BoxPane orientation="vertical" styles="{spacing:10, fill:true}"> |
| <Form bxml:id="form" styles="{showFlagIcons:false}"> |
| <Form.Section> |
| <Label bxml:id="sourceLabel" Form.label="Source" styles="{font:{italic:true}}"/> |
| |
| <Label Form.label="ID" textKey="id"/> |
| <TextInput Form.label="Name" textKey="name"/> |
| |
| <BoxPane Form.label="Address" orientation="vertical"> |
| <TextInput textKey="address.street" prompt="Street"/> |
| <BoxPane> |
| <TextInput textKey="address.city" prompt="City"/> |
| <TextInput textKey="address.state" textSize="6" prompt="State"/> |
| <TextInput textKey="address.zip" textSize="6" prompt="Zip"/> |
| </BoxPane> |
| </BoxPane> |
| |
| <TextInput Form.label="Phone" textKey="phoneNumber"/> |
| <TextInput Form.label="Email" textKey="emailAddress"/> |
| |
| <BoxPane Form.label="IM"> |
| <TextInput textKey="imAccount.id"/> |
| <ListButton selectedItemKey="imAccount.type" |
| listData="['AIM', 'Jabber', 'Yahoo']"/> |
| </BoxPane> |
| </Form.Section> |
| </Form> |
| |
| <Separator/> |
| |
| <BoxPane styles="{horizontalAlignment:'right'}"> |
| <PushButton bxml:id="loadJSONButton" buttonData="Load JSON"/> |
| <PushButton bxml:id="loadJavaButton" buttonData="Load Java"/> |
| <PushButton bxml:id="clearButton" buttonData="Clear"/> |
| </BoxPane> |
| </BoxPane> |
| </Border> |
| </databinding:DataBinding> |
| ]]> |
| </source> |
| |
| <p> |
| The windows's <tt>initialize()</tt> method defines the button press listeners that |
| load or clear the form: |
| </p> |
| |
| <source type="java" location="org/apache/pivot/tutorials/databinding/DataBinding.java"> |
| <![CDATA[ |
| package org.apache.pivot.tutorials.databinding; |
| |
| import java.io.InputStream; |
| import java.net.URL; |
| |
| import org.apache.pivot.beans.BeanAdapter; |
| import org.apache.pivot.beans.Bindable; |
| import org.apache.pivot.collections.Map; |
| import org.apache.pivot.json.JSONSerializer; |
| import org.apache.pivot.util.Resources; |
| import org.apache.pivot.wtk.Button; |
| import org.apache.pivot.wtk.ButtonPressListener; |
| import org.apache.pivot.wtk.Form; |
| import org.apache.pivot.wtk.Label; |
| import org.apache.pivot.wtk.PushButton; |
| import org.apache.pivot.wtk.Window; |
| |
| public class DataBinding extends Window implements Bindable { |
| private Form form = null; |
| private PushButton loadJavaButton = null; |
| private PushButton loadJSONButton = null; |
| private PushButton clearButton = null; |
| private Label sourceLabel = null; |
| |
| private static final Contact CONTACT = new Contact("101", "Joe User", |
| new Address("123 Main St.", "Cambridge", "MA", "02142"), |
| "(617) 555-1234", "joe_user@foo.com", |
| new IMAccount("juser1234", "AIM")); |
| |
| @Override |
| public void initialize(Map<String, Object> namespace, URL location, Resources resources) { |
| form = (Form)namespace.get("form"); |
| loadJavaButton = (PushButton)namespace.get("loadJavaButton"); |
| loadJSONButton = (PushButton)namespace.get("loadJSONButton"); |
| clearButton = (PushButton)namespace.get("clearButton"); |
| sourceLabel = (Label)namespace.get("sourceLabel"); |
| |
| loadJavaButton.getButtonPressListeners().add(new ButtonPressListener() { |
| @Override |
| public void buttonPressed(Button button) { |
| form.load(new BeanAdapter(CONTACT)); |
| sourceLabel.setText("Java"); |
| } |
| }); |
| |
| loadJSONButton.getButtonPressListeners().add(new ButtonPressListener() { |
| @Override |
| public void buttonPressed(Button button) { |
| JSONSerializer serializer = new JSONSerializer(); |
| InputStream inputStream = getClass().getResourceAsStream("contact.json"); |
| |
| try { |
| form.load(serializer.readObject(inputStream)); |
| sourceLabel.setText("JSON"); |
| } catch(Exception exception) { |
| System.err.println(exception); |
| } |
| |
| button.setEnabled(true); |
| } |
| }); |
| |
| clearButton.getButtonPressListeners().add(new ButtonPressListener() { |
| @Override |
| public void buttonPressed(Button button) { |
| form.clear(); |
| sourceLabel.setText(""); |
| } |
| }); |
| } |
| } |
| ]]> |
| </source> |
| |
| <p> |
| The JSON representation of the sample contact record is defined as follows (note that, |
| while JSON is used to represent the data in this example, any class that implements |
| the <tt>Dictionary</tt> interface, including <tt>HashMap</tt>, can be used): |
| </p> |
| |
| <source type="jscript" location="org/apache/pivot/tutorials/databinding/contact.json"> |
| <![CDATA[ |
| { id: 101, |
| name: "Joe User", |
| |
| address: { |
| street: "123 Main St.", |
| city: "Cambridge", |
| state: "MA", |
| zip: "02142" |
| }, |
| |
| phoneNumber: "(617) 555-1234", |
| emailAddress: "joe_user@foo.com", |
| |
| imAccount: { |
| id: "juser1234", |
| type: "AIM" |
| } |
| } |
| ]]> |
| </source> |
| |
| <p> |
| The Java bean version, which represents the same data, is composed of the following |
| classes: |
| </p> |
| |
| <source type="java" location="org/apache/pivot/tutorials/databinding/Contact.java"> |
| <![CDATA[ |
| package org.apache.pivot.tutorials.databinding; |
| |
| public class Contact { |
| private String id; |
| private String name; |
| private Address address; |
| private String phoneNumber; |
| private String emailAddress; |
| private IMAccount imAccount; |
| |
| public Contact(String id, String name, Address address, String phoneNumber, |
| String emailAddress, IMAccount imAccount) { |
| this.id = id; |
| this.name = name; |
| this.address = address; |
| this.phoneNumber = phoneNumber; |
| this.emailAddress = emailAddress; |
| this.imAccount = imAccount; |
| } |
| |
| public String getID() { |
| return id; |
| } |
| |
| public String getId() { |
| return getID(); |
| } |
| |
| public String getName() { |
| return name; |
| } |
| |
| public Address getAddress() { |
| return address; |
| } |
| |
| public String getPhoneNumber() { |
| return phoneNumber; |
| } |
| |
| public String getEmailAddress() { |
| return emailAddress; |
| } |
| |
| public IMAccount getIMAccount() { |
| return imAccount; |
| } |
| |
| public IMAccount getImAccount() { |
| return getIMAccount(); |
| } |
| } |
| ]]> |
| </source> |
| |
| <source type="java" location="org/apache/pivot/tutorials/databinding/Address.java"> |
| <![CDATA[ |
| package org.apache.pivot.tutorials.databinding; |
| |
| public class Address { |
| private String street; |
| private String city; |
| private String state; |
| private String zip; |
| |
| public Address() { |
| this(null, null, null, null); |
| } |
| |
| public Address(String street, String city, String state, String zip) { |
| this.street = street; |
| this.city = city; |
| this.state = state; |
| this.zip = zip; |
| } |
| |
| public String getStreet() { |
| return street; |
| } |
| |
| public String getCity() { |
| return city; |
| } |
| |
| public String getState() { |
| return state; |
| } |
| |
| public String getZip() { |
| return zip; |
| } |
| } |
| ]]> |
| </source> |
| |
| <source type="java" location="org/apache/pivot/tutorials/databinding/IMAccount.java"> |
| <![CDATA[ |
| public class IMAccount { |
| private String id; |
| private String type; |
| |
| public IMAccount() { |
| this(null, null); |
| } |
| |
| public IMAccount(String id, String type) { |
| this.id = id; |
| this.type = type; |
| } |
| |
| public String getID() { |
| return id; |
| } |
| |
| public String getId() { |
| return getID(); |
| } |
| |
| public String getType() { |
| return type; |
| } |
| } |
| ]]> |
| </source> |
| |
| <p> |
| This application's data binding requirements are fairly straightforward. It is |
| load-only, and all of the data is simply presented as-is. However, many real-world |
| applications may want to transform the data in some way before presenting it to the |
| user; for example, an application may want to apply currency formatting to a numeric |
| value, or convert an encoded date string to an instance of |
| <tt>org.apache.pivot.util.CalendarDate</tt>. Components that support data binding |
| provide a "bind mapping" interface to facilitate such transformations. Bind mappings |
| are outside the scope of this example but are demonstrated in the |
| <a href="query-servlet.html">QueryServlet</a> section as well as the |
| <a href="stock-tracker.html">Stock Tracker</a> tutorial. |
| </p> |
| |
| <p> |
| Also, though it is not shown in this example, bindable components allow a caller to |
| control the bind direction via a "bind type" property. The bind type is specified by |
| an instance of the <tt>org.apache.pivot.wtk.BindType</tt> enum, which defines the |
| following values: |
| </p> |
| |
| <ul> |
| <li><tt>LOAD</tt> - binding will only occur during a <tt>load()</tt> operation</li> |
| <li><tt>STORE</tt> - binding will only occur during a <tt>store()</tt> operation</li> |
| <li><tt>BOTH</tt> - binding occur during both <tt>load()</tt> and <tt>store()</tt> operations</li> |
| </ul> |
| </body> |
| </document> |
