Customizing Swift
How to customize DynamicWeb Swift
DynamicWeb Swift is built for versatility but it is also a standard solution – and sometimes you need something custom to make the customer happy. This section will teach you how to approach customizations to Swift and hopefully help you avoid some common pitfalls.
Note
Please note that this section requires a good understanding of templating in DynamicWeb – e.g. designs, templates, ViewModels, and a general proficiency with front-end development.
Built on Bootstrap 5
Swift is built using Bootstrap 5 – and we’ve taken care to only use Bootstrap whenever possible, with very little custom code for areas already handled by Bootstrap.
The only area where we really differ from stock Bootstrap 5 is on how we handle fonts (Branding) and colors (Themes), where we don’t fully use the Bootstrap 5 primary and secondary color (both set to gray) and basic font settings, and where the branding and theme choices take priority. This has been done to make the solution more end-user friendly and design-oriented.
Bootstrap 5 also features a collection of neat Javascript modules – we’ve included them all in swift.js, as the footprint is very small. This saves you from deciding on a project-to-project basis what to include; everything Bootstrap 5 should just work out of the box and you don’t need to include bootstrap.js manually.
Template structure
All frontend code for Swift is found in the Swift design folder which can be found under /Files/Templates/Designs/Swift.
As you may know, the Swift-design is built for the Visual Editor – our WYSIWYG (What You See Is What You Get) editor for creating website content – and as such the content is modular and based on item types with specific purposes and consists of:
- A set of item types for pages with specific functions – e.g. content pages, cart pages, product catalog pages, etc.
- A set of item types for various kinds of paragraphs – for creating features, navigations, search fields, product sliders, etc.
Each item type has a template associated with it – for pages these are placed in the root of the Designs-folder, for paragraphs they are placed inside a /Paragraphs subfolder. When customizing Swift, these are the templates you will be working with – which is good news, as they are all of a manageable size and quite simple to work with.
If you’re familiar with standard Dynamicweb, please note that these folders also contain templates for types of content not normally placed here, e.g. the product list and product details pages. This is because ecommerce content on Swift is rendered in a slightly unusual way – see the setup section for more information.
Some templates are placed elsewhere:
- Email: Files/Templates/Designs/Swift/Swift_Email
- Customer Center: Files/Templates/Designs/Swift/eCom/CustomerExperienceCenter
- Checkout & Cart: Files/Templates/Designs/Swift/eCom7/CartV2
Customizing Content
There are basically three paths to take when it comes to customizing Swift content:
- Use the built-in Customize feature - You can right-click an item type and select Customize. This will create the new custom item type and the template for it Please note that using this feature will result in the existing content using the original item type being switched to the new custom item type
- You can copy an existing item type and the associated template, rename them, and make them your own. This is the recommended method, as it makes it easier to upgrade down the line without having to manually merge customizations. We recommend adding a _Custom suffix to the item type and template, as this makes it easy to see which content is custom and which is standard.
- You can do your customizations directly in the system templates. This is sometimes the best approach, especially if your modifications will be very extensive across most parts of the Swift design. It comes at a cost, of course – any upgrades or bugfixes will have to be manually merged to your custom templates.
No matter which path you take you should consider closely how you approach adding new functionality to a template or an item. How will the content editor work with it? As a rule of thumb, keep the system consistent – if working with the new content type feels like working with the existing content type your editors will know what to expect.
For instance, almost all paragraph types share the same settings for styling – i.e. Theme, Spacing and Title size – so when adding a new content type you should strongly consider including them. You should also strongly consider creating presets for the content type, as they make it much easier for an editor to work with the new type.
Custom paragraph types
Most of Swift is built using paragraphs, which are item-based columns with specific purposes. Usually a paragraph type would have restrictions as to where the type may be used - by default, new paragraph types are not available anywhere, meaning editing the restrictions is an important step in creating new paragraph types. The general idea is that a paragraph type is only available where it makes sense, which helps reduce complexity for designers and editors when creating content.
If a standard paragraph doesn't quite cut it it’s quite easy to customize it:
If you want to follow path 1 from before, here is how to do that:
- Go to Settings > Content > Item Types > Swift and find the item type you want to customize
- Right-click the item type and select Customize This will create the item type and accompanying template
- Go to Assets > Templates > Designs > Swift > Paragraph and the newly created template should be positioned at the top
- Click the meatball menu and select Edit, here you should be able to customize the paragraph to your liking
The process is very straightforward. However, if you wish to avoid applying the new customized item type to all your existing content, it's advisable to follow path 2 or 3.
Here is how to create a new paragraph type using path 2 from before:
- Go to Settings > Content > Item Types > Swift and copy the item type of the paragraph you want to customize
- Name the copy – We recommend that you simply add a _Custom suffix to the system column name, as it makes it easy to identify customizations down the line
- Modify the paragraph type as you please – add or remove fields, create settings, etc.
- Remember to Save
If you do this from the backend you will notice that an item type definition file – ItemType_youritemtypename.xml – is created in the System/Content/Items folder. If you’re copying the item type definition file directly and editing the XML you’re creating this file yourself, of course.
To make sure you can use the custom paragraph type:
- Open the item type under which you want to use the new custom paragraph type – e.g. the Page item type
- Set the custom paragraph type as an allowed child under the item type restrictions
- Save
Finally, create a template for the customized paragraph type:
- Go to Assets > Templates > Designs > Swift > Paragraph and find the template matching the item type you copied
- Click on the meat ball menu next to the template and select Copy here. The copy will appear at the top
- Click on the meat ball menu next to the newly copied paragraph type and select Rename - If you name it after the system name of item type it will automatically be used when creating an item based on the type
- Modify the template to do the things you want to do
- Save
Please note that if you’re customizing highly specialized or technical columns – e.g. the columns used in the checkout flow – you will likely need to copy and customize a series of helper templates in addition to the base template, e.g. DeliveryUser.cshtml or Helpers/ShippingMethods.cshtml. Since the checkout flow is such an important part of a solution please don’t hesitate to use the Swift Forum if you have any questions.
Custom Rows
Swift ships with a set of grid rows, which are used to define the overall layout of a page – and in most cases they should be sufficient. If not, though, it’s not hard to create a custom row. The easiest approach is to copy and modify an existing row:
- Go to Settings > Content > Item Types > Swift > Grid and copy the item type you want to customize
- Name the copy – we recommend simply adding a _Custom prefix to the system name, as this makes it easy to identify custom content down the line
- Apply your changes
- Save
Next you want to include the row in the Swift grid definitions:
- Open the definition file - Files/Templates/Designs/Swift/Grid/Page/RowDefinitions.json
- Add a new element for your custom row:
- Save
To make sure the new row can be used:
- Go to Settings > Content > Item Types > Swift > Page and open the item restrictions
- Select your row as an allowed child
- Save
Finally, create a template for the custom row:
- Go to Assets > Templates > Designs > Swift > Grid > Page > Rowtemplates and find the template matching the item type you copied
- Copy this template file and rename it – the name must match the template name defined in RowDefinitions.json:
- Modify the template to do the things you want to do
- Save
When adding a row to a page now, you should be able to select the newly created custom row:
Please note that the RowDefinitions.json file may be overwritten if you upgrade to a newer version of Swift down the line – make a note of your changes and make sure they are manually merged at a later date if relevant.