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 and Product. 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
layout UI defines a web page (when the layout is not part of another layout)
display UI defines a section of a web page, a display is referenced by a layout
toolbar UI defines a toolbar that is going to be linked to a 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 Test A test defines a test case that includes some test steps. A JUnit test class and a few utility classes that support the test execution are generated.

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.

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

  • 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 Modules = MyUiModule1, MyUiModule2;
}

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

Info

The option Modules is going to be deprecated. It will be replaced with the option UserInterfaces in a future version of the generators. The modeled capability will then look like this:

capability MyCapability {
    link UserInterfaces = MyUiModule1, MyUiModule2;
}

A set of modeling concepts are not (yet) supported by the generator JSF Web-Fragment: databinding, flow, interfaces, local-storage, menu, view. 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

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.

Modeled Component Generated JSF Tag
Button <p:commandButton>
Link <p:commandLink>

When ActionPurpose is set to Navigate, a <h:outputLink> is generated instead.
BooleanChoice <p:selectBooleanCheckbox> (default)
<p:selectBooleanButton>
<p:inputSwitch>
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>
EmbeddedComponentGroup <h:panelGroup>
EmbeddedContainer <h:panelGroup>
FileUpload <p:fileUpload>
HTML <p:editor>

<p:editor> is deprecated since PrimeFaces 6.0.6
<p:textEditor> will be used in future releases of the JSF Web-Fragment generator.
Image <p:graphicImage>
Label <p:outputLabel>

<h:outputText> when it is used in a display of type List
Map <p:gmap>
Range <p:slider> or <p:spinner>
depends on the generator option ‘component-type-range’ (SLIDER or SPINNER)
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

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.

Note

The following explanations will not cover concepts that are not (yet) supported.

Capability

Option Default Value Effect
ConfigurationItems none not yet used
ProvidedServices none not relevant for web applications
ConsumedServices none not relevant for web applications
Storage none not relevant for web applications
DefaultStorage none not relevant for web applications
BusinessLogic none not relevant for web applications
DefaultBusinessLogic none not relevant for web applications
Modules none references modeled modules that contain layouts (= web pages)
files will only be generated for modules that are referenced like this
UserInterfaces none not yet implemented, will replace Modules in the future
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
IoTApplications none not relevant for web applications

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

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. It is not yet used in the generators.
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, Custom.

Form => <p:panelGrid>
List => <p:dataTable>
Grid => not yet supported
Custom => intentionally, there is nothing generated for this
FieldsWithImplicitComponents none not yet supported
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 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 not yet supported

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.
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 by the DTOs for UI generator. The generators JPA and EJB 3 CRUD create code for the modeled entities as well. That generated code and the DTO classes are then being used for the data binding.
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 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.
DataType none In cases where the EntityField option is not set, this option can be used as a hint for the DTOs for UI 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 used.
LongLasting false Defines, whether clicking the button/link will trigger a long lasting process. This is not yet used.
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

Undefined => no special handling
Store => not yet used
Cancel => <p:commandButton immediate='true' resetValues='true'>
Delete => not yet used
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

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, this is not yet used by the generators
CustomMessage none possible values: Required, Conversion, Validation, this is not yet used by the generators

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/edited.
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 is not yet used by the generator. It is meant to generate code that allows a user to make another window/dialog/overlay appear when she clicks on the UI component. The code that gets generated for the referenced layout or display produces the code to be used for the window/dialog/overlay.
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, this is not yet used by the generators

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 This feature is not yet used. Possible values are: Date, Time, DateTime, Timestamp.
CustomMessage none possible values: Required, Conversion, Validation, this is not yet used by the generators

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, this is not yet used by the generators

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 provide any options.

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, this is not yet used by the generators

for more information see the feature documentation ‘Messages & Dialogs’

TextArea

Option Default Value Effect
CustomMessage none possible values: Required, Conversion, Validation, this is not yet used by the generators

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, this is not yet used by the generators

for more information see the feature documentation ‘Messages & Dialogs’

Video

This component does not provide any options.

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

Component Comment
<p:triStateCheckbox> not yet supported
<p:toggleSwitch> not yet supported
<p:chips> not yet supported
<p:datePicker> not yet supported
<p:colorPicker> not yet supported
<p:knob> not yet supported
<p:rating> not yet supported

Button

Component Comment
<p:link> not yet supported
<p:button> not yet supported
<p:splitButton> not yet supported
<p:linkButton> not yet supported

Data

Component Comment
<p:dataGrid> not yet supported
<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
<p:tree> not yet supported
<p:treeTable> not yet supported
<p:timeline> not yet supported

Messages

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

File

Component Comment
<p:fileDownload> not yet supported

Dialog Framework

The PrimeFaces dialog framework is not yet supported at all by the modeling languages and the generators. To generate something that uses the dialog framework, first the modeling language needs to be extended.