Bug 200175 - Annotation to register templates
Annotation to register templates
Status: RESOLVED FIXED
Product: platform
Classification: Unclassified
Component: Dialogs&Wizards
7.0
All All
: P3 (vote)
: 7.1
Assigned To: Jesse Glick
issues@platform
: API, API_REVIEW_FAST
Depends on: 196452 201375 202993
Blocks:
  Show dependency treegraph
 
Reported: 2011-07-15 19:47 UTC by Jesse Glick
Modified: 2011-10-03 15:25 UTC (History)
1 user (show)

See Also:
Issue Type: ENHANCEMENT
:


Attachments
Running patch ('hg pdi template_anno_200175' to refresh) (127.39 KB, patch)
2011-07-18 22:35 UTC, Jesse Glick
Details | Diff

Note You need to log in before you can comment on or make changes to this bug.
Description Jesse Glick 2011-07-15 19:47:22 UTC
Registering (file or project) templates under Templates/ in an XML layer can be cumbersome and error-prone. There should be an annotation to take care of the syntax.
Comment 1 Jesse Glick 2011-07-18 22:35:40 UTC
Created attachment 109498 [details]
Running patch ('hg pdi template_anno_200175' to refresh)
Comment 2 Jesse Glick 2011-07-18 22:47:09 UTC
Please review.

Note that the basic @Template cannot be used to register Java sources as these require a custom iterator; instead there is a variant annotation sharing processor logic with the basic annotation. (Unfortunately this cannot be used in the java.project module itself, though that module could still use @Template on the definition of createJavaTemplateIterator to register e.g. Class.java.) The same mechanism could be used to define annotations for other specialized kinds of templates using a predefined iterator: Maven archetypes based on coordinates; sample projects based on simple.project.templates; etc. (Technically Templates.category would merit a separate annotation in projectuiapi using this system, but that seems like overkill for such a commonly used and simple attribute.)

There is an editor hint (currently functional only on "pure" templates with an iterator but no static content); the apisupport wizards are not yet updated to generate @Template, but they can be.

By the way I am unsure whether the Templates/Privileged folder is still used for anything; it seems not to be, in which case I can delete the handful of shadows still registered there.
Comment 3 Jaroslav Tulach 2011-07-19 07:38:17 UTC
Y01 So far our annotations registering something were suffixed by Registration. Should not the new annotation be @TemplateRegistration?

Y02 I don't like AbstractTemplateProcessor in the API. Find different solution.

Y02a I am not convinced you need JavaTemplates.Registration(s) as all. For example instead of annotatiting org.netbeans.modules.beans.resources.templates; you can annotation static method:

@Templates(....)
static InstantiatingIterator beansTemplates() {
  return JavaTemplates.createJavaTemplateIterator();
}

Y03 Can we put these (DataObject independent) classes to org.netbeans.api.templates? They can stay in openide.loaders for now, but having them in separate package may help splitting them away in future.

Y04 Include examples in description of Template.content(). I am not sure I patient enough to parse the current javadoc.

Y05 There should be code completion on the Template.folder() value (you can use this as an opportunity to show me how this should be done after your devastating critique of @ActionReference.path()). General, easy to use solution for other annotations referencing layer is welcomed.
Comment 4 Jesse Glick 2011-07-19 12:50:33 UTC
(In reply to comment #3)
> Y01 So far our annotations registering something were suffixed by Registration.
> Should not the new annotation be @TemplateRegistration?

It could be.

> Y02 I don't like AbstractTemplateProcessor in the API. Find different solution.

I do not like it much either but I could not find any other solution that permitted specialized template annotation types.

> Y02a ... you can annotate static method:
> 
> @Templates(....)
> static InstantiatingIterator beansTemplates() {
>   return JavaTemplates.createJavaTemplateIterator();
> }

This is a possible approach, though it means creating extra class files in each module registering Java templates. Ditto for other specialized template subtypes. Perhaps that is worth the cost.

> Y03 Can we put these (DataObject independent) classes to
> org.netbeans.api.templates?

I think that would not be a problem.

> They can stay in openide.loaders for now, but
> having them in separate package may help splitting them away in future.

Well, the template system is pretty heavily tied to DataObject and TemplateWizard.

> Y04 Include examples in description of Template.content(). I am not sure I
> patient enough to parse the current javadoc.

Can do.

> Y05 There should be code completion on the Template.folder() value

Will treat this as a TCA.
Comment 5 Jesse Glick 2011-07-19 15:22:14 UTC
Y01-Y04 implemented in branch, by the way.
Comment 6 Jesse Glick 2011-07-19 20:26:40 UTC
Also in branch: I found it was necessary to add an id() attribute (disjunctive with content()), for purposes of Templates/Classes/Package.
Comment 7 Jaroslav Tulach 2011-07-20 16:52:19 UTC
(In reply to comment #4)
> (In reply to comment #3)
> > Y02 I don't like AbstractTemplateProcessor in the API. Find different solution.
> 
> I do not like it much either but I could not find any other solution that
> permitted specialized template annotation types.
> 
> > Y02a ... you can annotate static method:
> > @Templates(....) static InstantiatingIterator beansTemplates() {
> >   return JavaTemplates.createJavaTemplateIterator();
> > }
> 
> This is a possible approach, though it means creating extra class files in each
> module registering Java templates. 

I don't think you need a special class. There always is some class in the module, so you can just add the method into it. E.g. no need to create special org.netbeans.modules.beans.resources.templates.Templates.

> > Y05 There should be code completion on the Template.folder() value
> 
> Will treat this as a TCA.

OK.
Comment 8 Jesse Glick 2011-07-20 17:01:43 UTC
(In reply to comment #7)
> I don't think you need a special class. There always is some class in the
> module, so you can just add the method into it. E.g. no need to create special
> org.netbeans.modules.beans.resources.templates.Templates.

It could be in an existing class, but then the relative resource paths would all need to be changed, and template-related configuration would not be in one place, so I just created Templates.java in the same package for clarity.
Comment 9 Jesse Glick 2011-07-25 21:02:05 UTC
core-main #d4c6057a3f4f
Comment 10 Quality Engineering 2011-07-27 14:10:06 UTC
Integrated into 'main-golden'
Changeset: http://hg.netbeans.org/main-golden/rev/d4c6057a3f4f
User: Jesse Glick <jglick@netbeans.org>
Log: #200175: annotation to register templates.


By use of this website, you agree to the NetBeans Policies and Terms of Use. © 2012, Oracle Corporation and/or its affiliates. Sponsored by Oracle logo