Migrate an existing project to use Web Spotlight
Web Spotlight is the way to go for Kontent.ai projects used for a website. When you start fresh, you just use it and don’t have to deal with anything. But what about using Web Spotlight for an already existing enterprise project?
Table of contents
Key takeaways
- Planning is the key to a successful transition to Web Spotlight. Map out all the upcoming changes.
- Add subpages to your existing navigation. It's likely easier than adjusting the predefined content type to your liking.
- Consider both navigation approaches will need to work for some time to prevent downtimes.
- Don't forget to train your staff and do a clean-up at the end.
What is Web Spotlight?
If you're not sure what Web Spotlight is and if it's suitable for your project, read our introduction to Web Spotlight and how to set up Web Spotlight.
This article will guide you through the Web Spotlight migration project, focusing on the content modeling part. Migrating to Web Spotlight will require some development. The development complexity will depend on how you approach navigation now and, therefore, how many changes you'll need to make.
1. Look before you leap
The better planned out your transition is, the fewer issues you'll need to solve on the go. Write down notes of your action plan. If unsure, consult with our support.
Most likely, you'll want to have your website with as short an outage as possible. Therefore, consider that you'll need to support both old and new navigation for some time. We recommend using an environment variable that signifies which navigation is used in the environment.
In the meantime, don't forget to purchase Web Spotlight for your subscription if you haven't yet.
Before you continue to the next step, ensure other people you'll need will make time for this transition. You'll make changes to:
- Content model (and project configuration in general) to follow Web Spotlight requirements
- Development code to incorporate changes in the content model
- Content creation process to reflect authoring through Web Spotlight
2. Set the stage
In this step, make sure you'll adjust your project in a non-production environment.
- Create a separate environment.
- Activate Web Spotlight for the newly created, non-production environment.
- (Optional) Create a project backup – Clone your project and archive the cloned copy. It's not required, but just to be extra careful.
Using an already established non-production environment?
You can use your already existing non-production environment if preferred. It will speed some actions up. For example, you don't need to spend time with additional deployment. However, getting Web Spotlight up and running in a larger project can take some time.
If you're not sure you can focus 100% on this transition, you may want to publish other updates in the meantime. In such a case, we recommend using another environment where you can deal with Web Spotlight without any disruptions.
3. Choose the right navigation approach
Because Kontent.ai is versatile, there have always been multiple ways to build the navigation. Web Spotlight works with the navigation modeled in Kontent.ai according to our best practice for navigation. That means you model the page tree via the content model, and your content creators can edit it based on their permissions.
Not using navigation modeled in Kontent.ai?
If you're using a different type of navigation, create the whole navigation logic as you would for a new project. We recommend going through the content modeling guide first and following this tutorial later.
You can use both described approaches – bind content to navigation or separate them. We recommend going with the separate (2-item) approach as it's better for larger projects prepared for omnichannel content. Moreover, Web Spotlight makes this approach more user-friendly. When editing items, it will automatically open the correct content item.
When to use the tightly-bound navigation?
Keeping your content and navigation in one content item is a more straightforward option. It means that the items you see in the Web Spotlight page tree hold both their place in navigation and the content itself. Use it for one-purpose, simpler, or learning projects.
Take this also as an opportunity to adjust your navigation if it doesn't satisfy all your needs.
4. Set up your homepage
Once you activate Web Spotlight, you'll find a new item named Homepage in your project. It comes with two elements, Content and Subpages.
- In the Subpages element, link pages to define your website's top-level navigation.
- The Content element is a linked item element and specifies what content is displayed on the homepage.
If you already have a content type and a content item for the homepage, adjust the newly created homepage to reflect the old one.
5. Add pages to your page tree
Web Spotlight creates the Page type for pages. However, using your original navigation in an already existing project will be much easier.
Ensure your navigation content types use the Subpages element instead of the Linked items element. Create the Subpages element manually for all content types where it makes sense. If you have a lot of content, use the Kontent.ai CLI to help you with these tasks.
What if I have localization in place?
If you have a multilingual website, create the page tree in one language first and then migrate the subpages to other languages. Use the Kontent.ai CLI for this task as well. This way, you’ll establish a common page tree across your multilingual project and adjust the page titles for each language.
6. Set up preview
Preview is a must for reaping the benefits of Web Spotlight. Provide preview URLs for every content type and enhance your website with clickable regions, called editable elements, using the Kontent.ai Smart Link SDK. This will let your content creators live edit the content directly from preview.
7. Redirect your stray sheep
Since you've made changes to the content model, some of your content may end up under different URLs after adopting Web Spotlight. If you're a heavy cross-linker, this could lead to lots of 404s, especially if caching plays against you.
If you don't have any support for setting redirects yet, consider whether you need to create redirect rules directly in Kontent.ai. Discuss suitable approaches with your technical staff.
8. Implementation and testing
After you finish changes to your content model, make sure your code supports the new elements. As subpages work very similarly to linked items, you'll only make a couple of adjustments.
Then, test your navigation in a non-production environment. Test the navigation from both the external and internal points of view. The navigation must work for your customers, and your authoring team must easily set the page tree structure.
9. Go live
After verifying everything works as expected, swap the environments and publish your updated code.
When the right time comes, switch to the new navigation in your app. Typically, you'll change the environment variable specifying which navigation is used and restart your application. However, specific actions can vary in different setups.
Train your staff to use the new Web Spotlight authoring experience. You can use our E-learning course and tutorial to help them.
10. There's always a clean-up
Before you close this project as another notch on your belt, devote some time to clean-up. Keeping your content model and code tidy will help you with your future endeavors. Again, use a separate environment to test that your clean-up doesn't break anything.
Remove unused elements and content types that were working for the old navigation. You can remove the logic for it; you won't need it anymore. You can also remove the Page content type if you used your content types for the original navigation.
Don't forget to clean your code as well.