Parent page: Working with Vault Components
Helping to streamline the creation of your Vault Components, Altium Designer, in conjunction with the Altium Vault, supports creating and defining Component Templates. Just as a schematic template can be used to predefine information on schematic sheets that reference it, a component template is referenced by a component library (CmpLib), and provides predefined settings for use by component definitions defined therein.
In particular, component templates have been developed with parametric information firmly in mind, allowing you define, in a single location, a 'bucket set' of parameters that will be made available to the referencing component library. Through the template, you can control which of those parameters are to be made visible, fill-in default values, and even mark those parameters that are required as mandatory. In addition, you can also force the use of parameters, marking them as required. Validation checks are in-place at the time of component definition release, to ensure compliance.
Specified default values for many of the template settings can be locked-down to be read-only, or selectively made available for override by the designer at the library-level.
Such Items are created directly from within the target Vault. Once a Component Template Item has been created (and data released into a revision of it), and its lifecycle state set to a level that the organization views as ready for use at the design level, it can be reused in the creation of one or more Vault components .
Folder Type
When creating the folder in which to store Component Template Items, you can specify the folder's type. This has no bearing on the content of the folder - releasing a component template will always result in a corresponding Component Template Item. It simply provides a visual 'clue' as to what is stored in a folder and can be beneficial when browsing a Vault for particular content. To nominate a folder's use as a container for Component Template Items, set its Folder Type as Component Templates, when defining the folder properties in the Edit Folder dialog.
Specifying the folder type - its intended use - gives a visual indication of the content of that folder when browsing the Vault!
Item Naming Scheme
Another important aspect of the parent folder is the Item Naming Scheme employed for it. This defines the format of the unique ID for each Item created in that particular folder. Several default example schemes are available, utilizing the short-form code for either the folder type (CTC - Component Template Collection) or the content type (CMPT - Component Template):
- $CONTENT_TYPE_CODE-001-{0000} - for example, CMPT-001-0001.
- $CONTENT_TYPE_CODE-001-{A00} - for example, CMPT-001-A01.
- $FOLDER_TYPE_CODE-001-{0000} - for example, CTC-001-0001.
- $FOLDER_TYPE_CODE-001-{A000} - for example, CTC-001-A001.
Using a default naming scheme, the software will automatically assign the next available unique ID, based on that scheme, having scanned the entire Vault and identifiers of existing Items. This can be a great time-saver when manually creating Component Template Items prior to release.
A custom scheme can also be defined for a folder, simply by typing it within the field, ensuring that the variable portion is enclosed in curly braces (e.g. CMP-TMP-{0000}).
The Item Naming Scheme of the parent folder is applied to the Unique ID for each Item
created within that folder.
The Item Naming Scheme employed for the parent folder can be changed at any time. The modified scheme will then be applied to any subsequent newly-created Items within that folder.
Item Type
When creating a target Component Template Item in which to store your component template, ensure that its Content Type is set to Component Template, in the Item Properties dialog. If you are creating the Item in a Component Templates type folder, this Item type will be available from the right-click context menu when creating the Item.
Creating a Component Template Item within a Component Templates folder - the correct Content Type is available on the context menu.
Item Lifecycle Definition and Revision Naming
When defining a Component Template Item, be sure to specify the type of lifecycle management to be used for the Item, and the naming scheme employed for its revisions, respectively.
Control over which Item types can use a particular lifecycle definition or revision naming scheme, can be defined and enabled at a global level from within the Content Types dialog, when defining each schema. For a newly-installed Vault, the default schemes assigned for use by a Component Template Item are: Basic Lifecycle and 1-Level Revision Scheme, respectively.
Once a template definition has been released into the initial revision of a Component Template Item, these schemes cannot be changed for that particular Item.
Specify the required schemes in the Item Properties dialog, using the Lifecycle Definition and Revision Naming Scheme fields respectively.
If the option to control use of lifecycle definitions and revision naming schemes per content type is enabled for any definitions/schemes, and the Component Template Item type is not set to use a particular definition/scheme, then that definition/scheme will not be available in the applicable drop-down list.
Selecting the Lifecycle Definition and Revision Naming schemes for a manually created Item.
Observing standard revision naming schemes and lifecycle definitions, across the various types of design item in a Vault ensures smooth, consistent management of those items.
It is a good idea to add a comment and description as part of the Item's definition. This information is used when searching the Vault and enables quick identification of what a Component Template Item offers.
Releasing a Component Template
So far, we've discussed the support for a Component Template Item in the Vault, in terms of related folder and item types. Releasing an actual defined component template into a revision of such an item can be performed in a single streamlined way.
A component template can be edited and released into the initial revision of a newly-created Component Template Item, courtesy of the Vault's support for direct editing. Direct editing frees you from the shackles of separate version-controlled source data. You can simply edit a supported Item type using a temporary editor loaded with the latest source direct from the Vault itself. And once editing is complete, the entity is released (or re-released) into a subsequent planned revision of its parent Item, and the temporary editor closed. There are no files on your hard drive, no questioning whether you are working with the correct or latest source, and no having to maintain separate version control software. The Altium Vault handles it all, with the same great integrity you've come to expect, and in a manner that greatly expedites changes to your data.
When you create a Component Template Item, you have the option to edit and release a component template into the initial revision of that item, after creation. To do so, simply enable the option Open for editing after creation, at the bottom of the Create Item dialog (which is enabled by default). The Item will be created and the temporary CMPT Editor will open, presenting a .CMPT document as the active document in the main design window. This document will be named according to the Item-Revision, in the format: <Item><Revision>.CMPT (e.g. CMPT-001-0001-1.CMPT).
Example of editing the initial revision of a Component Template Item, directly from the Vault - the temporary CMPT Editor provides the document with which to
define your component template.
Use the document to define the component template as required. For more information on doing this, see Defining the Template.
The Component Template Standard toolbar provides three relevant controls when direct editing:
-
- Save Active Document. Use this button to save the changes made to the document. This is required before you can release the document back to the Vault.
-
- Release Document. Use this button to release the defined component template to the Vault, storing it within the initial (planned) revision of the target Component Template Item. The Create Revision dialog will appear, in which you can change Comment, Description, and add release notes as required. The document and editor will close after the release. The document containing the source component template, *.CMPT, will be stored in the revision of the Item.
-
- Cancel Editing. Use this button if you wish to cancel editing. The document and editor will close, and nothing will be released to the target Component Template Item.
The released data stored in the Vault consists of the source component template, defined in the Component Template file (<Item><Revision>.CMPT).
The CMPT (Component Template) Editor
A component template itself is defined using the CMPT Editor. This is a temporary editor delivered through a purpose-made extension - the Component Template Editor extension.
The Component Template Editor extension.
The CMPT Editor can only be accessed, provided the Component Template Editor extension is installed as part of your Altium Designer installation. This extension is installed by default when installing the software, but in case of inadvertent uninstall, can be found back on the Purchased tab of the Extensions & Updates page (DXP » Extensions and Updates).
Defining the Template
The CMPT Editor is essentially divided into two main regions, illustrated in the following image and summarized thereafter.
The CMPT Editor can be coarsely divided into two key regions.
- Upper Region - for defining the document options for a CmpLib that references the template.
- Lower Region - for defining the parameters to be used in that CmpLib.
Specifying Document Options
The top half of the editor is dedicated to defining default values for the following Component Library properties:
- Lifecycle Definition - use the drop-down field to choose from all definitions defined for the Vault, and which are permitted for use by a Component Item.
- Revision Naming - use the drop-down field to choose from all schemes defined for the Vault, and which are permitted for use by a Component Item.
If the option to control use of lifecycle definitions and revision naming schemes per content type is enabled for any definitions/schemes, and the Component Item type is not set to use a particular definition/scheme, then that definition/scheme will not be available in the applicable drop-down list.
- Component Naming - use this field to define a default Item Naming Scheme for components released from the CmpLib file, ensuring a unique ID for each resulting Component Item in the Vault. The entry here will be used as the template for automatically naming a newly-added component definition (in its associated Name field). The software will automatically assign the next available unique ID, based on that scheme, having scanned the entire Vault and identifiers of existing Items. A default Item naming scheme - CMP-{00000} - is provided, but you can of course create your own scheme, simply by typing it within the field, ensuring that the variable portion is enclosed in curly braces (e.g. CMP-001-{0000}).
- Default Folder - to specify a default folder within the target Vault in which to store the released Component Items. Do this by clicking the Choose button to access the Choose Folder dialog - a cut-down version of the Vaults panel, from where you can browse to, and choose, an existing folder in the Vault, or create a new one on-the-fly.
There is no field to set the target Vault, as this will be hard-coded to use the same Vault as that in which the revision of the Component Template Item resides.
The Allow override option for each property can be used to independently control whether that property can be changed (enabled) or not (disabled), by the user on the CmpLib side.
When the template is referenced, the entries specified here are used to pre-fill the corresponding fields on the Document Options tab of the Document Options dialog - over in the referencing CmpLib file.
When the template is referenced, the entries are used to pre-fill the document options of the referencing CmpLib file.
Defining Parameters
The lower half of the editor is dedicated to defining and managing the parameters that will be made available to the referencing Component Library.
Example parameters defined in a component template.
Default System Parameters
Various system parameters are included by default when creating a new Component Template Item, as illustrated in the following image and detailed thereafter.
Default system-level parameters included in a newly-created Component Template Item.
- ComponentType - this parameter allows you to specify the type of component. This facilitates targeted searching through the Vault's powerful Search facility - a facility that not only allows you to search by component type, but allows you to search smarter, with supported unit-aware component parameters. Simply click on the associated Default Value field, and then click the
button to access the Component Type dialog. Use this to select the required type of component and click OK - the chosen type will be inserted as the value for the ComponentType parameter, back in the main parameters grid.
The Component Type dialog presents a default set of component types. Commands available from the dialog's right-click context menu allow you to craft this listing to better suit your needs - either by adding new types and sub-types, or editing and removing existing types.
Example Component Template, with the ComponentType system parameter set to Diode.
The data type for this parameter is set to ComponentType, and cannot be modified. Also, the ComponentType parameter cannot be copied or removed.
- SCHLIB and PCBLIB - these two parameters allow you to specify default Symbol and Footprint Items, respectively. Simply click on the associated Default Value field for each parameter, and then click the button to access a dialog with which to choose the required model Item.
It is the model Item that you are choosing, and not a specific revision of that Item. In this way, a component library using the template will always use the latest revision of the chosen model Item.
Specify Symbol and Footprint Items as part of your template.
The data types for these parameters are set to SCHLIB and PCBLIB respectively, and cannot be modified. Also, the model parameters cannot be copied or removed.
- Comment and Description - these two parameters allow you to define the comment and description for the component respectively. Simply enter the required strings in the associated Default Value field for each parameter.
Specify Comment and Description parameters as part of your template.
The data type for both of these parameters is set to Text and cannot be modified. Also, these parameters cannot be copied or removed.
Adding a New User Parameter
To add a new user parameter to the list, simply click the Add button (or use the Add command from the right-click context menu) - the parameter is added to the bottom of the current list.
Example addition of a new user parameter to the template.
Each parameter is presented in the grid-like listing in terms of the following information:
- Name - use this field to name the parameter, typically a meaningful name that conveys its purpose. When initially added, parameters will be given default names (Parameter, Parameter1, Parameter2, and so on).
- Type - the type of parameter. This entry will default to Text initially, but a range of unit-aware data types are supported, as well as the type PCBLIB, which facilitates the definition of multiple footprints.
- Visible - enable this option (which is the default state for a newly added parameter) to have the corresponding Show option for the parameter enabled in the referencing CmpLib. This, in turn, controls the display of the corresponding column for that parameter in the lower region of the CmpLib Editor, where the component definitions themselves are defined.
- Read Only - enable this option to make the parameter read-only. In the referencing CmpLib, the value for the parameter will be made non-editable.
- Required - enable this option to make the parameter a 'required parameter'. In the referencing CmpLib, the parameter must have a value defined for it, otherwise release of the associated component definition will not be possible. In the CmpLib, such a parameter is distinguished by the value cell having a red border, when no value has been entered.
- Default Value - use this field to enter a default value for the parameter.
If the parameter is marked as being required (Required option enabled), and has also been set to be read-only (Read Only option enabled), then a default value must be entered. If not, the parameter in the referencing CmpLib will be flagged as not having a value, but is non-editable by virtue of being read-only.
- Description - add any description for the parameter, for example a concise note about what it provides.
The parameters list also supports simple copy and paste actions, allowing you to duplicate one or more existing parameters. The copied parameter(s) will be added to the bottom of the list.
Standard copy (Ctrl+C) and paste (Ctrl+V) shortcuts are supported, and these commands are also available from the right-click menu. Multiple parameters can be selected for copy-paste operations, using standard Ctrl+click and Shift+click techniques.
To delete one or more parameters from the list, simply select each parameter, then click the Remove button, or use the Remove command from the right-click context menu.
Column Ordering and Sizing
The order of the columns is customizable. Simply click on a column's header and drag it horizontally to the required new position. Valid positions are highlighted by vertical positional arrows.
The width of a column can be modified, simply by clicking and dragging the right-hand separator (in that column's header).
Sorting
Parameters can be sorted by a specific column simply by clicking on that column's header. Click once to sort in ascending order (based on the content of that column). Click again to sort in descending order.
You can sort by multiple columns. With the parameters already sorted by a specific column, simply Shift+click on another column to 'sub-sort' by the content of that column.
To remove sorting for a column, Ctrl+click on its header.
Unit-Aware Component Parameter Data Types
The CMPT Editor provides the ability to define explicit data types for component parameters defined within a component template (*.CMPT). In addition, these data types are unit-aware, with a range of popular unit prefixes supported. As such, you can enter a parameter's value using a range of formats - such as 2.2k, 2k2, 4M, 2.5GHz - with the Altium Vault engineered with the requisite smarts to recognize the numerical value behind those entries.
This feature of a component template facilitates targeted searching through the Vault's Advanced Search facility - a facility that not only allows you to search by component type, but allows you to search smarter, with range, greater than, or less than searches. Using the power of unit-aware component parameters, you can quickly define a search, for example, to find all capacitors with a capacitance between 47uF and 220uF.
Use the following collapsible sections to learn more about unit-aware parameters.
Supported Units
The following unit-aware data types are supported when defining a user parameter as part of a component template:
Most data types have a unit (in brackets). This will be applied if no unit is specified when entering a value for a parameter.
- Volt(V)
- Ampere(A)
- Ohm
- Farad(F)
- Henry(H)
- Watts(W)
- Hertz(Hz)
- Celsius(C)
- Decibel(dB)
- Percent(%)
- Metre(m)
- Gram(g)
- Second(s)
Supported Prefixes
The following table lists the prefixes that are supported when entering a value for a unit-aware parameter type.
| Prefix |
Term |
Value (Scientific) |
Value (Normal) |
| T |
Tera |
1 x 1012 |
1,000,000,000,000 |
| G |
Giga |
1 x 109 |
1,000,000,000 |
| M |
Mega |
1 x 106 |
1,000,000 |
| k |
kilo |
1 x 103 |
1,000 |
| d |
deci |
1 x 10-1 |
1 / 10 |
| c |
centi |
1 x 10-2 |
1 / 100 |
| m |
milli |
1 x 10-3 |
1 / 1,000 |
| u |
micro |
1 x 10-6 |
1 / 1,000,000 |
| n |
nano |
1 x 10-9 |
1 / 1,000,000,000 |
| p |
pico |
1 x 10-12 |
1 / 1,000,000,000,000 |
Note that the use of some, or all prefixes may not be applicable, depending on the parameter type. For example, no prefix is valid for a Percentage. The software will alert you to any invalid use of prefixes.
Adding a Unit-aware Component Parameter
When adding a parameter to the template (click Add in the Parameters region), use the associated Type field to choose the required unit-aware data type from the drop-down.
Choosing a supported unit-aware data type for a user parameter in a
component template. In this example, Ampere is the parameter type.
When entering a value for a component parameter that uses a unit-aware data type - either as the Default Value in a component template, or as the required value in a component definition - the following are things to consider:
- You can enter the value in a range of different formats:
- Numerical value only (e.g., 10). Note that if the data type has a unit, this will be applied automatically. Those types with units, have the unit in brackets after their name.
- Numerical value and units (e.g., 10F).
- Numerical value with prefix (e.g., 10k). The appropriate unit will automatically be added (where applicable).
- Numerical value with prefix and units (e.g., 10kF).
- Numerical value with prefix in typical engineering format (e.g., 2k2, 2k2Ohm, 10r2, 10R2). The value will automatically be normalized accordingly (e.g., 2K2 will become 2.2k).
- You can enter prefix and/or units with or without a space after the numerical value (e.g., 10uF, or 10 uF). The space will be automatically stripped.
Note that engineering abbreviations are case insensitive, so entering 2k2 is the same as entering 2K2, and entering 100R is the same as entering 100r. The only exception is M (Mega) and m (milli).
Data Validation
When a unit-aware data type is used for a component parameter, the entered value is validated against the specified data type. This ensures that the correct measurement unit for that data type is used. For example, a parameter of type Celsius cannot have a value of 10V!
Validation is performed wherever a component parameter with a unit-aware data type is used and a value for that parameter is supplied:
- When defining a default value for a parameter in a component template.
- When defining a value for a parameter as part of a component's definition in a component library.
- When configuring a range search, based on parameter value, as part of an advanced searching scheme.
Example of data validation in action within the CMPT Editor.
Defining Multiple Footprints
The CMPT Editor also provides support for defining multiple PCB footprints as part of a Component Template. Any number of footprint model links may be specified, and this will be a welcome feature for those wishing to create components that reference 3 footprints, satisfying the IPC requirements for different density levels (L (least or minimum copper), M (most, or maximum copper), and N (nominal, or median copper)).
To add an additional footprint model definition to the template, simply click Add to add a new parameter, then choose the PCBLIB entry on the drop-down menu associated to the Type field.
Turn a newly added parameter into a footprint model definition by setting its Type to PCBLIB.
The name of the parameter will change from Parameter to PCBLIB n, where n is the next available integer to distinguish between multiple footprint models (e.g. PCBLIB 1, PCBLIB 2, and so on). The default model will be the one associated to the PCBLIB entry.
An example component defined in the Component Library Editor, using a referenced Component Template. The template has three footprint models defined, which are brought
into the CmpLib. Notice that the PCBLIB model entry in the template is used as the default footprint model (PCBLIB (default)) in the component library.
Reusing a Managed Component Template Item
Using a revision of a Component Template Item - or rather referencing one from the component library used to edit a specific Component Item Revision - can be performed in the following ways.
A component library can only reference one Component Template Item at a time.
Manually from within the CmpLib
There are two ways of 'hooking up' a Component Template to the component library used for the Component Item Revision currently being edited:
- From the Template tab of the Document Options dialog (Edit » Document Options). Simply click the Choose button to the right of the Item Revision field. This gives access to the Choose Item dialog - essentially a trimmed incarnation of the Vaults panel. Use this dialog to browse to, and select the revision of the required Component Template Item. After clicking OK, a link will be created between the component library and the target revision of the Component Template Item. Evidence of this link can be seen back on the Template tab of the Document Options dialog.
Manually linking the component library to a revision of a Component Template Item, in the target vault.
The Component Template Item being used can be changed at any time - simply click Choose and select a revision of a different Component Template Item.
The status of the linked Component Template Item is reflected on the Template tab of the Document Options dialog. If a newer revision of the linked Item is available, simply click the Update To Latest button, to use that latest revision.
- From the Add menu associated with the Required Models/Parameters region of the CmpLib Editor. The Templates sub-menu lists all Component Template Items currently available in the same Altium Vault in which the Component Item itself resides. Simply click on an entry to create a link to the latest revision of that Component Template Item. Once again, verification of the link can be seen on the Templates tab of the Document Options dialog.
Quickly linking a Component Template Item from a menu of all available templates.
Inherited from the Component Library Vault Folder
You can specify a Component Template Item to be automatically used for all Component Items (and revisions thereof) stored within a Components folder within the Vault.
A default Component Template Item can only be defined for a folder of type Components.
Specify the required template using the Component Template field, when defining the folder's properties, in the Edit Folder dialog. The field's associated drop-down lists all Component Template Items currently available in the same Altium Vault in which the Components folder itself resides. Simply choose an entry to create a link to the latest revision of that Component Template Item, for each Component Item created within that folder.
Specify a default Component Template Item, to be applied to all Component Items created within the Components folder.
To not use this feature, simply leave/set the Component Template field to None.
If a Component Template is chosen at the folder level, that same template will be used, by default, when Component Items are created in child sub-folders below. This facilitates quick template inheritance to all Items in child folders.
When a CmpLib is released, it will essentially lock-in the specific revision of the Component Template used - creating a strong link to that revision, unless changed manually.
Impact on CmpLib Models and Parameters when using a Component Template
When editing a revision of a Component Item, and a revision of a Component Template Item is linked to/referenced, the following happens within the Component Library Editor, with respect to models and parameters:
- The models defined within the referenced template are added to the Model Links region.
- An existing referenced model will be kept, and the component definition will remain using that model, unless purposefully changed manually.
- The parameters defined within the referenced template are added to the Required Models/Parameters region.
Example of parameters after linking to a revision of a Component Template Item.
All parameters originating from the referenced Component Template Item are distinguished by use of the
icon. The
Show option for each template-based parameter follows the state of the corresponding
Visible option in the template.
Template-based parameters cannot be removed.
You are free to add additional user-parameters as required.
- An existing user-defined parameter that has the same name as a parameter in the linked Component Template Item, will essentially be replaced with the template version. Any existing value for that parameter will be kept (and not overwritten with the value in the template).
- Template-based parameters that are set to be shown, are grouped together in the component definitions area of the editor, with Template Parameters used as the header text.
Appearance of example template-based parameters in the area where the component definitions themselves are defined.
The fields for template-based parameters that have been marked as read-only, will display grayed values, and are non-editable. For all other template-based parameters, that have not been marked as read-only, you are free to change the values as required.
If a template-based parameter has been marked as required, but has not been given a value in the template, its field will appear with a red boundary, alerting you to the fact that a value is required for this parameter. You will not be able to release a component definition until values are defined for all required parameters.
Re-Releasing a Component Template Item
At any stage, you can come back to any revision of a Component Template Item in the Vault, and edit it directly. Simply right-click on the revision and choose the Edit command from the context menu. Once again, the temporary editor will open, with the template contained in the revision opened for editing. Make changes as required, then commit the release of the document into the next revision of the item.
Right-clicking on the top-level entry for an Item itself, will edit the latest revision of that Item.
Accessing the command to launch direct editing of an existing revision of a Component Template Item.
Downloading Released Data
Download the data stored in a revision of a Component Template Item by right-clicking on that revision and choosing the Operations » Download command from the context menu. The component template file will be downloaded into a sub-folder under the chosen directory, named using the Item Revision name. The file can be found in the Released folder therein.
Access the Download command from the top-level entry for a Component Template Item itself, to download the component template file stored in the latest revision of that Item.
Click the Explore button in the Download from Vault dialog, to quickly explore to the download folder.
