RCPML Forms Tutorial

Introduction

This guide has been written to help you write your first form application using RCPML.

RCPML or Rich Client Platform Markup Language, is a technology with which you can build custom user interface xml based language, fast and easy.

The guide represents the state of org.rcpml.forms plugin with implementation of Eclipse Forms like language.

It is possible that some aspects of the language will slightly change until final release.

Layouting in RCPML are specified in css styleshets. Ways to add and describe them, would be described in another document.

When Eclipse platform was designed, there were two distinct context in which widgets could appear:

In traditional dialogs (message boxes, dialogs, wizards, preference pages, property pages)
In content areas (views and editors)

Controls in views and editors were 'stretchy' i.e. they filled the entire content area. Stretchy controls can scroll their content (trees, tables, text areas, lists etc.). The colors and fonts used here were those provided by the system for use in content area.

What was missing was the third option where widgets you would normally see in the dialog context are created in views or editors (where you would expect 'stretchy' controls).

RCPML forms technology provides:

A concept of a 'form' that is suitable for inclusion into the content area (editor or view)
Custom controls designed to fit into the form (hyperlink, image hyperlink, scrollable composite, section)
Multi-page editor where each page is a form (as in PDE).
User interface are specified in xml like language.
Scripts like JavaScript may be used to add some logic.

Setup

In order to be able to use RCPML Eclipse Forms language, all you need to do is add "org.rcpml.core" plug-in to your list of required plug-ins.

API packages

Eclipse Forms has the following public (API) packages:

org.rcpml.core - the main package.
org.rcpml.forms - forms namespace implementation.
org.rcpml.example.forms - forms examples.

Getting Started

We will start playing with RCPML Eclipse Forms by creating an empty form in a view. As we said above, views are content areas that require flexible content. Here is the code sample:

<?xml version="1.0"?>
<view xmlns="http://rcpml.org/forms">
        <form title="This is RCPML Form"/>
</view>

In the snippet above, we have created a view.
When we register this view with the workbench and run (please see Simple RCPML Plugin Example), we get the following:

The form we just created does the following things:

It render the title we set using title attribute
It can render a background image behind the title
The title will wrap if there is no space to show it on one line
The form will introduce scroll bars if the content cannot be shown in the provided space

The last item in the list needs some clarification. In some instances, you will want to make the form be a child of a more complex layout that is itself capable of scrolling. In that case, you may want to get all the capabilities of a form, but without scrolling. In that case you can set "scroll" attribute of form to "true"

Adding content

Now that we have the form view running, we can start adding some content to it. Eclipse forms have a body and all the content should be created there:

<?xml version="1.0"?>
<view xmlns="http://rcpml.org/forms">
	<form title="This is RCPML Form">
		<hyperlink onclick="java.lang.System.out.println('Link activated');">Click here.</hyperlink>
	</form>
</view>

Hyperlink control is one of the custom widgets in Eclipse Forms and acts like a label that is clickable. To set action hyperlink has a onclick attribute in witch you can write javascript handler. Handling events of the hyperlink are very similar to other elements, as shown in the code above. Our view now looks like this:

Note how hyperlink has focus rectangle painted around it. When the view is activated, focus is transferred to the form, which passes it to the first control capable of accepting focus, our link in this case.

Creating common controls

One of the design goals of RCPML Eclipse Forms was to allow common controls to be created in the editor/view content space. Since form is a normal control, you can use any layout and control you want inside it. We will now create some using their constructors by continuing the method above:

<?xml version="1.0"?>
<ui:view xmlns="http://rcpml.org/forms" xmlns:ui="http://rcpml.org/ui" xmlns:core="http://rcpml.org/core">

	<core:style type="text/css">
		form#myform {rcpml-layout:grid;rcpml-layout-columns:2;}
		form#myform > hyperlink {rcpml-colspan:2}
		form#myform > text {rcpml-fill:horizontal;rcpml-grab:horizontal;}
		form#myform > checkbox { rcpml-colspan:2; }
	</core:style>
	
	<form id="myform" title="This is RCPML Form">
		<hyperlink>Click here</hyperlink>		
		<label>Text field label:</label>
		<text/>
		<checkbox title="An example of a checkbox in a form"/>
	</form>		
</ui:view>

We are now using two columns and creating a label, a text field and a checkbox. The result is below:

Control Wrapping.

After appying another layout style, and changing hyperlink into Label we can check wrapping capabilities of label.

Here is the code sample:

<?xml version="1.0"?>
<ui:view xmlns="http://rcpml.org/forms" xmlns:ui="http://rcpml.org/ui" xmlns:core="http://rcpml.org/core">

	<core:style type="text/css">
		form#myform {rcpml-layout:wrap;rcpml-layout-columns:2;}
		form#myform > label.long {rcpml-wrap:true;rcpml-colspan:2;}
		form#myform > text {rcpml-fill:horizontal;rcpml-grab:horizontal;}
		form#myform > checkbox { rcpml-colspan:2; }
	</core:style>
	
	<form id="myform" title="This is RCPML Form">
		<label class="long">This is an example of a form that is much longer and will need to wrap.</label>		
		<label>Text field label:</label>
		<text/>
		<checkbox title="An example of a checkbox in a form"/>
	</form>
</ui:view>

Let's see the result on screen:

This is more like it. Then we apply styles, text control will grab the excess space in its column, and both the checkbox and the label will just spread across both columns. In addition, label will not try to render in one long line - it will take the view width and push the rest of the content down in order to wrap.

