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. 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. 

The template file can be located in any directory -- Knapsack can find the file with either a relative or absolute path. However, we recommend keeping all files related to a given component in the same folder. In our preconfigured repository, folders for components can be found in the /src/components directory.

Note: Our repository is preconfigured to support React, Web Components, and Twig template files. If you want to configure another template renderer, 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

Now that you have a new pattern in your workspace, you can integrate a design component by pointing to its template file. 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.

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

Once you have added a Code Tab, you will need to grab the file path for the source template. The path you provide can be relative to your system's root directory or the current working directory of your instance (the same directory containing your package.json file). The path will look something like /Users/yourname/documents/knapsack-example/assets/patterns/button.tsx

React
  1. Click Add a Tab.
  2. Select Code Template.
  3. Select React as the template renderer.
  4. Enter the file path to the React template file. This can either be an absolute path or a relative path from the data directory. 
  5. If you are using a default export in your React template file, leave the Named Export field blank. Otherwise, if you are using a named export, enter the Named Export.
    Note: We recommend using a default export in your React template file. This allows you to create and edit the name in Knapsack.
  6. Click Add.
Web Components
  1. Click Add a Tab.
  2. Select Code Template.
  3. Select Web Components as the template renderer.
  4. Enter the file path to the React template file. This can either be an absolute path or a relative path from the data directory. 
  5. 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. Enter a Namespaced Path. If you are using Twig namespaces, provide the same value you would use in a Twig include statement, such as “@components/button.twig”.

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 on the public 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.