doc/org.eclipse.emf.parsley.doc/xdoc/documentation/01-Overview.xdoc - emf-parsley/org.eclipse.emf-parsley - Git at Google

 chapter:Overview[Overview]

 e[EMF Parsley] is a lightweight framework that allows easy and quick UI development based
 upon EMF. e[EMF Parsley] is built on top of the EMF Edit framework and it implements features like Trees, Forms and Table builders with
 standard JFace databinding, providing a complete component-based toolset.
 EMF Parsley can be configured to use all kinds of EMF persistence
 implementations (XMI, Teneo, CDO)
 Moreover a DSL allows to easily customize several behaviors in each component.

 section:ParsleyComponents[Parsley Components]

 e[EMF Parsley] aims to provide a complete set of components to visualize your model with the introspective EMF capabilities
 and can be used to easily build forms, viewers or editors.

 There are some components that can be used out-of-the-box and can be considered as a reference implementation
 of the mechanisms that are the basis of e[EMF Parsley] itslef.

 ul[
 	item[e[Trees] ]
 	item[e[Forms] ]
 	item[e[Tables] ]
 	item[e[Editors] ]
 	item[e[Search boxes] (coming soon)]
 ]

 img[images/01-components.png][][ ][]

 section2:Customize[Customize]

 The main feature of e[EMF Parsley] is that you can customize all basic UI behaviours of the components with e[Dependency Injection]
 mechanisms (based on link[https://github.com/google/guice][Google Guice]).
 You can get more info in the ref:Customizations[Customizations Section], but you don't have to know all details
 about the internal implementation to inject your own customization because
 e[EMF Parsley] provides a DSL to easy customize your UI, as explained in the next section.

 section3:Customizations_DSL[Customize with the DSL]

 You can use the DSL by creating a new project with the wizard "Create a new project" -> "EMF Parsley DSL Based project"

 img[images/01-new-project-dsl-wizard.png][][ ][]

 Clicking the "Finish" button the wizard will open directly the DSL editor. You can use the content assistant
 to discover all features.

 img[images/01-dsl-content-assistant.png][][ ][]

 The DSL allows to customize the most relevant behaviors. Here we list only a few of them:

 ul[
 	item[e[parts] lets you define your View Parts: this will correspond to the standard Eclipse extension
 	points for the parts (see ref:PluginXml[How the DSL handles the plugin.xml])]

 	item[e[bindings] section lets you define which implementation will be used with Injection]

 	item[e[menu] section lets you define the contextual menu for all viewers (e[trees] and e[tables])]

 	item[e[features provider] is used to retrieve the list of feature for a given EClass to build e[tables]
 	and e[forms]]

 	item[e[viewer content provider] mediates between the viewer's model and the viewer, to provide the
 	contents to be shown]

 	item[e[Label Provider] is used to retrieve the image and text rapresentation of the objects of a
 	tree viewer]

 	item[e[Caption Provider] provides captions for each feature (namely, EStructuredFeature) of the object shown in a form,
 	in a dialog or in a table row.
 	Different implementations can be defined for e[dialogs], e[forms] and e[tables].]

 	item[e[Control Factory] provides a custom implementation of the Controls for each feature shown in a form or a dialog.
 	Different implementations can be defined forfor e[dialogs] and e[forms]]
 ]

 section3:DslProjectStructure[The structure of an EMF Parsley project]

 An EMF Parsley project, as created by the wizard, is an Eclipse plug-in project with a few
 additional builders.

 The e[emfparsley-gen] source folder will contain all the Java files generated by the DSL
 compiler.  The contents of this folder should never be modified manually, since their contents
 will be overwritten by the DSL compiler.

 The e[src] source folder will contain an codeRef[org.eclipse.ui.plugin.AbstractUIPlugin] generated
 by the wizard. This is generated only during the creation of the project and it can be safely modified
 if you need to put other mechanisms in the activator.

 IMPORTANT: it is crucial that the activator has the static method e[getDefault], so you must not remove
 that method.

 If you choose one of the templates provided by the wizard, the e[src] folder will also contain
 a Java class for the view, which extends the corresponding view of Parsley.  This can be safely modified
 if you need to add some additional mechanisms or contents to the view.

 You can then create additional e[.parsley] files in the same project.

 section3:PluginXml[How the DSL handles the plugin.xml]

 If you specify any e[part] in the DSL file, then
 the Parsley DSL will generate a e[plugin.xml_emfparsley_gen] in the e[emfparsley-gen] folder,
 in a directory named after the containing module.  Then, the e[EMF Parsley builder] will take
 care of merging the generated content with the e[plugin.xml] in the root folder of the current project.
 If the e[plugin.xml] does not exist it will create it.  Subsequent changes to the DSL file
 will regenerate e[plugin.xml_emfparsley_gen] and the builder will merge it with e[plugin.xml].
 The merging will overwrite in the e[plugin.xml] only the elements that are specified in the DSL.
 Any other elements in the e[plugin.xml] will not be touched, so you can also add other extension points
 manually in the e[plugin.xml].

 This merging takes place ONLY if your project has the e[EMF Parsley builder nature].
 Since version 0.6.1 this nature is automatically applied to the projects created with our wizard.
 In existing projects, you have to enable the nature yourself by right-clicking on the project,
 then "Configure" and then "Enable EMF Parsley builder.

 Note that this merging will not consider possible removed e[part] sections in the DSL file.
 The merging relies on the e[id], so if you change the e[id], e.g., the e[viewid], in the DSL file, then you will end up
 with two extension points in the e[plugin.xml].  Thus, in general, if you removed a e[part] section from
 the DSL file, or if you rename an e[id] in a e[part] section, please make sure you manually modify
 the e[plugin.xml] accordingly.  The easiest way is to select to the files,
 and use the context menu "Compare With" => "Each Other".  This way, you will soon detect the
 changes that have to be manually applied.

 section3:InjectorProvider[Obtaining the Injector]

 Since we also generate the e[plugin.xml] starting from the DSL file, we already make sure that the
 views will be created via Google Guice injection mechanisms, using a generated
 e[executable extension factory].

 If you need to obtain an injector corresponding to a specific DSL file, you can use the
 corresponding generated class e[injector provider].  This is prefixed with the name of the module
 (first letter capitalized).  For example, given this DSL module

 code[EmfParsley][
 module org.eclipse.emf.parsley.examples.firstexample {
 	...
 }
 ]

 The Java class for the injector provider will be e[org.eclipse.emf.parsley.examples.firstexample.FirstexampleInjectorProvider].

 These injector providers have a static method e[getInjector()] that will return the e[singleton] injector
 corresponding to that module:

 code[Java][
 Injector injector = FirstexampleInjectorProvider.getInjector();
 ]

 The returned injector is e[singleton] in the sense that it is the same injector used
 to create instances of the view parts specified as extension points in the e[plugin.xml].

 Obtaining the injector this way is useful, for example, when you develop a pure e4 application,
 where you do not define views in the e[plugin.xml].  See ref:Eclipse4[Eclipse 4.x].

 %%section2:Customitations_TheHardWay[The Hard way]
 %%
 %%If you need a deeper degree of customizations, you can use the injection mechanism based on Google Guice.
 %%The framework has been designed for being completly customized in every detail. All you need to do is provide a custom
 %%implementation for a class that implements a specific aspect; then you need to write the corresponding
 %%e[bind] method to tell the dependency injection mechanism to use your own custom class.
 %%You can use the Java editor content assist to discover all bindings.
 %%
 %%img[images/01-guice-module-content-assistant.png][][ ][]
	chapter:Overview[Overview]

	e[EMF Parsley] is a lightweight framework that allows easy and quick UI development based
	upon EMF. e[EMF Parsley] is built on top of the EMF Edit framework and it implements features like Trees, Forms and Table builders with
	standard JFace databinding, providing a complete component-based toolset.
	EMF Parsley can be configured to use all kinds of EMF persistence
	implementations (XMI, Teneo, CDO)
	Moreover a DSL allows to easily customize several behaviors in each component.

	section:ParsleyComponents[Parsley Components]

	e[EMF Parsley] aims to provide a complete set of components to visualize your model with the introspective EMF capabilities
	and can be used to easily build forms, viewers or editors.

	There are some components that can be used out-of-the-box and can be considered as a reference implementation
	of the mechanisms that are the basis of e[EMF Parsley] itslef.

	ul[
	item[e[Trees] ]
	item[e[Forms] ]
	item[e[Tables] ]
	item[e[Editors] ]
	item[e[Search boxes] (coming soon)]
	]

	img[images/01-components.png][][ ][]

	section2:Customize[Customize]

	The main feature of e[EMF Parsley] is that you can customize all basic UI behaviours of the components with e[Dependency Injection]
	mechanisms (based on link[https://github.com/google/guice][Google Guice]).
	You can get more info in the ref:Customizations[Customizations Section], but you don't have to know all details
	about the internal implementation to inject your own customization because
	e[EMF Parsley] provides a DSL to easy customize your UI, as explained in the next section.

	section3:Customizations_DSL[Customize with the DSL]

	You can use the DSL by creating a new project with the wizard "Create a new project" -> "EMF Parsley DSL Based project"

	img[images/01-new-project-dsl-wizard.png][][ ][]

	Clicking the "Finish" button the wizard will open directly the DSL editor. You can use the content assistant
	to discover all features.

	img[images/01-dsl-content-assistant.png][][ ][]

	The DSL allows to customize the most relevant behaviors. Here we list only a few of them:

	ul[
	item[e[parts] lets you define your View Parts: this will correspond to the standard Eclipse extension
	points for the parts (see ref:PluginXml[How the DSL handles the plugin.xml])]

	item[e[bindings] section lets you define which implementation will be used with Injection]

	item[e[menu] section lets you define the contextual menu for all viewers (e[trees] and e[tables])]

	item[e[features provider] is used to retrieve the list of feature for a given EClass to build e[tables]
	and e[forms]]

	item[e[viewer content provider] mediates between the viewer's model and the viewer, to provide the
	contents to be shown]

	item[e[Label Provider] is used to retrieve the image and text rapresentation of the objects of a
	tree viewer]

	item[e[Caption Provider] provides captions for each feature (namely, EStructuredFeature) of the object shown in a form,
	in a dialog or in a table row.
	Different implementations can be defined for e[dialogs], e[forms] and e[tables].]

	item[e[Control Factory] provides a custom implementation of the Controls for each feature shown in a form or a dialog.
	Different implementations can be defined forfor e[dialogs] and e[forms]]
	]

	section3:DslProjectStructure[The structure of an EMF Parsley project]

	An EMF Parsley project, as created by the wizard, is an Eclipse plug-in project with a few
	additional builders.

	The e[emfparsley-gen] source folder will contain all the Java files generated by the DSL
	compiler. The contents of this folder should never be modified manually, since their contents
	will be overwritten by the DSL compiler.

	The e[src] source folder will contain an codeRef[org.eclipse.ui.plugin.AbstractUIPlugin] generated
	by the wizard. This is generated only during the creation of the project and it can be safely modified
	if you need to put other mechanisms in the activator.

	IMPORTANT: it is crucial that the activator has the static method e[getDefault], so you must not remove
	that method.

	If you choose one of the templates provided by the wizard, the e[src] folder will also contain
	a Java class for the view, which extends the corresponding view of Parsley. This can be safely modified
	if you need to add some additional mechanisms or contents to the view.

	You can then create additional e[.parsley] files in the same project.

	section3:PluginXml[How the DSL handles the plugin.xml]

	If you specify any e[part] in the DSL file, then
	the Parsley DSL will generate a e[plugin.xml_emfparsley_gen] in the e[emfparsley-gen] folder,
	in a directory named after the containing module. Then, the e[EMF Parsley builder] will take
	care of merging the generated content with the e[plugin.xml] in the root folder of the current project.
	If the e[plugin.xml] does not exist it will create it. Subsequent changes to the DSL file
	will regenerate e[plugin.xml_emfparsley_gen] and the builder will merge it with e[plugin.xml].
	The merging will overwrite in the e[plugin.xml] only the elements that are specified in the DSL.
	Any other elements in the e[plugin.xml] will not be touched, so you can also add other extension points
	manually in the e[plugin.xml].

	This merging takes place ONLY if your project has the e[EMF Parsley builder nature].
	Since version 0.6.1 this nature is automatically applied to the projects created with our wizard.
	In existing projects, you have to enable the nature yourself by right-clicking on the project,
	then "Configure" and then "Enable EMF Parsley builder.

	Note that this merging will not consider possible removed e[part] sections in the DSL file.
	The merging relies on the e[id], so if you change the e[id], e.g., the e[viewid], in the DSL file, then you will end up
	with two extension points in the e[plugin.xml]. Thus, in general, if you removed a e[part] section from
	the DSL file, or if you rename an e[id] in a e[part] section, please make sure you manually modify
	the e[plugin.xml] accordingly. The easiest way is to select to the files,
	and use the context menu "Compare With" => "Each Other". This way, you will soon detect the
	changes that have to be manually applied.

	section3:InjectorProvider[Obtaining the Injector]

	Since we also generate the e[plugin.xml] starting from the DSL file, we already make sure that the
	views will be created via Google Guice injection mechanisms, using a generated
	e[executable extension factory].

	If you need to obtain an injector corresponding to a specific DSL file, you can use the
	corresponding generated class e[injector provider]. This is prefixed with the name of the module
	(first letter capitalized). For example, given this DSL module

	code[EmfParsley][
	module org.eclipse.emf.parsley.examples.firstexample {
	...
	}
	]

	The Java class for the injector provider will be e[org.eclipse.emf.parsley.examples.firstexample.FirstexampleInjectorProvider].

	These injector providers have a static method e[getInjector()] that will return the e[singleton] injector
	corresponding to that module:

	code[Java][
	Injector injector = FirstexampleInjectorProvider.getInjector();
	]

	The returned injector is e[singleton] in the sense that it is the same injector used
	to create instances of the view parts specified as extension points in the e[plugin.xml].

	Obtaining the injector this way is useful, for example, when you develop a pure e4 application,
	where you do not define views in the e[plugin.xml]. See ref:Eclipse4[Eclipse 4.x].

	%%section2:Customitations_TheHardWay[The Hard way]
	%%
	%%If you need a deeper degree of customizations, you can use the injection mechanism based on Google Guice.
	%%The framework has been designed for being completly customized in every detail. All you need to do is provide a custom
	%%implementation for a class that implements a specific aspect; then you need to write the corresponding
	%%e[bind] method to tell the dependency injection mechanism to use your own custom class.
	%%You can use the Java editor content assist to discover all bindings.
	%%
	%%img[images/01-guice-module-content-assistant.png][][ ][]