Customizing Rapido

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
• Customizing the Javascript:
  • Is done in js/source/Custom.js
  • Vanilla JavaScript, no jQuery

We recommend that you use Visual Studio when customizing Rapido.

Here is how to get going with a local setup in less than 30 minutes:

• First, install Dynamicweb locally in the standard manner
• Second, install the latest Rapido release

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:
  • Dynamicweb.dll
  • Dynamicweb.Core.dll
  • RazorEngine.dll
  • Rapido.dll
• To compile Less + JavaScript, you must install this Web Compiler extension

We also recommend that you use some kind of source control, like Team Foundation Server or Git.

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.

Rapido is a “Vanilla” JavaScript solution, which basically means that we use regular, clean JavaScript. It ships with a small, but simple and useful framework of JavaScript classes – such as Handlebars.js. Read more about JavaScript and Ajax on Rapido in general here.

The basic idea is to only use JavaScript when absolutely necessary – as many of the issues which were once solved using complex JavaScript can now be handled with simple CSS or easily maintained script templates likes Handlebars.js. We strongly advise against including any JavaScript frameworks or components unless strictly necessary, as it will inevitably drag you into an unnecessary maintenance hell. For the same reasons, you should stay far away from jQuery

We strongly recommend that you familiarize yourself with what is already included before adding any new JavaScript – especially Handlebars, RememberState, and the concepts of css/base/components/_expandable.less and css/base/components/_modals.less

That said, custom JavaScript can be added to the js/source/custom.js file. Don’t forget to install the WebCompiler extension in Visual Studio to compile to minified js.

Of course, we have also made it easy to extend the already included JavaScript – read more here.

The JavaScript used on Rapido can easily be extended – there are custom JavaScript events for most methods, and whenever it makes sense, you can simply use the events like this:

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.

A RapidoHook is a precise extensibility point, you can hook up to whatever you want to create an extension of the out-of-the-box JavaScript supplied with Rapido. This helps keep your projects strong, clean and easy to use.

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.

Read more about the templates on Rapido.