:toc: toc::[] = Configuration CobiGen is maintaining a home directory further referenced in this documentation as `$cghome`, which is used to maintain temporary or transient data. The home folder is determined with the following location fall-back: 1. System environment variable `COBIGEN_HOME` (e.g. `C:\project\ide\conf\cobigen-home`) 2. `.cobigen` directory in OS user home (e.g. `~/.cobigen`) The actual configuration of CobiGen is maintained by a single folder or jar. The location can be configured with respect to the implemented configuration fall-back mechanism. CobiGen will search for the location of the configuration in the following order: 1. A configuration jar or directory, which is passed to CobiGen by the Maven or Eclipse integration or any other program using the CobiGen programming interface: 1.1. the Maven integration allows to configure a jar dependency to be included in the currently running classpath _(of interest for link:cobigen-maven_configuration#plugin-injection-since-v3[maven configuration]_ 1.2. the Eclipse integration allows to specify a `CobiGen_Templates` project in the eclipse workspace 2. The file `$cghome/.cobigen` exists and the property `templates` is set to a valid configuration (e.g. `templates=C:\project\ide\conf\templates` or `templates=C:\project\ide\conf\templates.jar`) _Hint: Check for log entry like `Value of property templates in $cghome/.cobigen is invalid` to identify an invalid configuration which is not taken up as expected_ 3. The folder `$cghome/templates/CobiGen_Templates` exists 4. The lexicographical sorted first configuration jar of the following path pattern `$cghome/templates/templates-([^-]+)-(\\d+\\.?)+.jar` if exists (e.g. `templates-devon4j-2020.04.001`) 5. CobiGen will automatically download the latest jar configuration from maven central with `groupId` `com.devonfw.cobigen` and `artifactId` `templates-devon4j` and take it like described in 4. Within the configuration jar or directory you will find the following structure: ``` CobiGen_Templates |- templateFolder1 |- src |- main |- templates |- template1 |- templates |- templates.xml |- templateFolder2 |- context.xml ``` Since: CobiGen 2021.12.007: ``` template-sets |- downloaded |- template-set1.jar |- template-set2.jar |- template-set-utilities.jar |- adapted |- template-set1 |- src |- main |- templates |- templates |- context.xml |- templates.xml |- template-set2 ``` Find some examples https://github.com/devonfw/cobigen/tree/master/cobigen-templates[here]. == CobiGen Configuration File The CobiGen configuration file located at: `$home/.cobigen` can be used to set the path to the custom `templates` as well as the `template sets` project. You can also specify attributes to control the behaviour of your template sets. === Templates For a custom templates folder simply set the `templates` parameter like this: ``` templates=C:\\project\\ide\\conf\\templates ``` For a custom templates jar simply set the `templates` parameter like this: ``` templates=C:\\project\\ide\\conf\\templates\\my-custom-templates-devon4j-2021.06.001.jar ``` === Template Sets Since: CobiGen 2021.12.006 For a custom template-sets folder simply set the `template-sets` parameter like this: ``` template-sets=C:\\project\\ide\\conf\\template-sets ``` === Template set attributes Since: CobiGen 2021.12.006 You can specify `template-sets` attributes f.e. to restrict the teams to ask for default templates provided by CobiGen. There are `four` custom template-sets attributes: * `template-sets.groupIds`: Search for template-set artifacts by that configuration key configure multiple (comma separated) `groupIds`. By default, (public) CobiGen `groupId` will be used. * `template-sets.allow-snapshots`: Allow snapshots of template-sets to be offered for template-set development purposes. By default, no snapshots should be queried. * `template-sets.disable-default-lookup`: Disable by default querying of default public `groupIds` configured in CobiGen. * `template-sets.hide:` Hide very specific template sets or versions of template sets. * `template-sets.installed:` Template sets will be available at CobiGen startup if template sets are not already adapted. The key `template-sets.hide` and `template-sets.installed` accept maven coordinate with the following format: `groupID:artifactID:version` the version is optional and if omitted the **LATEST** version will be used. You can specify multiple maven coordinates separated with *,*. * An example of how such a configuration should look like: ``` template-sets.groupIds=com.devonfw.cobigen.templates,jaxen,jakarta.xml.bind template-sets.allow-snapshots=true template-sets.disable-default-lookup=false template-sets.hide=com.devonfw.cobigen.templates:crud-angular-client-app:2021.12.007-SNAPSHOT template-sets.installed=com.devonfw.cobigen.templates:crud-angular-client-app:2021.12.007-SNAPSHOT, com.devonfw.cobigen.templates:crud-java-server-app: ``` == Context Configuration The context configuration (`context.xml`) always has the following root structure: .Context Configuration ```xml ... ``` The context configuration has a `version` attribute, which should match the XSD version the context configuration is an instance of. It should not state the version of the currently released version of CobiGen. This attribute should be maintained by the context configuration developers. If configured correctly, it will provide a better feedback for the user and thus higher user experience. Currently there is only the version v1.0. For further version there will be a changelog later on. === Trigger Node As children of the `` node you can define different triggers. By defining a `` you declare a mapping between special inputs and a `templateFolder`, which contains all templates, which are worth to be generated with the given input. .trigger configuration ```xml ... ``` * The attribute `id` should be unique within an context configuration. It is necessary for efficient internal processing. * The attribute `type` declares a specific _trigger interpreter_, which might be provided by additional plug-ins. A _trigger interpreter_ has to provide an _input reader_, which reads specific inputs and creates a template object model out of it to be processed by the FreeMarker template engine later on. Have a look at the plug-in's documentation of your interest and see, which trigger types and thus inputs are currently supported. * The attribute `templateFolder` declares the relative path to the template folder, which will be used if the trigger gets activated. * The attribute `inputCharset` _(optional)_ determines the charset to be used for reading any input file. === Matcher Node A trigger will be activated if its matchers hold the following formula: `!(NOT || ... || NOT) && AND && ... && AND && (OR || ... || OR)` Whereas NOT/AND/OR describes the `accumulationType` of a _matcher_ (see below) and e.g. `NOT` means 'a _matcher_ with `accumulationType` NOT matches a given input'. Thus additionally to an _input reader_, a _trigger interpreter_ has to define at least one set of _matchers_, which are satisfiable, to be fully functional. A `` node declares a specific characteristics a valid input should have. .Matcher Configuration ```xml ... ``` * The attribute `type` declares a specific type of _matcher_, which has to be provided by the surrounding _trigger interpreter_. Have a look at the plug-in's documentation, which also provides the used trigger type for more information about valid matcher and their functionalities. * The attribute `value` might contain any information necessary for processing the _matcher's_ functionality. Have a look at the relevant plug-in's documentation for more detail. * The attribute `accumulationType` _(optional)_ specifies how the matcher will influence the trigger activation. Valid values are: ** OR (default): if any matcher of accumulation type OR _matches_, the trigger will be activated as long as there are no further matchers with different accumulation types ** AND: if any matcher with AND accumulation type does _not match_, the trigger will _not_ be activated ** NOT: if any matcher with NOT accumulation type _matches_, the trigger will _not_ be activated === Variable Assignment Node Finally, a `` node can have multiple `` nodes as children. _Variable assignments_ allow to parametrize the generation by additional values, which will be added to the object model for template processing. The variables declared using _variable assignments_, will be made accessible in the templates.xml as well in the object model for template processing via the namespace `variables.*`. .Complete Configuration Pattern ```xml ``` * The attribute `type` declares the type of _variable assignment_ to be processed by the _trigger interpreter_ providing plug-in. This attribute enables _variable assignments_ with different dynamic value resolutions. * The attribute `key` declares the namespace under which the resolved value will be accessible later on. * The attribute `value` might declare a constant value to be assigned or any hint for value resolution done by the _trigger interpreter_ providing plug-in. For instance, if `type` is `regex`, then on `value` you will assign the matched group number by the regex (1, 2, 3...) === Container Matcher Node The `` node is an additional matcher for matching containers of multiple input objects. Such a container might be a package, which encloses multiple types or---more generic---a model, which encloses multiple elements. A container matcher can be declared side by side with other matchers: .`ContainerMatcher` Declaration ```xml ``` * The attribute `type` declares a specific type of _matcher_, which has to be provided by the surrounding _trigger interpreter_. Have a look at the plug-in's documentation, which also provides the used trigger type for more information about valid matcher and their functionalities. * The attribute `value` might contain any information necessary for processing the _matcher's_ functionality. Have a look at the relevant plug-in's documentation for more detail. * The attribute `retrieveObjectsRecursively` _(optional boolean)_ states, whether the children of the input should be retrieved recursively to find matching inputs for generation. The semantics of a container matchers are the following: * A `` does not declare any `` nodes * A `` matches an input if and only if one of its enclosed elements satisfies a set of `` nodes of the same `` * Inputs, which match a `` will cause a generation for each enclosed element == Templates Configuration The template configuration (`templates.xml`) specifies, which templates exist and under which circumstances it will be generated. There are two possible configuration styles: 1. Configure the template meta-data for each template file by xref:template-node[template nodes] 2. `_(since cobigen-core-v1.2.0)_`: Configure `xref:templatescan-node[templateScan nodes]` to automatically retrieve a default configuration for all files within a configured folder and possibly modify the automatically configured templates using xref:templateextension-node[`templateExtension` nodes] To get an intuition of the idea, the following will initially describe the first (more extensive) configuration style. Such an configuration root structure looks as follows: .Extensive Templates Configuration ```xml ... ... ``` The root node `` specifies two attributes. The attribute `version` provides further usability support and will be handled analogous to the `version` attribute of the xref:context-configuration[context configuration]. The optional attribute `templateEngine` specifies the template engine to be used for processing the templates (_since `cobigen-core-4.0.0`_). By default it is set to FreeMarker. The node `` allows two different grouping nodes as children. First, there is the `` node, which groups all declarations of templates. Second, there is the `` node, which groups all declarations about increments. === Template Node The `` node groups multiple `