chapter:Components[Components]

This section describes the components that are provided to be used out-of-the-box, that are the foundations for all parts built upon e[EMF Parsley].
Afetr a brief description, for each component we present a set of customizations, just to give an idea of how it works. You can refer
to ref:Customizations[Customizations Section] for a complete list.

Components and viewers have to be created using the factories we provide
(e.g., for viewers we provide codeRef[org.eclipse.emf.parsley.viewers.ViewerFactory]);
such factories provide specific e[create] methods that require all the needed parameters.
These factories must be injected.

section:FormComponent[Form Component]

The e[Form Component] can be used to rapresent an codeRef[org.eclipse.emf.ecore.EObject] in a form,
like in the image above.

img[images/03-components-form.png][][ ][]

e[EMF Parsley] provides a factory that can be used to create such a component, like in the code below.
Here you can see that a form can be configured in 2 lines, the constructor phase and the build&fill phase. 

code[Java][
@Inject FormFactory formFactory;

(...)

formComposite = formFactory.createFormDetailComposite(parent, SWT.NONE);
formComposite.init(eObject);
]

Most of the job is done by the second line of code, which gets the list of codeRef[org.eclipse.emf.ecore.EStructuralFeature] defined
for the codeRef[org.eclipse.emf.ecore.EClass]
(that is the type of the object to represent) and builds a row for each of them. Each row is composed
by a e[caption] which defaults to the name of the feature and a e[control] to access the data. 

All these aspects can be customized in many ways, for example you can customize the feature list, the captions and the controls.  


section2:FormComponent_features[Feature List Customization]

The e[list of features] displayed on the form can be customized via the ref:FeaturesProvider[Feature Provider] 
that returns the list of the features (in a given order).

section2:FormComponent_captions[Caption Customization]

The captions of the features shown in the form can be customizzed via the ref:FormFeatureCaptionProvider[Form Feature Caption Provider].

section2:FormComponent_controls[Control Customization]

The Controls in the form can be customized via the ref:FormControlFactory[Form Control Factory].

section2:FormComponent_proposals[Proposal Provider]

Depending on the feature types, some fields can have predefined values (e.g. combo). 
You can provide the exact proposal list via the ref:ProposalProvider[Proposal Provider]


section:TreeComponent[Tree Component]

The e[Tree Component] provides a tree representation of data that can be fed with an EResource, a
Resource URI, and a simple EObject. This component uses the EMF Meta-Model information to display objects in the tree. 

img[images/03-components-tree.png][][ ][]

e[EMF Parsley] provides a factory that can be used to create such a component, like in the code below:

code[Java][
@Inject ViewerFactory viewerFactory;

(...)

treeViewer = new TreeViewer(parent);
viewerFactory.initialize(treeViewer, element);
]


The e[Tree Component]can be customized in several way via the standard EMF Edit facilities or with the EMF Parsley 
codeinjection based mechanism. If you are familiar with Jface APIs, you can easily use the basic class with some facilties to define the specific implementation. 
See the corrisponding sections for more details.


section2:Tree_ContentProvider[Content Provider]

An IContentProvider is used in Jface to retrieve the list of e[elements] and e[children] to be showed
in the tree viewer. The ref:ViewerContentProvider[Viewer Content Provider] is the e[EMF Parsley] implementation of that interface,
and by default uses the containment mechanisms to provide children as in EMF Edit framework, but it can
be customized as weel.

section2:Tree_LabelProvider[LabelProvider]

The ref:ViewerLabelProvider[Viewer Label Provider] is the implementation of an ILabelProvider interface
and is responsible to provide the text and image representation for each EObject visualized.

section2:Tree_MenuBuilder[Adding Menu]

The contextual menu can be added to the viewer via an injected
codeRef[org.eclipse.emf.parsley.menus.ViewerContextMenuHelper], as explained in the ref:ContextualMenu[Menu section].
The ref:MenuBuilder[Menu Builder] allows to fully customize the menus.

section:TreeFormComponent[Tree Form Component]