Let us take a closer look at the space distribution with the following code:

<?xml version="1.0"?>
<ui:view xmlns="http://rcpml.org/forms" xmlns:ui="http://rcpml.org/ui" xmlns:core="http://rcpml.org/core" >
	<core:style type="text/css">
		form#myform {rcpml-layout:wrap; rcpml-layout-columns:3;}
		form#myform > label {rcpml-wrap:true;}
		form#myform > label.fill {rcpml-fill:horizontal;rcpml-grab:horizontal;}
		form#myform > label.hfill {rcpml-fill:horizontal;}
		form#myform > label.cspan {style="rcpml-colspan:2;"}
		form#myform > label.rspan {style="rcpml-rowspan:2;"}
	</core:style>
	
	<form id="myform" title="This is RCPML Forms, Labels Test">
		<label>
			Some text to put in the first column
		</label>
		<label class="cspan">
			Some text to put in the second column and make it a bit longer so that we can see what happens with column distribution. 
			This text must be the longest so that it can get more space allocated to the columns it belongs to.
		</label>		
		<label class="rspan">
			This text will span two rows and should not grow the column.
		</label>
		<label class="fill">
			This text goes into column 2 and consumes only one cell.
		</label>
		<label class="hfill">
			This text goes into column 3 and consumes only one cell too
		</label>
		<label class="fill">
			This text goes into column 2 and consumes only one cell.
		</label>
		<label class="hfill">
			This text goes into column 3 and consumes only one cell too.
		</label>		
	</form>
</ui:view>

The code above creates a number of labels with wrapping style, with text of variable length. Some labels has span styles. To make the test easier, we will set the form background to widget background so that cells will be easy to spot. When we run the example, we will get the following:

Column View

If you configure style of form to place children vertically (in columns), and to make all controls the same with within the column, we would get several columns (depending on the width of controls), but the last column would typically not be completely filled (depends on the number of controls). Again, if placed in a form, we would get all the controls in one column.

There are situations in more complex forms where we want the number of columns to be adaptive. In other words, we would like it to change depending on the width of the form - use more when possible, drop the number down if the width decreases. We would also like to fill the form area more-less equally (with all the columns roughly the same height). All this can be achieved with ColumnLayout.

The only choice you need to make is the range of columns you want to have (default is 1 to 3). The following example shows a form with a large number of sections (we will talk about sections later). Since there is enough space, three columns are used.
Lets see following code:

<?xml version="1.0"?>
<ui:view xmlns="http://rcpml.org/forms" xmlns:ui="http://rcpml.org/ui" xmlns:core="http://rcpml.org/core">
	<core:style type="text/css">
		form#myform {rcpml-layout:column; rcpml-layout-columns:3}
		form#myform > section > text { rcpml-fill:horizontal;rcpml-grab:horizontal; }
	</core:style>
	
	<form id="myform" scroll="true" title="Form with wrapped sections.">
		<section title="Link section:0" description="An example of a section with links">
			<link>Hyperlink text 1</link>
			<link>Hyperlink text 2</link>			
		</section>
		<section title="Link section:1" description="An example of a section with links">
			<link>Hyperlink text 1</link>
			<link>Hyperlink text 2</link>
		</section>
		<section title="Sample section:2" description="An example of a section with links">
			<link>Hyperlink text 1</link>
			<link>Hyperlink text 2</link>
			<link>Hyperlink text 3</link>
		</section>
		<section title="Sample section:3" description="An example of a section with links">
			<link>Hyperlink text 1</link>
			<link>Hyperlink text 2</link>
			<link>Hyperlink text 3</link>
			<link>Hyperlink text 4</link>
		</section>
		<section title="Mixed Sample section:4" description="An example of a section with links">
			<link>Hyperlink text 1</link>
			<link>Hyperlink text 2</link>
			<link>Hyperlink text 3</link>
			<link>Hyperlink text 4</link>
			<label> This is Label</label>
			<text> This is Edit</text>	
		</section>
		<section title="Mixed Sample section:5" description="An example of a section with links">
			<link>Hyperlink text 1</link>
			<link>Hyperlink text 2</link>
			<link>Hyperlink text 3</link>
			<link>Hyperlink text 4</link>
			<label>This is Label</label>
			<text> This is Edit</text>	
			<link>Hyperlink text 5</link>
		</section>
		<section title="Link section:6" description="An example of a section with links">			
			<link>Hyperlink text 1</link>
			<link>Hyperlink text 2</link>			
		</section>
		<section title="Link section:7" description="An example of a section with links">
			<link>Hyperlink text 1</link>
			<link>Hyperlink text 2</link>
		</section>
		<section title="Sample section:8" description="An example of a section with links">
			<link>Hyperlink text 1</link>
			<link>Hyperlink text 2</link>
			<link>Hyperlink text 3</link>
		</section>
	</form>
</ui:view>

When we run the example, we will get the following:

The sample exact example will drop the number of columns to two when the form is narrowed:

Controls are laid out top-down, left to right. One column is filled, then then the next one etc. However, the space computation first ensures that each column is roughly the same height so that space is used rationally.

You can still tweak the sizing of the individual controls when using using layout style. For example, if the control is 'stretchy', you may want to limit its width or height by setting width or height hint. By default, controls 'fill' the width of the column, but you can change that by choosing left, center or right.

Add Labels
Enter labels to add to this page: Looking for a label? Just start typing.