Skip to content

Modeling

Introduction

You can find general information about the Virtual Developer Modeler by visiting its online documentation. The page you are looking at right now teaches you how a model’s elements affect the generated code. The generator JSF Web-Fragment processes models that are made with the DSLs Basic, UI, Product and Testing. It processes a subset of the DSLs’ modeling concepts. In the following sections all modeling concepts are mentioned, along with the information as to whether they are handled or not.

Main Modeling Concepts

Concept/Keyword DSL Description
view UI defines a web page, all options for a layout can be applied to a view, too
layout UI defines the structure of the web page or of a part of the web page
display UI defines a section of a web page, a display is referenced by a layout or view
toolbar UI defines a toolbar that is going to be linked to a view, layout or display
component UI defines a ui component that is part of a section of a web page
capability Product A capability defines a business capability and has references to other model elements that belong to the business capability. A capability represents the web fragment where all the generated files will be bundled in.
feature Product features can be modeled and linked to a capability. The generator creates a Java enumeration that holds entries for all modeled features and a mechanism to switch features on and off by manually writing code in a generated web application.
type Basic A type defines a type with some typed fields. Typically, a simple Java class is generated for this model element. Its purpose is to provide data for the configuration of web pages, web fragments and web applications.
enumeration Basic An enumeration defines an enumeration. Typically, a Java enum is generated for this model element. Its purpose is to support the configuration of web pages, web fragments and web applications.
test Testing A test defines a test case that includes some test steps. A JUnit test class and some utility classes that support the test execution are generated.

A web page is modeled by defining a tree structure of view, layouts, displays, toolbars and components.

  • A view can have layouts or displays as children. view features the modeling option Children for this purpose: link Children = Layout2, Display2;
  • A layout can have layouts or displays as children. layout features the modeling option Children for this purpose: link Children = Layout2, Display2;
  • A display can have components assigned to them. display features the option component for this purpose: component FirstName : TextField;
  • toolbars can be assigned to layouts and displays. layout and display feature the option Toolbar for this purpose: link Toolbars = MainToolbar;
  • components can be assigned to displays and toolbars, as mentioned in one of the previous points.

A capability references a set of modules that contain modeled web pages:

capability MyCapability {
    link UserInterfaces = MyUiModule1, MyUiModule2;
}

With this, a set of web pages is defined that belongs to the business capability.

Note

A set of modeling concepts are not (yet) supported by the generator JSF Web-Fragment: databinding, flow, interfaces, local-storage, menu. You can still model them, but they should not affect the generation output. In future versions of the generators some of those options will be evaluated.

Available UI Components

The following table shows a complete list of UI components that you can model. When there in principle is more than one possible JSF tag for a modeled component, then you can select one of them either by setting another option in the model or by setting a generator option. Setting a generator option makes a default choice. The generator will make that choice for all modeled components of the corresponding component type.

Note

Clicking on the XHTML tag leads you to the related documentation on the web.

Modeled Component Generated JSF Tag
Button <p:commandButton> clicking the button makes an AJAX call

<p:button> when set NavigationTarget = [view-name] Open; or
set ActionPurpose = Navigate; is modeled. In such a case an AJAX call is not needed and the page to open on a button click is already known when the page has finished loading and is going to be opened in a new browser tab/window.
Link <p:commandLink>

<p:link> when set NavigationTarget = [view-name] Open; is modeled. In such a case an AJAX call is not needed and the page to open on a click on the link is already known when the page has finished loading and is going to be opened in a new browser tab/window.

<h:outputLink> when set ActionPurpose = Navigate; is modeled. The same rules as for <p:link> apply. Use this when you want to get a link that leads to a web page that is not part of your web application.
BooleanChoice <p:selectBooleanCheckbox> (default setting CHECKBOX for the generator option ‘component-type-boolean-choice’)

<p:selectBooleanButton> when generator option ‘component-type-boolean-choice’ is BUTTON

<p:inputSwitch> when generator option ‘component-type-boolean-choice’ is INPUT_SWITCH