The e[Tree Form Component] contains a ref:TreeComponent that provides a tree representation of data that can be fed with
an EResource, a Resource URI, and a simple EObject. This component uses the EMF Meta-Model information to display objects in 
the tree. The component also combines a ref:FormComponent detail that display the current selected object.

img[images/03-components-treeform.png][][ ][]

e[EMF Parsley] provides a factory to create such a component.

code[Java][
@Inject TreeFormFactory treeFormFactory;

(...)

treeFormComposite = treeFormFactory.createTreeFormComposite(parent, SWT.BORDER);
treeFormComposite.update(application);
]

Since e[Tree Form Component] is a combination of  e[Tree Component] and  e[Form Component], all their customizations
are avaible for it.

section:TableComponent[Table Component]

The e[Table Component] can rapresent data in a grid, once you have specified the type of objects to represent. 
It uses metamodel information to build columns as needed, and a
codeRef[org.eclipse.emf.parsley.edit.ui.provider.TableViewerContentProvider] to retrieve
the contents of the specified type (see also ref:TableViewerContentProvider[]).

img[images/03-components-table.png][][ ][]

code[Java][
@Inject ViewerFactory viewerFactory;

(...)

tableViewer = viewerFactory.createTableViewer(composite, SWT.BORDER | SWT.FULL_SELECTION, eClass);
]

The class codeRef[org.eclipse.emf.parsley.viewers.TableViewerColumnBuilder] has the responsibility to
build the columns of the Table, by using the ref:FeaturesProvider[Features Provider] to get the list
of features and the ref:FeatureCaptionProvider[Feature Caption Provider] for the column headers.
The class codeRef[org.eclipse.emf.parsley.ui.provider.TableColumnLabelProvider] can be used to specify
an implementation of ILabelProvider for each cell in the table. 

section2:Table_features[Feature List Customization]

The e[list fo features] displayed on the table can be customized via the ref:TableFeaturesProvider[Table Feature Provider].
This list of features will be used for building the columns of the table.

section2:Table_captions[Caption Customization]

The headers of the table can be customizzed via the ref:FeatureCaptionProvider[Caption Provider].

section2:Table_columns_width[Column width Customization]

All columns have the same size by default, but they can be customizzed via the ref:Configurator[Configurator]
for instance in the DSL, like in the example below.

code[EmfParsley][

bindings{
	value List<Integer> TableColumnWeights -> #\[10,20,30,40\]
}
]

section2:Table_MenuBuilder[Adding Menu]

The contextual menu can be added to the viewer via an injected
codeRef[org.eclipse.emf.parsley.menus.ViewerContextMenuHelper], as explained in the ref:ContextualMenu[Menu section].
The ref:MenuBuilder[Menu Builder] allows to fully customize the menus.

section:TreeWithColumnsComponent[Tree With Columns Component]

The e[Tree With Columns Component] provides a tree representation just like ref:TreeComponent[Tree Component],
but it also shows table columns representing the features of the specified codeRef[org.eclipse.emf.ecore.EClass].

IMPORTANT: the codeRef[org.eclipse.emf.ecore.EClass] is used to retrieve the features to be shown, and
NOT to filter elements to be shown (as opposite to the ref:TableComponent[Table Component]).  If a given
row in the tree represents an object whose class does not have the feature for a given column, then the
corresponding table cell for that object will be empty.

For example, the following screenshot shows a tree with columns representing a library; the specified
codeRef[org.eclipse.emf.ecore.EClass] is the e[Writer] so the columns show the features of the
e[Writer]'s class.  Some of these features, e.g., e[address], e[firstName] and e[lastName], are defined
in the superclasses of e[Writer].  The objects of class e[Employee] have these features as well, while
they don't have features that are specific of e[Writer], e.g., e[name] and e[books], thus the corresponding
cells for employees will be empty.

img[images/03-components-treecolumns.png][][ ][]

e[EMF Parsley] provides a factory that can be used to create such a component, like in the code below:

code[Java][
@Inject ViewerFactory viewerFactory;

(...)

treeViewer = createTreeViewerWithColumns(parent, getEClass(), getContents());
]

Since this component mixes the features of a tree and a table, the customizations are basically the
same shown in the subsections of ref:TreeComponent[] and ref:TableComponent[].