Preview Your Template Files in Storybook

In a recent Meetup presentation, Tom Arild Jakobsen, Senior Consultant from Item Consulting introduced us to the world of Storybook Enonic XP application. It lets developers work on Thymeleaf or Freemarker templates with millisecond feedback loops. You will see how to set up a Storybook in your XP-project, and dig into some of the more advanced features.

What Is Storybook?

Storybook is a tool for developers, specifically designed to be run with Node.js. In the context of Enonic, Storybook allows developers to develop components in isolation and preview them with hot module reloading. This means that as developers work on their template files, CSS, or front-end JavaScript, any changes they make are instantly reflected in the browser. This tool is particularly useful for creating a component library or design system documentation, organizing and documenting components effectively.

Storybook also offers various plugins to assist with running tests, including front-end tests and accessibility checks. In this context, a "story" refers to an instantiated component or template, which can be a sub-template or part of a component. This typically involves HTML, styles, and front-end JavaScript, excluding any backend logic from the controller in Enonic. Storybook focuses purely on the front-end aspects.

The tool was initially built for use with front-end frameworks like React, Vue, or Svelte. However, in the Enonic ecosystem, components such as pages, layouts, and parts are well-suited for integration with Storybook for previews and development.

Recently, support for Freemarker and Thymeleaf, popular backend template engines used with Enonic, has been added to Storybook. Although Freemarker is more thoroughly tested, the support extends to both languages. Developers can install Storybook from the Enonic market for development purposes only, as it is not intended for production environments due to potential security risks. Configuration safeguards are in place to prevent accidental production installation, but developers should exercise caution.

See also: Why choose Enonic's headless CMS when building a Next.js website »

Overall, Storybook provides a robust environment for front-end development in Enonic, enhancing the workflow with immediate visual feedback and comprehensive documentation capabilities.

Why Use Storybook with Enonic XP?

Using Storybook with Enonic XP offers several advantages, primarily centered around its efficient feedback loop and documentation capabilities. 

1. Immediate Feedback with Hot Module Reloading

One of the key benefits is the quick feedback loop. With hot module reloading, as soon as you press save, your preview updates instantly. This eliminates the need to move your cursor away from your code, allowing you to maintain your focus and workflow without interruptions.

2. Efficient Code Reviewing

Storybook allows you to set up pre-configured data objects or models to test different configurations of your components. This means you don't need to create content manually to preview your components. While it's essential to test the final product in Enonic XP before passing a code review, Storybook provides a great initial overview, helping you identify and fix mistakes quickly.

3. Documentation and Demoing

Storybook is also a valuable tool for documenting your components. By organizing your component library within Storybook, you create a comprehensive documentation resource. This is especially useful for demoing your components, showcasing their functionality and design.

4. Utility Library for Easy Integration

To get started with Storybook in your project, you need to install the application and integrate some utility libraries. These libraries include files named `.stories.js` or similar, which contain your component stories. A utility library has been created to simplify this process, providing TypeScript types and other necessary tools. Detailed documentation is available to guide you step by step through the setup process.

Overall, Storybook enhances the development workflow in Enonic XP by providing immediate visual feedback, streamlining code reviews, and offering robust documentation and demoing capabilities.

Demo/Live Coding

During the live coding demo, Tom Arild demonstrated the use of Storybook to manage and preview components within a project. Tom Arild started by running Storybook using the `npm run storybook` command. In Tom Arild's project, he has created a library that contains different components, which he refers to as "blocks." These blocks, configured with titles and items, form the basis of an accordion component. The accordion's structure and rendering logic are managed through a template that iterates over the items, generating the accordion's content.

Opening the story file `blocksAccordion.stories.ts`, Tom Arild highlighted the configuration setup for the stories and the story object itself. The story object specifies the classes and items array used in rendering. By updating the title of the first accordion item and saving the file, changes are instantly reflected in the preview, demonstrating the live reloading capability of Storybook.

Next, Tom Arild proceeded to create a story for a new component, the "fact box." He added a new file and exported a default configuration to prevent errors. After configuring the title to "blocks/factbox," the story appeared but needed further setup for proper preview. Using the server flavor of Storybook, Tom Arild specified the server parameters and the path to the template file.

He encountered errors due to missing data, which he resolved by passing the required arguments, such as the title "Hello, Factbox." Fixing a bug in the template (renaming a variable from "body" to "text") allowed the preview to display correctly. He then imported CSS to style the fact box properly.

Additionally, Tom Arild configured control options for the component's input parameters, using TypeScript types to ensure valid input values. This included creating reusable input controllers for themes, allowing users to switch between different styles using radio buttons.

Finally, Tom Arild showcased the ability to use inline templates within Storybook for testing partial templates. This approach enables the inclusion of other template files, providing a powerful tool for comprehensive testing. The toolkit covers all types of templates used in Tom Arild's projects, facilitating the development and documentation process. Storybook proves to be a quick and effective way to preview and document server-rendered components, especially for projects that utilize traditional server-side rendering.

Questions & Answers

Question: What is it that shows the story in Storybook itself, or is there some other plugin involved?

Answer: It's mainly Storybook itself. What Tom Arild has in addition are extra Webpack loaders that can import FTL files for Freemarker or HTML files for Thymeleaf and follow those dependency graphs. By doing that import, it becomes part of the dependency graph, enabling hot module reloading.

Question: If Tom Arild changes something, does Storybook pick up the changes?

Answer: Yes, Storybook picks up the changes. For example, the CSS is imported directly in the file. In Tom Arild's assets folder, he has a higher level of CSS that points to all other files and builds one bundle. For Storybook, he prefers more pinpointed imports. Common styles that will be applied to all stories are configured in the Storybook folder, and more exact imports are used in each story.

Question: Has Tom Arild come up with his own styling, or is he using Storybook's?

Answer: Everything in the middle is Tom Arild's own styling. The sidebars and everything else are Storybook, but the iframe in the middle shows only the styles and front-end JavaScript that Tom Arild adds to it.

Question: Is it configurable to move the story files somewhere else, maybe another repository or folder?

Answer: Yes, it's configurable. Tom Arild likes to keep his stories files together with the components they are testing, but you could potentially put them into a separate repo or another folder. Storybook will check for all files with stories.ts and use them to create the list of stories. However, you can't uncritically share files between your XP environment and your Storybook environment due to potential dependencies and path issues.

Question: Can you elaborate on the functionality exposed by the XP app you made?

Answer: The XP app exposes a service that takes the ID, which is the path to the file, and query parameters for the model, then renders out the HTML and returns it. It includes functionality to unpack or stringify JSON objects sent as query parameters, deserialize date inputs server-side, and convert them into the appropriate Java object shape for use in templates. This process allows for the integration of Java time datetime objects in the templates.

Question: How does this integration handle datetime objects?

Answer: The template uses either Thymeleaf or Freemarker code to render out the string from datetime objects. There is functionality to deserialize date inputs server-side in the XP application to match Java object shapes, making it possible to use Java types effectively in the templates.