Note that there is a modeling option to get individual control over the component type to be generated.
Choice selection of a single item when set Multiplicity = SingleValued; (this is the default value):

<p:selectOneMenu> … when set ChoiceType = DropDown;
<p:selectOneRadio> … when set ChoiceType = Check;
<p:selectOneListbox> … when set ChoiceType = List;
<p:selectOneButton> … when set ChoiceType = Button;
<p:multiSelectListbox> … this is not yet supported


selection of multiple items, when set Multiplicity = MultiValued;:
<p:selectManyMenu> … when set ChoiceType = List;
<p:selectManyCheckbox> … when set ChoiceType = Check;
<p:selectManyButton> … when set ChoiceType = Button;
<p:selectCheckboxMenu> … when set ChoiceType = DropDown;

<p:pickList> … when set ChoiceType = PickList;

<p:autoComplete> … when set ChoiceType = AutoComplete;
DateSelector <p:calendar>

Note that <p:datePicker> is going to be supported soon. <p:datePicker> is available since PrimeFaces 7 and is designed to replace <p:calendar>.
EmbeddedComponentGroup <h:panelGroup>

This component lets you place a display within a form or a table.
EmbeddedContainer <h:panelGroup>

This component lets you place a layout or even a complete view within a form or a table.
FileUpload <p:fileUpload>
HTML <p:textEditor>

Note that <p:textEditor> replaces the deprecated <p:editor>
Image <p:graphicImage> or <o:graphicImage>, depending on the setting for the generator option ‘jsf.graphic-image-implementation’ (PRIMEFACES or OMNIFACES).

<o:graphicImage> has an easier programing model and comes with features that <p:graphicImage> doesn’t provide, e.g. explicit caching support (attribute ‘lastModified’) and SVG view modes (attribute ‘fragment’).
Label <p:outputLabel>

<h:outputText> when it is used in a display of type List, Tree or TreeTable or when it is used in a display of type Form and set Format = Html; is not set.
Map <p:gmap>
Range <p:slider> or <p:spinner>, depends on the generator option ‘component-type-range’ (SLIDER or SPINNER). <p:spinner> is the default component here.
TextArea <p:inputTextarea>
TextField <p:inputText>

<p:password> in case the Password option is set to true

<p:inputMask> in case an input mask is set for the option InputMask
Video this component is not yet supported
Timeline <p:timeline>
Tree <p:tree>
Chart <p:chart> when generator option ‘version.primefaces’ is set to a version lower than ‘PF_7’.

When a PrimeFaces version 7 or higher is targeted, more modern chart components are going to be generated:
<p:barChart>
<p:bubbleChart>
<p:donutChart>
<p:lineChart>
<p:pieChart>
<p:scatterChart>
<p:polarAreaChart>
<p:radarChart>

The type of the chart is defined by using the modeling option ChartType. Possible values are: Bar, PolarArea, Bubble, Radar, Donut, Line, Pie, Scatter.

Model Customization

Apart from doing structural modeling of web pages, as outlined in the previous section, you can fine-tune the model by using other options. You don’t necessarily need a deep technical understanding of Java Server Faces to use those options. Instead, they are meant to be used to define requirements in a way it could also be done by non-technical staff, e.g. project managers or even customers.

Capability

Option Default Value Effect
ConfigurationItems none defines capability-wide configuration items, this is not yet implemented
ProvidedServices none not relevant for web applications, see Capability generator for more information
ConsumedServices none not relevant for web applications, see Capability generator for more information
Storage none not relevant for web applications, see Capability generator for more information
DefaultStorage none not relevant for web applications, see Capability generator for more information
BusinessLogic none not relevant for web applications, see Capability generator for more information
DefaultBusinessLogic none not relevant for web applications, see Capability generator for more information
Modules none deprecated, use UserInterfaces instead
UserInterfaces none references modeled modules that contain views
files will only be generated for modules that are referenced like this
Features none references modeled features, generates one enumeration [capability‑Name]Feature.java that has an entry for every referenced feature

