Rapido Conventions

Everyone who’s ever worked with code knows the challenges of creating maintainable code. Why do beautiful projects so often bloat into incomprehensible monsters?

Ultimately, all code projects start with the best of intentions – not even the most evil developer sets out to write incomprehensible or unmaintainable code.

So what can you do to keep the project maintainable over time?

• Good names
• Good comments
• Simple statements
• And above all - be consistent!

Here are some of the ground rules we’ve found most productive to focus on when developing projects based on Rapido.

When coding on an existing project – and since you’re using Rapido as a base, there will always be an existing project – you must code like the locals do, in each and every area. The rule is simple, when you are extending the code base, look at how things are already done, and then continue doing it that way.

This means that if you are using JavaScript and you notice that jQuery is not included, you must not include jQuery. If you do, the locals may get very aggressive indeed. Or if someone has organized the code in a way you do not like, do not change it, unless it is not done the same way as the rest of the code.

Actually, with time the locals will be yourself and your colleagues – and as a project matures it becomes increasingly important to do things the same way. You must align, learn to approach things from the same angle, and solve problems in the same manner, with respect for the local architecture.

So what do you do if you find two files within the same project with different approaches?

You generally have two options:

• Treat each file as a village – and code in a manner true to the dialect used in each file
• Treat the project as a village – and refactor the code whenever you discover a file which does not speak the project language

So what happens when a cool inventive villager like yourself discovers a fantastic new way to do something? Can you use it? YES! But…

• All villagers – your colleagues – must agree that it’s a good idea
• It should be used across the whole village – all over the project – replacing the current practice

Like all social norms this can be annoying at times, but if you don’t take this approach you will end up with a project filled with hundreds of different “smart” ways of doing more or less the same thing. So please take this approach – even when you have the greatest idea ever!

We strongly advise you to code like the locals do – or, as they say in Russia, you and the other villagers will eventually experience sadness.

A lot of stuff is possible with CSS, but to keep your CSS maintainable follow these simple rules:

• The !Important attribute is highly illegal. There are very, very, very few circumstances where it is ok to use it – so don´t.
• Nesting CSS is also almost always forbidden, as it can be very hard to know which rule overrides which rule. One of the few circumstances where it may be necessary is when manipulating font colors, as is done in the /base/base/_helpers.less class. Another example is when using checkboxes + css to show/hide content. See /base/components/_expandable.less
• Try not to use Mixins - even though both Less and Sass supply the functionality. They make the code unnecessarily complex and hard to maintain, and it may be hard to convert it to the next popular language. The exception is when you want to use conditionals in Less – then Mixins are the only option.
• Try to limit the use of the advanced features of the pre-compilers - this will make your code a lot more maintainable in the long run.
• Use the prefix “js-” for any CSS class that JavaScript should grab. These classes may never, ever be styled. This makes it very visible that the classes are meant for JavaScript, and secures that we do not ruin them or use them wrongly
• Don't use “markup styling” like <b>, <strong>, and &nbsp;. To keep the design consistent and maintainable, use css classes instead.

Base includes a lot of re-useable generic classes, which help you write maintainable code. The advanced classes are found in the “component” folder, while the most basic ones are found in “base/base/helpers.less”. The helpers have a “u-” prefix to show that it is a helper (Utility).

Keep names consistent. It sounds easy, but in reality it’s often the hardest task of all.

Here are the naming conventions in Rapido:

Following these rules makes your code easier to read and collaborate on – whether tomorrow or a year down the line.

While there are several possible ways to work with translations in Dynamicweb, it is very important that you follow the conventions outlined below.

This will help you keep your code consistent, readable and maintainable.

• The default language should always be English – no other languages are allowed in templates
• Translation keys must be the word or sentence you want to translate:
  • Don´t @Translate("productlist_AddToCart”, “Add to cart”)
  • Do @Translate("Add to cart”, “Add to cart”)
• Never include special characters at the end of your translation:
  • Don´t @Translate("User creation is complete.”, “User creation is complete.”)
  • Do @Translate("User creation is complete”, “User creation is complete”)
• If you do not know how to translate a word or a sentence, please consult someone who does
• Don’t translate directly from one language to another – a translation must make sense in both languages:
  • Don’t go from støvsuger to dust-sucker
  • Do go from støvsuger to vacuum cleaner

We recommend that you use either Chrome or Firefox while implementing, as they are both fairly stable. Chrome seems to be a lot faster when working in the DW9 Backend, so that is currently our preferred browser.

Here are some tips which will make your life easier and your projects more successful.

The only thing you need is a Mac with Safari and an iPad or an iPhone connected to the computer.

• On the iDevice go to Settings -> Safari -> Advanced and enable “Code inspector”
• In the Safari browser on your Mac, do the same.
• While the device is connected you only need to choose Developer in the top and then choose the connected device. 

This section will provide you with knowledge regarding different aspects of Blocks and Components development. Below, you will find different tips and tricks, that improves your skills as a developer and eases the process of finding specific codes and Blocks. Please read the different sections below, to increase your comfortability with development in Rapido.

Instead of being frustrated because you can’t find the code you are looking for, just do a simple search.  

We have put a lot of work into naming things properly in Rapido.

For some, this is the classic approach. It simply requires you to learn the file structure of Rapido. Firstly, you will find everything in the “Files/Templates/Designs/Rapido” folder.

From this folder, the repeated folder design looks like this: Area -> Subarea -> Blocks folder This, for example, translates to: eCom7/CartV2/Step/Blocks. You can always find the “Custom__blocks.cshtml” file in the Blocks folder, and the root Blocks structure are always defined in files in the folder containing the Blocks folder.

On your page you can add “?debug=true” to the URL. One of the debugging benefits while debug is on, is that you can inspect the page and then get a little more help. On the elements tab in the inspector, you can now see comments on where the Blocks start and ends.

If you are missing a Block that should have been on the site, or it is at a different location than you thought, you can always print out the Blocks structure. The easiest way to do this, is to locate the file containing the root Blocks structure.

In the top locate the BlocksPage variable. In Cart.cshtml it is “checkoutPage”. Then, in the bottom of the file, write: checkoutPage.GetBlocksByStructure() Then refresh the page in the browser and look though the structure. This should provide you with the information you need.