diff options
Diffstat (limited to 'documentation/application/application-declarative.asciidoc')
| -rw-r--r-- | documentation/application/application-declarative.asciidoc | 398 |
1 files changed, 0 insertions, 398 deletions
diff --git a/documentation/application/application-declarative.asciidoc b/documentation/application/application-declarative.asciidoc deleted file mode 100644 index 316d6d7633..0000000000 --- a/documentation/application/application-declarative.asciidoc +++ /dev/null @@ -1,398 +0,0 @@ ---- -title: Designing UIs Declaratively -order: 3 -layout: page ---- - -[[application.declarative]] -= Designing UIs Declaratively - -Declarative definition of composites and even entire UIs makes it easy for -developers and especially graphical designers to work on visual designs without -any coding. Designs can be modified even while the application is running, as -can be the associated themes. A design is a representation of a component -hierarcy, which can be accessed from Java code to implement dynamic UI logic, as -well as data binding. - -For example, considering the following layout in Java: - - -[source, java] ----- -VerticalLayout vertical = new VerticalLayout (); -vertical.addComponent(new TextField("Name")); -vertical.addComponent(new TextField("Street address")); -vertical.addComponent(new TextField("Postal code")); -layout.addComponent(vertical); ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.basic[on-line example, window="_blank"]. - -You could define it declaractively with the following equivalent design: - - -[source, html] ----- -<v-vertical-layout> - <v-text-field caption="Name"/> - <v-text-field caption="Street address"/> - <v-text-field caption="Postal code"/> -</v-vertical-layout> ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#layout.orderedlayout.basic[on-line example, window="_blank"]. - -Declarative designs can be crafted by hand, but are most conveniently created -with the Vaadin Designer. - -In the following, we first go through the syntax of the declarative design -files, and then see how to use them in applications by binding them to data and -handling user interaction events. - -[[application.declarative.syntax]] -== Declarative Syntax - -A design is an HTML document with custom elements for representing components -and their configuration. A design has a single root component inside the HTML -body element. Enclosing [literal]#++<html>++#, [literal]#++<head>++#, -[literal]#++<body>++# are optional, but necessary if you need to make namespace -definitions for custom components. Other regular HTML elements may not be used -in the file, except inside components that specifically accept HTML content. - -In a design, each nested element corresponds to a Vaadin component in a -component tree. Components can have explicitly given IDs to enable binding them -to variables in the Java code, as well as optional attributes. - - -[source, html] ----- -<!DOCTYPE html> -<html> - <body> - <v-vertical-layout size-full> - <!-- Label with HTML content --> - <v-label><b>Hello!</b> - How are you?</v-label> - - <v-horizontal-layout size-full :expand> - <v-tree _id="mytree" caption="My Tree" - width-auto height-full/> - <v-table _id="mytable" caption="My Table" - size-full :expand/> - </v-horizontal-layout> - </v-vertical-layout> - </body> -</html> ----- - -The DOCTYPE is not required, neither is the [literal]#++<html>++#, or -[literal]#++<body>++# elements. Nevertheless, there may only be one design root -element. - -The above design defines the same UI layout as done earlier with Java code, and -illustrated in -<<dummy/../../../framework/application/application-architecture#figure.application.architecture.example,"Simple -Hierarchical UI">>. - - -[[application.declarative.elements]] -== Component Elements - -HTML elements of the declarative syntax are directly mapped to Vaadin components -according to their Java class names. The tag of a component element has a -namespace prefix separated by a dash. Vaadin core components, which are defined -in the [package]#com.vaadin.ui# package, have [literal]#++v-++# prefix. The rest -of an element tag is determined from the Java class name of the component, by -making it lower-case, while adding a dash ( [literal]#++-++#) before every -previously upper-case letter as a word separator. For example, -[classname]#ComboBox# component has declarative element tag -[literal]#++<v-combo-box>++#. - -[[application.declarative.elements.prefix]] -=== Component Prefix to Package Mapping - -You can use any components in a design: components extending Vaadin components, -composite components, and add-on components. To do so, you need to define a -mapping from an element prefix to the Java package of the component. The prefix -is used as a sort of a namespace. - -The mappings are defined in [literal]#++<meta name="package-mapping" ...>++# -elements in the HTML head. A [parameter]#content# attribute defines a mapping, -in notation with a prefix separated from the corresponding Java package name -with a colon, such as " [literal]#++my:com.example.myapp++#". - -For example, consider that you have the following composite class -[classname]#com.example.myapp.ExampleComponent#: - - -[source, java] ----- -package com.example.myapp; - -public class ExampleComponent extends CustomComponent { - public ExampleComponent() { - setCompositionRoot(new Label("I am an example.")); - } -} ----- - -You would make the package prefix mapping and then use the component as follows: - -[subs="normal"] ----- -<!DOCTYPE html> -<html> - <head> - **<meta name="package-mapping" content="my:com.example.myapp" />** - </head> - - <body> - <v-vertical-layout> - <v-label><b>Hello!</b> - How are you?</v-label> - - <!-- Use it here --> - **<my-example-component/>** - </v-vertical-layout> - </body> -</html> ----- - -[[application.declarative.elements.inline]] -=== Inline Content and Data - -The element content can be used for certain default attributes, such as a button -caption. For example: - - -[source, html] ----- -<v-button><b>OK</b></v-button> ----- - -Some components, such as selection components, allow defining inline data within -the element. For example: - - -[source, html] ----- -<v-native-select> - <option>Mercury</option> - <option>Venus</option> - <option selected>Earth</option> -</v-native-select> ----- - -The declarative syntax of each component type is described in the JavaDoc API -documentation of Vaadin. - - - -[[application.declarative.attributes]] -== Component Attributes - -[[application.declarative.attributes.mapping]] -=== Attribute-to-Property Mapping - -Component properties are directly mapped to the attributes of the HTML elements -according to the names of the properties. Attributes are written in lower-case -letters and dash is used for word separation instead of upper-case letters in -the Java methods, so that [literal]#++input-prompt++# attribute is equivalent to -[methodname]#setInputPrompt()#. - -For example, the __caption__ property, which you can set with -[methodname]#setCaption()#, is represented as [literal]#++caption++# attribute. -You can find the component properties by the setter methods in the -link:https://vaadin.com/api/[JavaDoc API documentation] of the component -classes. - - -[source, html] ----- -<v-text-field caption="Name" input-prompt="Enter Name"/> ----- - - -[[application.declarative.attributes.parameters]] -=== Attribute Values - -Attribute parameters must be enclosed in quotes and the value given as a string -must be convertible to the type of the property (string, integer, boolean, or -enumeration). Object types are not supported. - -Some attribute names are given by a shorthand. For example, -[parameter]#alternateText# property of the [classname]#Image# component, which -you would set with [methodname]#setAlternateText()#, is given as the -[literal]#++alt++# attribute. - -Boolean values must be either " [literal]#++true++#" or " [literal]#++false++#". -The value can be omitted, in which case [literal]#++true++# is assumed. For -example, the [literal]#++enabled++# attribute is boolean and has default value " -[literal]#++true++#", so [literal]#++enabled="true"++# and -[literal]#++enabled++# and equivalent. - - -[source, html] ----- -<v-button enabled="false">OK</v-button> ----- - - -[[application.declarative.attributes.parent]] -=== Parent Component Settings - -Certain settings, such as a component's alignment in a layout, are not done in -the component itself, but in the layout. Attributes prefixed with colon ( -[literal]#++:++#) are passed to the containing component, with the component as -a target parameter. For example, [literal]#++:expand="1"++# given for a -component [parameter]#c# is equivalent to calling [methodname]#setExpandRatio(c, -1)# for the containing layout. - -[subs="normal"] ----- -<v-vertical-layout size-full> - <!-- Align right in the containing layout --> - <v-label width-auto **:right**>Hello!</v-label> - - <!-- Expands to take up all remaining vertical space --> - <v-horizontal-layout size-full **:expand**> - <!-- Automatic width - shrinks horizontally --> - <v-tree width-auto height-full/> - - <!-- Expands horizontally to take remaining space --> - <v-table size-full **:expand**/> - </v-horizontal-layout> -</v-vertical-layout> ----- -Again, compare the above declaration to the Java code given in -<<dummy/../../../framework/application/application-architecture#application.architecture,"Building -the UI">>. - - - -[[application.declarative.identifiers]] -== Component Identifiers - -Components can be identified by either an identifier or a caption. There are two -types of identifiers: page-global and local. This allows accessing them from -Java code and binding them to components, as described later in -<<application.declarative.composite>>. - -The [literal]#++id++# attribute can be used to define a page-global identifier, -which must be unique within the page. Another design or UI shown simultaneously -in the same page may not have components sharing the same ID. Using global -identifiers is therefore not recommended, except in special cases where -uniqueness is ensured. - -The [literal]#++_id++# attribute defines a local identifier used only within the -design. This is the recommended way to identifying components. - - -[source, html] ----- -<v-tree _id="mytree" caption="My Tree"/> ----- - - -[[application.declarative.composite]] -== Using Designs in Code - -The main use of declarative designs is in building application views, sub-views, -dialogs, and forms through composition. The two main tasks are filling the -designs with application data and handling user interaction events. - -[[application.declarative.composite.designroot]] -=== Binding to a Design Root - -You can bind any component container as the root component of a design with the -[classname]#@DesignRoot# annotation. The class must match or extend the class of -the root element in the design. - -The member variables are automatically initialized from the design according to -the component identifiers (see <<application.declarative.identifiers>>), which -must match the variable names. - -For example, the following class could be used to bind the design given earlier. - - -[source, java] ----- -@DesignRoot -public class MyViewDesign extends VerticalLayout { - Tree mytree; - Table mytable; - - public MyViewDesign() { - Design.read("MyDeclarativeUI.html", this); - - // Show some (example) data - mytree.setContainerDataSource( - TreeExample.createTreeContent()); - mytable.setContainerDataSource( - TableExample.generateContent()); - - // Some interaction - mytree.addItemClickListener(event -> // Java 8 - Notification.show("Selected " + - event.getItemId())); - } -} ----- -See the http://demo.vaadin.com/book-examples-vaadin7/book#application.declarative.designroot[on-line example, window="_blank"]. - -The design root class must match or extend the root element class of the design. -For example, earlier we had [literal]#++<v-vertical-layout>++# element in the -HTML file, which can be bound to a class extending [classname]#VerticalLayout#. - - -[[application.declarative.composite.using]] -=== Using a Design - -The fact that a component is defined declaratively is not visible in its API, so -you can create and use such it just like any other component. - -For example, to use the previously defined design root component as the content -of the entire UI: - - -[source, java] ----- -public class DeclarativeViewUI extends UI { - @Override - protected void init(VaadinRequest request) { - setContent(new MyViewDesign()); - } -} ----- - - -[[application.declarative.composite.viewnavigation]] -=== Designs in View Navigation - -To use a design in view navigation, as described in -<<dummy/../../../framework/advanced/advanced-navigator#advanced.navigator,"Navigating -in an Application">>, you just need to implement the [interfacename]#View# -interface. - - -[source, java] ----- -@DesignRoot -public class MainView extends VerticalLayout - implements View { - public MainView() { - Design.read(this); - ... - } - ... -} - -... -// Use the view by precreating it -navigator.addView(MAINVIEW, new MainView()); ----- - -See -<<dummy/../../../framework/advanced/advanced-navigator#advanced.navigator.urifragment,"Handling -URI Fragment Path">> for a complete example. - - - - - |