KDevelop5/File template specification: Difference between revisions

    From KDE TechBase
    No edit summary
    Line 1: Line 1:
    {{ Construction }}
    === Template language ===
    === Template language ===


    Line 5: Line 7:
    For information regarding Grantlee templates in general, refer to its [http://www.grantlee.org/apidox/pages.html documentation]. Since Grantlee's template language is based on Django's, it might be useful to read the [https://docs.djangoproject.com/en/1.1/topics/templates/ Django template documentation] as well.  
    For information regarding Grantlee templates in general, refer to its [http://www.grantlee.org/apidox/pages.html documentation]. Since Grantlee's template language is based on Django's, it might be useful to read the [https://docs.djangoproject.com/en/1.1/topics/templates/ Django template documentation] as well.  


    === File Structure ===
    === Example template template ===


    Like project templates, class templates are compressed directories, and they too contain a special description file and any number of content files. It is recommended that the description file has a <tt>.desktop</tt> extension instead of <tt>.kdevtemplate</tt>, although both are supported.  
    There is a project template that creates a new project consisting of a single '''KDevelop''' class template. You can use it by starting a new project, choosing <menuchoice>Get More Templates...</menuchoice> and installing [http://kde-files.org/content/show.php/?content=152234 this one]. Proceeding to create a project using this template will create an example class template.
     
    === File structure ===
     
    Like [[Development/KDevelop/Project_template_specification|project templates]], class templates are compressed directories, and they too contain a special description file and any number of content files. It is recommended that the description file has a <tt>.desktop</tt> extension instead of <tt>.kdevtemplate</tt>, although both are supported.  


    Unlike with project templates, not all files from the archive are copied to the output directory. Because Grantlee supports template inheritance and inclusions, class templates may contain helper files that only serve for convenience and produce no actual output. The actual output files have to be specified in the template description.  
    Unlike with project templates, not all files from the archive are copied to the output directory. Because Grantlee supports template inheritance and inclusions, class templates may contain helper files that only serve for convenience and produce no actual output. The actual output files have to be specified in the template description.  


    === Description File Format ===
    === Description file format ===


    === Variables ===
    === Variables ===


    The variables which are passed to class templates are described in the {{class|TemplateClassGenerator|kdevelop|extragear}} API documentation.
    The variables which are passed to class templates are described in the {{class|TemplateClassGenerator|kdevelop|extragear}} API documentation.
    === Additional template filters ===


    === Custom options ===
    === Custom options ===
    Line 25: Line 33:
    </nowiki>}}
    </nowiki>}}


    For information about the options file format, see [[Development/Tutorials/Using_KConfig_XT|Using KConfig XT]].
    {{note|Template options are meant to be used only for small differences in large, complex templates. To reduce the number of necessary clicks, it is preferred to use separate templates instead. }}
     
    For information about the options file format, see [[Development/Tutorials/Using_KConfig_XT|Using KConfig XT]]. Note that KDevelop only supports a subset of the KConfig XT specification. Only <tt>Int</tt>, <tt>Bool</tt> and <tt>String</tt> types are recognized, options with other types are ignored. Furthermore, only <tt>name</tt>, <tt>type</tt>, <tt>label</tt> and <tt>default</tt> attributes are used.

    Revision as of 07:47, 10 July 2012

     
    Under Construction
    This is a new page, currently under construction!


    Template language

    Class templates use the Grantlee library for rendering templates. It has more features than KMacroExpander, the most important being loops and the ability to expose custom data types from C++ code to templates. The use of Grantlee makes templates more powerful, but also more difficult to write.

    For information regarding Grantlee templates in general, refer to its documentation. Since Grantlee's template language is based on Django's, it might be useful to read the Django template documentation as well.

    Example template template

    There is a project template that creates a new project consisting of a single KDevelop class template. You can use it by starting a new project, choosing Get More Templates... and installing this one. Proceeding to create a project using this template will create an example class template.

    File structure

    Like project templates, class templates are compressed directories, and they too contain a special description file and any number of content files. It is recommended that the description file has a .desktop extension instead of .kdevtemplate, although both are supported.

    Unlike with project templates, not all files from the archive are copied to the output directory. Because Grantlee supports template inheritance and inclusions, class templates may contain helper files that only serve for convenience and produce no actual output. The actual output files have to be specified in the template description.

    Description file format

    Variables

    The variables which are passed to class templates are described in the Expression error: Unrecognized word "extragear". API documentation.

    Additional template filters

    Custom options

    Templates can expose configuration options to the user prior to the class generation. To do this, add a KConfig XT formatted file into the archive, and specify an Options entry in the template description file pointing to it.

    Options=options.kcfg
    
    Note
    Template options are meant to be used only for small differences in large, complex templates. To reduce the number of necessary clicks, it is preferred to use separate templates instead.


    For information about the options file format, see Using KConfig XT. Note that KDevelop only supports a subset of the KConfig XT specification. Only Int, Bool and String types are recognized, options with other types are ignored. Furthermore, only name, type, label and default attributes are used.