Connecting Code Templates to a Pattern Page

NOTE: This functionality is only available when running Knapsack locally.

Adding a Pattern to Knapsack

Patterns can be any type of component from simple to complex, including buttons, cards, menus, and more. Once your component is added to Knapsack, non-technical team members will be able to interact with the live pattern and create variations to share and include in documentation from the Knapsack Cloud UI.

Note: To make these changes to your workspace, you must be logged in and have either Admin or Editor permissions.

Prepare a template file

Before you can add a component to your workspace, you first need a template file for the new component. Supported renderers include Angular, React, Twig, Vue, Web Components, and HTML. You can create a new template file, grab one from your current design system, or duplicate an example component template that’s included in the preconfigured repository.

  • By default, template files are located within their associated renderer directory (package), inside the packages directory.
  • Every package (with exception to HTML) within the packages directory will generate a private npm package containing the dist directory and whatever else is deemed necessary within the relative package.json.
  • It should be noted that this is only the default configuration — and customizing this configuration is not only possible, but encouraged!

For example, the React templates are located within  packages/react/src:

Note: Our repository is preconfigured to supportAngular, React, Twig, Vue, Web Components, and HTML. If you have any questions regarding any of our template renderers or supported formats, contact us at help@knapsack.cloud.

Create a new Pattern Page in your workspace

After you have a template file ready, create a pattern.

  1. In Knapsack, click Add Nav Item.
  2. Select Pattern.
  3. Enter a name for the new pattern. This name does not need to be the same as your component template, and you can edit it later.
  4. Click Add.

(Optional) Add content tabs + content blocks

In addition to coded templates, you can add static or dynamic content to document your system. Add content blocks on the default Overview tab to add information about your component, or create a new content tab for more documentation space.

For more information on using content blocks, see our User Guides.

Add a template to the pattern

Note: The option to add a Code Template only appears when running Knapsack locally.

Now that you have a new pattern in your workspace, you can integrate a coded component. While there is some nuance from one templating language to the next, adding any template begins by adding a tab to the pattern page and selecting Code Template.

From there — the setup continues as you select the desired Template Renderer and fill in the required details (path and named export). Below we have outlined the process for adding a template to each supported renderer.

React

  1. Click Add a Tab.
  2. Select Code Template.
  3. Select React as the template renderer.
  4. Template Path: Enter the name of the React package. For example, @knapsack-cloud/workspace-react.
    Note: The package name is located within the package.json inside the packages/react directory.
  5. Named Export: Enter the named export.
  6. Click Add.

Vue

  1. Click Add a Tab.
  2. Select Code Template.
  3. Select Vue as the template renderer.
  4. Template Path: The path is constructed using the name of the Vue package and the path to the source template file. For example, @knapsack-cloud/workspace-vue/src/card.vue.
    Note: The package name is located within the package.json inside the packages/vue directory.
  5. Click Add.

Web Components

  1. Click Add a Tab.
  2. Select Code Template.
  3. Select Web Components as the template renderer.
  4. Template Path: Enter the name of the Web Components package. For example, @knapsack-cloud/workspace-web-components.
    Note: The package name is located within the package.json inside the packages/web-components directory.
  5. Custom Element Name: Enter the custom element name.
  6. Click Add.

Twig

  1. Click Add a Tab.
  2. Select Code Template.
  3. Select Twig as the template renderer.
  4. Template Path: The path you provide can be relative to your system's root directory or the current working directory of your instance(repo root). The path will look something like ../packages/twig/src/button/button.twig OR /Users/yourname/documents/knapsack-workspace-example/packages/twig/src/button/button.twig
  5. Namespaced Path: Provide the same value you would use in a Twig include statement, such as “@components/button.twig”.
  6. Click add.

HTML

  1. Click Add a Tab.
  2. Select Code Template.
  3. Select HTML as the template renderer.
  4. Template Path: The path you provide can be relative to your system's root directory or the current working directory of your instance(repo root). The path will look something like ../packages/html/button/button.html OR /Users/yourname/documents/knapsack-workspace-example/packages/html/button/button.html
  5. Click Add.

Angular

  1. Click Add a Tab.
  2. Select Code Template.
  3. Select Angular as the template renderer.
  4. Template Path: The path you provide can be relative to your system's root directory or the current working directory of your instance(repo root). The path will look something like ../packages/angular/src/lib/button/button.component.ts OR /Users/yourname/documents/knapsack-workspace-example/packages/angular/src/lib/button/button.twig
  5. Named Export: Enter the named export.
  6. Click add.

Next steps

Now that you have a component in your workspace, you can modify the component by adding Props and Slots.

Committing your changes

Editing content through the UI in the ways described here, when working locally, automatically writes the changes to the corresponding local files. You do not need to use the Propose Change feature and workflow.

In order to commit your changes and have them appear in the cloud workspace, your updated files will need to be merged into the main branch of the repo through your established git workflow.

For instructions on adding and changing content from the Knapsack Cloud UI, please refer here.