Skip to content

Extensibility Support

Jump to bottom
Damyan Petev edited this page Apr 23, 2018 · 10 revisions

Create Custom Template

Create Custom Template Automatically

To automatically create a custom template, use the generate command. This will not only create a configuration file and a basic file structure but will also automatically register your new template to the Ignite UI CLI.

You can find an example of automatically creating a custom template at the "Examples" section below.

Create Custom Template Manually

You can create a custom template manually, without using a command (however, using the generate command can save you a lot of time) and later register it to the Ignite UI CLI. If you prefer this approach, you need to create and setup a template.json file that contains the template's configuration as well as a files folder that contains the actual files your template consists of, see Files content and structure.

After you are done with creating those, there are two steps you need to execute in order for your new template to be available when creating a new application using the CLI:

Register custom template into Ignite UI CLI

In case you have generated your template using the generate command the template gets automatically registered into the CLI, unless you have set the skip-config flag. If that's the case or you have created your custom template structure manually you need to use config command to add the root folder of the custom template as a record to the customTemplates property of the config.

ig config add customTemplates <value>

Configure template.json

Property Description
id The id is a string property which should be unique for the framework you want to add the template to. If you add the template to a project using the add command, you will need to provide this id as the first argument.
name The name is a string property representing the friendly name of the template which will be displayed when using the step by step mode of the CLI.
description The description is a string property describing the purpose of the template.
dependencies A list of dependencies used from the CLI to load required resources for the specific template. Can be either an array of strings or objects. See Template dependencies for details.
packages
(v1.3.0)		 An array of strings with extra packages (beyond default setup) that the Ignite UI CLI should install when the template is added to a project.
framework The framework is a string property that defines in what framework the template will be available. Supported frameworks are: "jquery", "angular" and "react".
projectType The projectType is a string property that defines for what project type the template will be available. You can find all the available controls in the "Project types" table.
components The components is an array of strings (components) - which are used from the CLI to show the template under the correct control it refers to when using the step by step mode . You can find all the available controls in the "Control groups and components" table
controlGroup The controlGroup is a string property which is used from the CLI to show the template under the correct control group when using the step by step mode . You can find all the available controls in the "Control groups and components" table.
listInComponentTemplates The listInComponentTemplates is a boolean property which defines if the template will be shown under the selected control group and component alongside with the other templates when using the step by step mode . If this is set to true, listInCustomTemplates property should be set to false.
listInCustomTemplates The listInComponentTemplates is a boolean property which defines if the template will be shown under the Views option, alongside with the other custom templates when using the step by step mode . If this is set to true, listInComponentTemplates property should be set to false.

Project types

Following is the list of project types, depending on the selected framework.

Framework Project type
"jquery" "js"
"angular" "ig-ts" (Angular Wrappers)
"angular" "igx-ts" (Angular)
"react" "es6"

Control groups and components

Ignite UI for JavaScript

This table lists the control groups and the components that are available when adding a template for jQuery, React or Ignite UI Angular Wrappers projects.

Control Group Components
Data Grids
Grid
Hierarchical Grid
Tree Grid
Data Entry
Editors
Combo
Charts
Bar Chart
Column Chart
Doughnut Chart
Financial Chart
Funnel Chart
Line Chart
Pie Chart
Radial Chart
Scatter Chart

Ignite UI for Angular

This table lists the control groups and the components that are available when adding a template for Ignite UI for Angular projects.

Control Group Components
Grids & Lists
Grid
List
Layouts
Tabbar
Carousel
Scheduling
Date Picker

Files content and structure

Template variables

Template variables are provided by the base template implementations, mostly based around the user-provided name for the template to be generated. Those can be used in content inside the files folder with the $(variable) format and will be replaced during generation.

Variable Description Available in project type
name Name for the template as provided by the user. Generally available
description Description of the template from configuration. Generally available
cliVersion Version of the Ignite UI CLI. Generally available
cssBlock A block of link tags referencing required styles. js
scriptBlock A block of script tags referencing required js files. js
ClassName Camel case version of the provided name, suitable for use in generated class names. es6, ig-ts, igx-ts
igniteImports A set of module import clauses adding required scripts. es6
filePrefix File name generated based on the provided name. Content equivalent of the path name variable. ig-ts, igx-ts

File path variables

These can be used in the file path, rather than content, with __variable__ format.

All base implementations except the jQuery js type provide:

  • path: Folder name generated based on the provided name. Depends on project setup and framework guidelines.

Additionally, Angular templates (ig-ts and igx-ts types) provide:

  • name: File name generated based on the provided name. Usually in lower case and dash-separated.

Files structure