use the method
Boolean isFeatureActive([capability-Name]Feature feature) in Abstract[capability‑Name]ManagedBean.java to check whether a feature is active or not, features can be individually en-/disabled in each web application
UiApplications none determines which web applications belong to the capability, this does not yet affect any generated code
ServiceApplications none not relevant for web applications, see Capability generator for more information
IoTApplications none not relevant for web applications, see Capability generator for more information

View

Option Default Value Effect
Menus none This option links menus to a view. With this you can define view-specific menus.

This is not yet implemented.

Layout

Option Default Value Effect
ConfigurationItems none references a modeled type, generates the inner class Configuration in the file [layout‑Name]BeanCustomization.java

use the method getConfigurationItems() to get the actual configuration values, the configuration values can be individually set in each web application
LayoutVariants none references a modeled enumeration, to nominate layout variants for one and the same web page

see feature documentation ‘Web Page Layout Variants’ for more information
Orientation TopToBottom Determines the orientation of a layout container, possible values: TopToBottom, LeftToRight
Type Split determines which JSF component to be used to structure the page, possible values: Tab, Split, Wizard

Tab ⇒ <p:tabView>
Split ⇒ <p:panelGrid>
Wizard ⇒ <p:wizard>
DynamicStructure false this is not yet implemented in the generator

If the option is set to true, the usage of <pe:dynaForm> will be generated in the future.
Features none references modeled features, the generator does not yet make use of this information
Optional false if set to true, the generated JSF tag gets an attribute rendered=#{...} generated

see feature documentation ‘Optional UI Components’ for more information
Disablable false For layouts the only tag that feature the disabled semantics is <p:tab> which is used as nested tag for <p:tabView> and <p:wizard>. Setting this option to true doesn’t make a difference, though. The generator always creates a disabled=#{...} for every <p:tab>, no matter what’s found in the model.
Services none references modeled interfaces, this option is not yet used in the generators
TestPreludeViews none Nominates views that are going to be accessed from within the prelude test logic.

Example: Login to an application (login view), then search for an item (search view), then edit that item. Login and search views are prelude views for the ‘edit item’ view.
CustomTitle none If this is set to true, the titles of a view, e.g. a tab view or a wizard, are not simple labels but contain more complex UI components (circles, numbers, …).

This is implemented only for wizard.

Display

Option Default Value Effect
SelectionMode None This sets the selection mode for a modeled display with Type = List. As a result, the selectionMode attribute of <p:dataTable> is set to the corresponding value.
Entity none This references a modeled entity. You have to set an entity when you are going to set the option ==EntityField= on a display’s components.
Function none This references a modeled function.
It is not yet used in the generators.
Type Form Sets the type of a display. Possible values: Form, List, Grid, TreeTable, Tree, Custom.

Form ⇒ <p:panelGrid>
List ⇒ <p:dataTable>
Grid ⇒ <p:dataGrid>
TreeTable ⇒ <p:treeTable>
Tree ⇒ <p:tree>
Custom ⇒ intentionally, there is nothing generated for this
FieldsWithImplicitComponents none Assigning fields to this option implicitly creates matching components on the fly, e.g. a <p:selectBooleanCheckbox> for a boolean-typed field.

This is not yet implemented.
DynamicStructure false If the option is set to true, the usage of <pe:dynaForm> is going to be generated.

This is not yet implemented.
Features none references modeled features, the generator does not yet make use of this information
Optional false if set to true, the generated JSF tag gets an attribute rendered=#{...} generated

see feature documentation ‘Optional UI Components’ for more information
Disablable false For a display, setting this option to true results in all ui component tags that are owned by the display and support the attribute disabled to get that attribute generated: disabled=#{...}.
SortBy none This option references UI components. When this is set, the <p:dataTable> and <p:treeTable> tags do get the attribute sortBy set.

Toolbar

Option Default Value Effect
Features none references modeled features, the generator does not yet make use of this information
Optional false if set to true, the generated JSF tag gets an attribute rendered=#{...} generated

