Introduction
Swift is designed to accommodate a wide range of customizations, enabling you to create a storefront that closely aligns with a brand’s design guidelines and functional needs. While Swift provides robust out-of-the-box styling, layouts, and backend-driven configurations, there are many scenarios where you may want to go beyond the default experience to add custom behavior or styling. This chapter explains how to do that effectively.
From Simple Tweaks to Full Extensions
Customization in Swift ranges from minor CSS adjustments to fully custom content types with dedicated layouts. You can incrementally decide how deep you want to go:
- Minor Customizations These are cosmetic changes, often handled purely with CSS. You might add a mask to an image, give headers a distinctive style, or change default button shapes and colors. Swift leverages DynamicWeb-controlled CSS variables and Bootstrap 5, providing a flexible framework for design tweaks.
- Medium-Level Customizations At this stage, you might adjust layouts or content structure without altering the core item definitions. For example, you can modify Razor templates for paragraphs or product components to change how data is rendered while using Swift’s existing fields and logic.
- Deeper Extensions When you need additional functionality or significant layout changes, consider extending the DynamicWeb item model by adding new fields—or even creating entirely new item types. This approach gives you the power to introduce custom data structures, specialized templates, and dedicated CSS. It ensures your solution can handle unique business or brand requirements.
Modifying vs. Customizing
There is a subtle but important difference between modifying and customizing Swift:
- Modifications are minor changes and typically involves overriding the original Swift CSS rules. Swift might have flavours that you need to override or improve which can be done in custom CSS — so the original Swift code remains intact. This approach is highly recommended if you want to keep your solution upgradable.
- Customizations are achieved by layering changes on top of Swift — changing existing Swift CSS, overriding layout templates, extending item types, new Razor templates, or separate CSS files. While sometimes necessary, it can complicate future upgrades.
Maintaining an Upgradable Solution
One of the key benefits of Swift is the ability to install updates and benefit from ongoing improvements. If you overwrite too many core files, applying updates can become time-consuming or break existing functionality. By carefully managing your customizations — maintaining a clear separation between Swift’s default files and your changes — you can more easily merge upstream updates into your project.
Typical customizations
Below is an overview of typical customizations you might perform in Swift, ranging from simple styling tweaks to fully custom content types. The table outlines each customization’s scope, how it is typically implemented, and its potential impact on upgradeability. Use it as a quick reference guide to select the right approach for your project’s needs while balancing complexity, effort, and maintainability.
| Customization | Description | Typical Approach | Impact on Upgradability |
|---|---|---|---|
| Minor CSS Adjustments | Tweak colors, borders, spacing, or other simple visual details. | Add a custom CSS file or override SCSS variables. | Low – Usually does not conflict with updates, provided you use separate files or partial overrides. |
| Custom Razor Templates | Change how content (e.g., rows, paragraphs, product components) is rendered, using the same fields Swift provides. | Copy or create new .cshtml templates, then override the defaults or use template selection in the backend. |
Medium – Requires merging changes if Swift updates the same templates. |
| Adding New Fields | Extend existing item types with additional properties (e.g., an extra headline, a custom link). | Modify or update the item definition XML, then edit or create corresponding Razor templates. | Medium – Depends on how extensively you modify default items; keep changes separate from core definitions. |
| Adding Components to Header/Footers | Place new sections, banners, or custom menus in the globally shared layout areas. | Duplicate or override the global _Master.cshtml (or equivalent) and insert custom logic or partial views. |
Medium – If the master layout changes upstream, merging customizations may need attention. |
| Custom Navigation | Implement a tailored menu or mega-menu beyond the default Swift navigation. | Override the default navigation Razor template, or implement a new paragraph type for navigation. | Medium – Same as above, but navigation code can change with major Swift versions. |
| Custom Product Components | Introduce new ways to display product lists, product detail blocks, etc. | Create new product-related Razor templates (or item types) referencing Swift’s existing product structure. | Medium – Product areas change often; track official Swift releases. |
| Fully Custom Layouts | Redesign entire page/row structures or create new layout frameworks. | Develop new Razor templates or page types referencing Swift’s row/paragraph architecture. | High – May significantly diverge from default Swift structure, making merges more complex. |
| Creating New Item Types | Build completely new content types with their own fields, templates, and potentially custom logic. | Define an item type XML, implement .cshtml templates in a new folder, optionally add custom CSS or JS. | High – Offers greatest flexibility but requires ongoing maintenance to keep consistent with Swift updates. |
| JavaScript Behavior Overrides | Add or modify interactive features, such as sliders, modals, or user input handling. | Override Swift’s default JS or add new scripts in a custom file that runs after Swift’s scripts. | Medium – JS updates less frequent than design changes, but conflicts may arise if Swift updates core JS heavily. |
| Advanced Theming/SCSS | Deep SCSS modifications or variable overrides to Bootstrap and Swift’s core. | Use the _src/scss/ structure (if available) or create custom SCSS partials that you build into your final CSS. |
High – Potential for merge conflicts if Swift changes SCSS architecture. |
| Integration with DW API | Fetch or manipulate data beyond standard item models, display specialized content. | Use Dynamicweb’s .NET or REST API in your Razor templates, or create custom modules and services. | High – Requires strong knowledge of DW internals; merges generally unaffected but must track API changes. |
How to Use this Table
- Look for Low-Impact Options First: If you only need minimal style tweaks, start with minor CSS overrides to preserve maximum upgradeability.
- Assess Complexity: As you move down the list, the complexity and potential upgrade risk typically increases.
- Version Control: No matter which level of customization you choose, ensure your changes are tracked in Git or a similar VCS for easier merging and rollback.
Tooling and Best Practices
Throughout this chapter, you will also learn about various tools and best practices to optimize your development workflow:
- Developer Tools Use Visual Studio Code, Git, and other modern development practices to manage and track customizations.
- Dynamicweb API For advanced scenarios, tapping into the Dynamicweb API allows you to fetch or manipulate data in ways that go beyond standard Swift configurations.
- Debugging & Performance Learn how to keep your solution efficient and user-friendly, including handling large images, managing complex SCSS structures, and more.
What’s Next
The upcoming sections will guide you through the various customization options—whether it’s a simple addition to the built-in CSS, a new Razor layout, or a custom item type. You’ll discover how to leverage Swift’s existing architecture to achieve a refined, brand-consistent experience without losing the benefits of a fully supported and continually evolving storefront solution.