The files folder contains all files that will be copied to a project when adding the template.

files/
└── <template output files>
template.json

All projects have a minimum required structure present (provided automatically when using the generate command), while some have additional conditions:

Project type Minimal files structure File collision*
"js" An index.html file ❎
"es6" An index.js file under client/pages/__path__/ ⚠️
"ig-ts" An __name__.component.ts file under src/app/components/__path__/ ⚠️
"igx-ts" An __name__.component.ts file under src/app/__path__/ ⚠️

* In the jQuery project each templates is added in its own folder, so there's no danger of overriding files. For all other projects, the structure matches the project one from its root. This means a template can create files in multiple folders, including outside its designated one. However, in those cases validation will be performed for potential file overrides and will fail the add process. That's why we recommend template files to be kept under a __path__ folder or created with __name__ in the file name, to ensure uniqueness.

Template dependencies

Ignite UI for JavaScript

Templates for jQuery, React or Ignite UI Angular Wrappers projects list their dependencies as a list of Ignite UI for JavaScript widgets they use. For example if the template contains an igGrid the dependency would be:

"dependencies": ["igGrid"]

Or if multiple widgets are used, for example in a form with various editors and validation:

"dependencies": ["igEditors", "igCombo", "igValidator"]

Ignite UI for Angular

As of version 1.3.0, templates targeting the Ignite UI for Angular project list dependencies as objects describing modifications that should be made to the root NgModule metadata in the main app module (app.module.ts). See the TemplateDependency interface.

This allows templates to import modules from the igniteui-angular or @angular/<..> packages, declare additional components or add providers.

"dependencies": [
  { "import": "IgxAvatarModule", "from": "igniteui-angular/main" },
  { "import": "HttpClientModule", "from": "@angular/common/http" },
  { "declare": "SomeComponent", "from": ".."},
  { "provide": "Service", "from": ".."}
]

  • An import entry will both import the module from the package and add it to the imports metadata of the main NgModule. Can call the forRoot() method when importing module if it requires it by setting the "root" property to true. For example :

    { "import": "IgxGridModule", "from": "igniteui-angular/grid", "root": true }

    Multiple identifiers per import can be requested by providing a comma separated string or a string array:

    { "import": ["IgxIconModule", "IgxAvatarModule", "IgxBadgeModule", //...

  • An declare entry will both import the component and add it to the declarations metadata of the main NgModule.

  • An provide entry will both import the identifier and add it to the providers metadata of the main NgModule.

All identifiers can use the template variables in their names and file path variables in the "from" property. For example if a template has the following service file to be provided:

files/
├── src/
│   └── app/
│      └── __path__/
|         ├── __name__.component.ts
|         └── data.service.ts
template.json

The service can be added as a dependency using:

{ "provide": "$(ClassName)DataService", "from": "./src/app/__path__/data.service.ts" }

The path will be relatively resolved to the main app module when added.

Examples

Create Custom Template Automatically

The following example demonstrates how to generate a new template containing a grid component that we want to use in our future Ignite UI for Angular projects. We will also update the template.json to include it to the list of the available grid templates.

First we need to execute the generate command to create our new template. We will use the argument aliases:

ig g t myTemplate -f=angular -t=igx-ts

After our template is generated, we can setup our grid component and when we are done, we need to open the template.json file to make the required updates. As we want our new template to appear under the Grid control, which is included inside the 'Grids & Lists' control group, our changes will look like this:
"components": [ "Grid" ]
"controlGroup": "Grids & Lists"
"listInCustomTemplates": false
"listInComponentTemplates": true

After executing those steps, when you activate the Ignite UI CLI step by step mode, using the ig command, after selecting to create a new Ignite UI for Angular application, you will find your new template under Add component > Grids & Lists > Grid.

Create Custom Template Manually

The following example demonstrates how to manually create a new template which contains a grid component. We want to use it in our future React projects. We will also make sure to include it to the list of the available grid templates.

We need to create a new folder that will contain our custom template. Inside we should create an empty template.json file and also a files folder that will contain all the files that our template needs. The content of the files folder will be copied to your actual project when adding the custom template.

Open the template.json file in a text editor and paste the following setup in it:

{
  "id": "myTemplate",
  "name": "myTemplate",
  "description": "This is a React custom template with id: myTemplate",
  "framework": "react",
  "projectType": "es6",
  "components": [ "Grid" ],
  "controlGroup": "Data Grids",
  "listInCustomTemplates": false,
  "listInComponentTemplates": true,
  "dependencies": [] 
}

After you save the template.json file, you just need to register your new template into the Ignite UI CLI..

When this is done, you will be able to use this template in your future projects.

Clone this wiki locally