see feature documentation ‘Optional UI Components’ for more information
Disablable false For a toolbar, setting this option to true results in all ui component tags that are owned by the toolbar and support the attribute disabled to get that attribute generated: disabled=#{...}.

Component

Note

You can manually add any JSF component tag to the generated file [layout-name]_[layout variant].xhtml and make it work together with the generated Java classes by also manually adding field and methods therein.

Generic Options

There are some options that can be set for any kind of modeled UI component. Those are documented in the following table.

Option Default Value Effect
Label none Sets the label of a user interface component. That label through codegeneration is becoming part of the application internationalization functionality. If you do not set this option, you will still get an entry in the properties files for internationalization, but with a default value that is identical to the properties file key.

The main purpose of this modeling option is to be able to imediately get a meaningful text being displayed on the web page.
EntityField none References an entity field. The field’s type determines the type of the field in the DTO class that’s going to be generated.

When you use this, you also have to model an Entity for the enclosing display, otherwise the generator will give you an error.
Optional false If set to true, code is generated that lets you programatically include or exclude a component on a web page. The attribute rendered=#{...} is going to be used for this purpose.
Disablable false If set to true, code is generated that lets you programatically disable a component on a web page. The attribute disabled=#{...} is going to be used for this purpose. If a component does not support disabled, the option is simply ignored.
WithoutLabel false By default all components that are part of a display of type Form, except for Button and Link, are getting a <p:outputLabel> generated. If under exceptional circumstances this is not desired, you have to set this option to true.
DataEntryRequired false If set to true, code is generated that lets you programatically make input being required for a component on a web page. The attribute required=#{...} is going to be used for this purpose. If a component does not support required, the option is simply ignored.

If this option is not set but the UI component has EntityField set to point to a required entity field, you still end up with a required field on the web page, being validated and displaying a ‘*’ next to the input field’s label.
DataType none In cases where the EntityField option is not set, this option can be used as a hint for the generator, to tell the generator what type to use for the corresponding DTO field.
ReadOnly false If set to true, code is generated that lets you programatically prevent hat a user enters something in the component (e.g. the text field). The attribute readonly=#{...} is going to be used for this purpose. If a component does not support readonly, the option is simply ignored.
Option Default Value Effect
DefaultAction false When this option is set to true, the tag <p:defaultCommand> is generated and references the button/link. As a result, the button/link will be clicked when the web page is open and a user presses the return key.
HasIcon false Defines, whether an icon should be displayed along with the button/link.

This is not yet implemented.
LongLasting false Defines, whether clicking the button/link will trigger a long lasting process, which needs a busy indicator to be displayed.

This is not yet implemented.
ActionPurpose Undefined With this option you can tell what the button/link is going to be used for. Possible values: Undefined, Store, Cancel, Delete, Navigate, Load, Create, Assign, Download

Undefined ⇒ no special handling
Store ⇒ not yet used
Cancel ⇒ <p:commandButton immediate='true' resetValues='true'>
Delete ⇒ a modal confirmation dialog is used before actually deleting something
Navigate ⇒ in case of a modeled link: <h:outputLink> instead of <p:commandLink> is generated
Load ⇒ not yet used
Create ⇒ not yet used
Assign ⇒ not yet used
Download ⇒ an additional <p:fileDownload> tag is generated

BooleanChoice

Option Default Value Effect
HandleSelectionEvent false true leads to the generation of an AJAX event-handler, see feature documentation ‘Event Handling’ for more information
BooleanChoiceType none possible values: Button, Check, Switch

Button ⇒ <p:selectBooleanButton>
Check ⇒ <p:selectBooleanCheckbox>
Switch ⇒ <p:inputSwitch>
CustomMessage none possible values: Required, Conversion, Validation
When for a view there is at least one component that has this options set, a method getCustomMessage is generated in the managed bean. This method is being called from requiredMessage, converterMessage or validatorMessage attributes.

For more information see the feature documentation ‘Messages & Dialogs’.

Choice

