While Rapido is quick to configure and offers a lot of versatility out of the box, sometimes you need something a little more custom. Don´t worry, Rapido is designed to be really easy to customize and extend. It is pretty straight forward to both make small design changes and extend with whole new features.
In this document we will take a closer look at exactly how.
Here is a quick summary of the basic ways to customize Rapido:
- Customizing the CSS:
- Make small, custom changes in templates/designs/rapido/css/ignite/
- Customizing the templates:
- Create a copy of the template, rename it using a “_custom.cshtml” suffix
- Set up the reference in Dynamicweb
- Is done in js/source/Custom.js
We recommend that you use Visual Studio when customizing Rapido.
Visual Studio Setup
Here is how to get going with a local setup in less than 30 minutes:
Then set the solution up in Visual Studio:
- In Visual Studio go to File > New > Project and select ASP.NET Web Application
- Give it a name and select the location of the Rapido folder. Chose “Empty” on the next page, and click OK.
- Go to the downloaded Rapido folder and copy/move the contentsinto the new Solution folder, which automatically is created by Visual studio when creating a new project.
- In Visual Studio Solution Explorer:
- Click “Show all files”
- Right click the “hidden” files and include them in the project.
- To get proper code hinting in Visual Studio, copy at least the following dlls from the Dynamicweb bin folder to the Rapido bin folder:
We also recommend that you use some kind of source control, like Team Foundation Server or Git.
Modifying the Design
When contemplating making changes to the Rapido design you should always follow the same process:
- Start by testing if modifying the CSS could solve the task
- If that is not enough, then you can customize the Rapido templates
The reason is simple; custom CSS is very "cheap" and easy, and will likely not break compatibility with future Rapido releases and minor updates. Custom templates are harder to develop, and need careful merging on every Rapido upgrade.
Rapido ships with a full Less project called Ignite which is only for modifications – it can be found at templates/designs/rapido/css/ignite. It consists a large set of empty modifier classes ready to use – simply fill in the CSS where you need it.
Ignite ties into the same “dw-mod” modifier classes used by standard Rapido when you e.g. save the configuration choices from the Rapido website settings. For example, if you want to add a bottom border to the top navigation bar you simply locate the _navigation.less file in the ignite/layout folder, and then add the border code to the modifier like this:
As stated previously, you must install the WebCompiler extension in Visual Studio to compile the Less to CSS. When this extension is installed, Less-files are automatically compiled to minified CSS when they are saved. You can trace the progression in the blue status bar in the bottom of Visual Studio. Please note that it is not easy to see if you have introduced an error. If you suspect there may be an error, keep an eye on the status bar while saving multiple times. If there is an error, it will show in the status bar for a short time. To track down the error, click the “output” tab in Visual Studio and locate the elements which point to something Less-related.
To view the changes in the browser, remember to empty the browser cache. In Chrome you can do this by right-clicking the page, go to “Inspect”. Then right-click the “refresh” button on the left side of the address bar, and choose “Empty cache and hard reload”.
Of course you are not forced to work with the CSS classes already supplied by Rapido – feel free to create your own. The easiest way may be to simply add them in ignite/layout/_custom.less. This makes it very easy to locate the custom changes. But you could also add your own Less classes, if you want.
On Rapido, we use a CSS design methodology called BEM. It would be a good idea to familiarize yourself with this design methodology, as it ensures that your CSS will be maintainable and easy to read. Read more here or at the BEM website.
You can use the events to extend code the classic way by adding event listeners, or your can use the extensibility points supplied by us: RapidoHooks.
When you write extensions, place them in the custom.js file and remember to enable it in Dynamicweb -> Website Settings.
A list of all hooks – we supply more than 30 – can be found in Templates/Designs/Rapido/js/source/RapidoHooks.js
A RapidoHook is used like this:
The hook above is used when you want to extend the code which executes when shifting slides in a carousel. The hook may also supply available data (e.details object).
To see what is available, print it to the console like this:
This is the most basic example – but you can do more. The hook call has three arguments:
- The first is a required callback method – your extension.
- The second is type, which can be ’attach’ or ’detach’ (default), and controls whether the event should be attached or detached.
- The third is the targetElement argument, which is also optional and defaults to ’document’. It is sometimes not available because a hook has a specific target, e.g. the product list.
Here are some examples of extensions using RapidoHooks. Don't forget that you still need to write the CSS that your extension requires, and to do so in the css/ignite project.
As of Rapido 3.X, a new powerful extensibility concept called 'Blocks' has been introduced - read more here.
Blocks allow you to move around, modify and extend existing Rapido templates without touching the standard templates; all changes are located in the dedicated Custom_Blocks files, which are easy to use and maintain.
Sometimes the design options offered by Rapido are not enough. Perhaps a customer has a very clear idea about how a front page or product page should look, or perhaps you are asked to replicate an existing design in Rapido.
In those cases, you may create custom templates to solve the task at hand. There are, however, some disadvantages to this approach:
- Upgrading the solution to a new Rapido release will no longer be quite as easy
- More often than not, template changes require dedicated frontend work and expertise
For those reasons, we recommend that you first investigate whether custom CSS can do the job – but if it can’t, forge right ahead!
Start by copying the template you want to customize, and rename it with a _custom.cshtml suffix – this ensures that you and others will be able to track your changes, and makes merging your changes to new releases simpler. Remember to update the references in Dynamicweb – your custom product page template must be selected in the Product Catalog app.
In Rapido, everything is placed in some kind of block, so if your job is to move “Long description” to a new area on the product page you will simply have to locate the block, move it to where you want it, and change the container and grid classes/elements, if needed.