Option Default Value Effect
EntityFieldForDisplay none Explicitly links an entity field to a user interface component in order to tell the generator about the source of the data that is going to be displayed. Additional fields are going to be added to the generated DTO classes.
HandleSelectionEvent false true leads to the generation of an AJAX event-handler, see feature documentation ‘Event Handling’ for more information
Preselected false If this is set to true, one of the available choices is preselected in the component and there is no ‘unselected’ choice provided.
Container none This option lets you point to a view that is going to be used to open a dialog wherein a user chooses an element to become the selected element of the choice component.

This is not yet implemented.
Multiplicity SingleValued Possible values are SingleValued and MultiValued. By setting this option you decide whether the UI component that the generator will generate code for supports selection of a single entry (e.g. <p:selectOneMenu> or multiple entries (e.g. <p:selectManyMenu>).
Editable false Setting this to true enables that manual entry of text in the UI component that is going to be generated for the modeled Choice. If the generated UI component does not support the manual entry of text, this option will simply be ignored.
ChoiceType DropDown Possible values are: Button, Check, DropDown, List, AutoComplete, PickList. By setting this option, you choose the type of the UI component that code gets generated for.
CustomMessage none possible values: Required, Conversion, Validation
When for a view there is at least one component that has this options set, a method getCustomMessage is generated in the managed bean. This method is being called from requiredMessage, converterMessage or validatorMessage attributes.

For more information see the feature documentation ‘Messages & Dialogs’.

DateSelector

Option Default Value Effect
HandleSelectionEvent false true leads to the generation of an AJAX event-handler, see feature documentation ‘Event Handling’ for more information
Type Date Possible values are: Date, Time, DateTime, Timestamp. Depending on the setting, a matching format will be set for the attribute pattern of <p:calendar>.
CustomMessage none possible values: Required, Conversion, Validation
When for a view there is at least one component that has this options set, a method getCustomMessage is generated in the managed bean. This method is being called from requiredMessage, converterMessage or validatorMessage attributes.

For more information see the feature documentation ‘Messages & Dialogs’.

EmbeddedComponentGroup

Option Default Value Effect
Display none References a modeled display. A <h:panelGroup> with nested UI components that correspond to the display’s components is added to the generated XHTML file. Note that the generated code doesn’t make use of <ui:include> but directly integrates the XHTML code in the web page’s XHTML file.
Orientation LeftToRight Determines whether the referenced display’s components should be layed out from left to right or from top to bottom. Possible values are: TopToBottom, LeftToRight.

EmbeddedContainer

Option Default Value Effect
Container none References a modeled display or layout. A <h:panelGroup>. The generator directly integrates the content of the related display or layout into the generated XHTML file. Note that the generated code doesn’t make use of <ui:include>.

FileUpload

Option Default Value Effect
CustomMessage none possible values: Required, Conversion, Validation
When for a view there is at least one component that has this options set, a method getCustomMessage is generated in the managed bean. This method is being called from requiredMessage, converterMessage or validatorMessage attributes.

For more information see the feature documentation ‘Messages & Dialogs’.

HTML

This component does not yet provide any options.

Image

This component does not yet provide any options.

Label

This component does not yet provide any options.

Map

This component does not yet provide any options.

Range

The PrimeFaces component type to be generated (<p:slider> or <p:spinner>) is controlled by the generator option component-type-range.

Note

There is a restriction in the modeling of Lower, Upper and Stepping options. Only integer values can be modeled. If you want to use floating point numbers you have to manually modify the generated code.

Option Default Value Effect
Lower 0 An integer value. This sets the lower boundary of the values that can be entered with a <p:slider> or <p:spinner> component.
Upper 100 An integer value. This sets the upper boundary of the values that can be entered with a <p:slider> or <p:spinner> component.
Stepping 1 An integer value. This sets the stepping to be used when values are going to be entered with a <p:slider> or <p:spinner> component.
CustomMessage none possible values: Required, Conversion, Validation
When for a view there is at least one component that has this options set, a method getCustomMessage is generated in the managed bean. This method is being called from requiredMessage, converterMessage or validatorMessage attributes.

For more information see the feature documentation ‘Messages & Dialogs’.

TextArea

Option Default Value Effect
CustomMessage none possible values: Required, Conversion, Validation
When for a view there is at least one component that has this options set, a method getCustomMessage is generated in the managed bean. This method is being called from requiredMessage, converterMessage or validatorMessage attributes.

For more information see the feature documentation ‘Messages & Dialogs’.

TextField

Option Default Value Effect
Password false If set to true, a <p:password> tag is generated instead of a <p:inputText>.
InputMask none This option defines an input mask for the input field. If this is set, a <p:inputMask> is generated instead of a <p:inputText>.
CustomMessage none possible values: Required, Conversion, Validation
When for a view there is at least one component that has this options set, a method getCustomMessage is generated in the managed bean. This method is being called from requiredMessage, converterMessage or validatorMessage attributes.

For more information see the feature documentation ‘Messages & Dialogs’.

Video

This component does not provide any options.

Timeline

Option Default Value Effect
HandleSelectionEvent false true leads to the generation of an AJAX event-handler, see feature documentation ‘Event Handling’ for more information

Tree

Option Default Value Effect
HandleSelectionEvent false true leads to the generation of an AJAX event-handler, see feature documentation ‘Event Handling’ for more information
Multiplicity SingleValued Possible values are SingleValued and MultiValued. By setting this option you decide whether the UI component that the generator will generate code for supports selection of a single entry or for multiple entries in <p:tree>.

Chart

Option Default Value Effect
HandleSelectionEvent false true leads to the generation of an AJAX event-handler, see feature documentation ‘Event Handling’ for more information
ChartType Bar Possible values are Bar, PolarArea, Bubble, Radar, Donut, Line, Pie, Scatter. PolarArea, Radar and Scatter are not supported when the generator targets the PrimeFaces version < 7.

When the PrimeFaces version < 7 is set in the generator options, <p:chart> is going to be generated.

For PrimeFaces version >= 7, the more modern PrimeFaces components <p:barChart>, <p:polarAreaChart>, <p:bubbleChart>, <p:radarChart>, <p:donutChart>, <p:lineChart> are generated. Generation support for <p:scatterChart> is not yet available.

Unsupported JSF and PrimeFaces Components

The following tables lists unsupported JSF and PrimefFaces components. The table does not list all of them but the ones that are considered to be frequently used. The purpose of this list is to give some information about future plans and about alternatives that could be used.

Input

PrimeFaces Component     Comment
<p:triStateCheckbox> not yet supported
<p:toggleSwitch> not yet supported
<p:chips> not yet supported
<p:datePicker> not yet supported, replaces the older <p:calendar>, which is still supported, but <p:datePicker> has a better look and usability
<p:colorPicker> not yet supported
<p:knob> not yet supported
<p:rating> not yet supported

Button

PrimeFaces Component Comment
<p:splitButton> not yet supported
<p:linkButton> not yet supported

Data

PrimeFaces Component Comment
<p:dataView> not yet supported
<p:dataScroller> not yet supported
<p:orderList> not yet supported
<p:organigram> not yet supported
<p:mindmap> not yet supported
<p:schedule> not yet supported
<p:tagCloud> not yet supported

Messages

PrimeFaces Component Comment
<p:growl> There is no generation support, but it is used in the JSF templates in the open-source runtime library.
<p:messages> There is no generation support, but it is used in the JSF templates in the open-source runtime library.
<p:staticMessage> not yet supported

Dialog Framework

The PrimeFaces dialog framework is not supported at all by the modeling languages and the generators. You can manually write code to make use of it.

Note

There is generation support for dialogs. You can model dialogs exactly the same way as you model web pages. Then you use the option set NavigationTarget = [view-name] Push; that can be applied to buttons and links. The keyword ‘Push’ makes the generator create additional XHTML code to include a <p:dialog> within a web page.

You find more information about this in the feature documentation for dialogs.