Dynamicweb Rapido

Dynamicweb Rapido is a highly configurable implementation of a frontend using Dynamicweb, and functions as an advanced starting point for developing and implementing solutions on Dynamicweb.

With Dynamicweb Rapido, you can easily configure and deploy most projects with a minimum of hassle – and custom projects are also guaranteed to be off to a good start, as we provide the foundation with a clean, maintainable and highly customizable code base.

In this document you will be introduced to the following:

  • The item types, which are used to both configure a solution and to create content
  • The templates, some of which are ViewModel-based and all of which easy to work with
  • The CSS projects Base, Rapido & Ignite – which are at the core of the Rapido philosophy of making everything maintainable, configurable, and extendable
  • The dos and don’ts of JavaScript and Ajax on Rapido – especially the don’ts
  • And much, much more…

We will also discuss some general principles for working with frontend development in teams, which will help you make your projects maintainable – and will save you lots of time in the long run. Of course, the concepts described in this document are fully optional – you are always free to implement Dynamicweb as you prefer.

If you find errors in Rapido, please don’t hesitate to contact us. Especially if we don’t follow our own rules and guidelines! 

Download rapido here:

Filename Filesize Date
Rapido1.0BETA2_Database.zip 1472 KB 22/12/2017 11:17:54
Rapido1.0BETA2_Files.zip 119359 KB 22/12/2017 11:10:16

Rapido1.0BETA2 requires Dynamicweb version 9.3.9 or newer - and MS SQL Server Management Studio 2014.

Please note that this documentation covers all of Dynamicweb Rapido, both the fundamental and the advanced topics.

If you’re only going to use the configurable part of Rapido – the part after which the project is named – some of the information may be out of scope for you. But on the plus side, it may open your eyes to interesting and inspiring new approaches and methods.

Rapido ships with a number of item types, which are a central part of the design.

In this section you can familiarize yourself with the various item types and their use:

  • The Article and Article List item types
  • The Content item types
  • The Settings item types
  • Other item types

We will also show you how to use the content items to create banners, testimonials, etc.

The Article item types are made for content with a fixed format and layout – such as blog posts, news articles, course descriptions, and so forth.

  • The Article Lists are page items which only allow a certain type of article as children
  • The Articles are page items with item fields tailored to a particular purpose

So if your news articles or blog posts always have the same layout – article items are the way to go. If not, you should use the content items to create a more dynamic composition.

If you use Article items, use the Item Publisher to publish them – don’t use the details template, link directly from the list to the article instead.

The Content item types are intended for creating content with a dynamic composition – in contrast to the Article item types which are perfect for fixed-format content.

There are four content item types:

  • The Paragraph item type
  • The Paragraph Container item type
  • The Maps item type
  • The Video item type

All of the content item types inherit from the Layout item type, which contains shared layout settings.

If you’re considering creating new item types for content, please take a moment to consider whether the existing types can do what you need to do. They are built for flexibility, and should be able to handle almost everything.

The Paragraph item type is the basic item type for creating dynamic content.

It allows you to create a title, an image, a text and a button – and to control content width on large and small devices, the relative position of the content, the image style & crop, and so on.

The Paragraph item type can be created on the paragraph list – or inside a Paragraph container item, which brings us to the next content item type.

The Paragraph container item type contains a collection of paragraphs, and some associated settings.

This item type can be used to group your content and apply configurations to the whole group, e.g. set a background color, font color, width, etc.

It also makes it easy to move the whole group up and down in the paragraph list.

The Maps item type is an easy way to create a Google Map with a marker to your content. You can enter an address to retrieve coordinates automatically – or select a location manually. You can also enter a title and some information which will be shown when the marker is clicked.

The Video item allows you to embed a video using iframes.

Like the other Content item types, you can use the Layout settings to control where the content is rendered.

The Settings item types contain the various website and page settings which can be used to configure a solution based on Rapido.

If you are not familiar with using item fields to extend the basic website and page properties, please consult the manual.

The Website settings item type extends the default website properties with a number of item fields for configuring a solution based on the Rapido CSS project – you can read more about that in the CSS section below.

The website settings cover basic configuration options such as:

  • Layout options (width, top layout, background images, etc.)
  • Logo settings
  • Navigation styles & behavior
  • Content styles
  • Etc.

The heart of Rapido’s configurable design is that these Website settings are compiled to Less variables and then the Less files are further compiled down to perfect, clean and minified CSS.

This means that the Rapido project is perfect for those projects which require relatively few changes to a standard combination of website settings

The Page item type contains a couple of fields extending the default page properties

The current release features only two:

  • A checkbox for enabling a left menu
  • A checkbox for enabling a breadcrumb

A couple of additional item types are available from the Shared folder in the item types overview. They are very simple, and all of them are used as extensions for the other item types:

Item type

Use

Notes

Button

Item type extension

Basic re-usable button settings

Comments list

Item type extension

For an optional comment system (Not fully implemented)

Font

Item type extension

Basic re-usable font settings

Social links

Item type extension

Basic re-usable social links

Since the Paragraph Container is something of a novel concept in Dynamicweb, we’ve created a couple of examples of how you accomplish common tasks using the paragraph container.

You are free to implement in your own way, of course – but maybe these examples can serve as inspiration.

If you want to create a banner (Figure 15.1), it is simply a matter of configuration:

  • Start by creating a paragraph container in Dynamicweb.
  • If you want it to be full width, check the checkbox.
  • Then create a new paragraph by clicking “Add paragraph”.
  • Then set the paragraph width to 1/1 and the Image style to “Full” (The fully blue one). 
Figure 15.1 A banner created using a content container

Service columns (Figure 16.1) are also a breeze:

  • Start by creating a paragraph container
  • Then create the wanted paragraph columns inside it.

Remember to set the column with and styles.

Figure 16.1 A service column created with a content container

A testemonial (Figure 17.1) is also a simple configuration. Create the paragraph and select the appropriate style (Fx. small image at left for each column).

Figure 17.1 A testemonial created with a content container

A layout style which is currently very popular is a huge full with row with an image at one side and text at the other. To do this:

  • Start by creating a paragraph container. Set it to full width.
  • Then create two paragraphs inside it. One of them should have an image set to use the full paragraph (The full blue icon found in image styles). The other paragraph contains the text.
  • Remember to set the width on both paragraphs to ½.

Dynamicweb Rapido uses custom design templates found in the Templates/Designs/Rapido folder. These override any template that may be defined outside of this folder.

We assume that you are familiar with the basics of working with templates in Dynamicweb – if you are not, please consult the manual.

In this section, we will go through some of the most important Rapido templates:

  • The Master template
  • The Page template
  • The Paragraph template
  • The Paragraph container template
  • Special case templates, such as clean.cshtml, NoLayout.cshtml and JSON.cshtml
  • How to work with and create email templates

We will not cover all Rapido templates here – for instance, each Article item type has a dedicated template which is self-explanatory, and there are NoEcom versions of some templates for solutions without Ecommerce.

Please note that some Rapido templates use Razor with ViewModels to retrieve content from Dynamicweb. If you are unfamiliar with how Razor and ViewModels work, please consult the manual.

The Master template contains the layout and content that is the same on all pages, such as the header, navigation and footer elements.

The Master template is organized in the following way:

  • At the top is the Mobile navigation. The mobile navigation is contained outside of the site container to make it possible to move the whole site when the mobile navigation is open.
  • The site container contains the rest of the site: Tools menu, Header, Main navigation, the content section and the footer.

The mobile navigation also has an important, hidden checkbox that makes it possible to open and close it without JavaScript.

This template is located in the Templates/Designs/Rapido folder.

The Page template contains the layout and content that is consistent on every page. The template is quite simple. It is mostly there to put the paragraphs inside the grid.

It also contains markup which handles the choices made via Page settings item types, e.g. the Left menu and Show breadcrumb flags, which control whether or not a left menu and a breadcrumb should be rendered.

The template is quite simple. It is mostly there to put the paragraphs inside the grid.

This template is located in the Templates/Designs/Rapido folder.

The Paragraph template is where all the magic around the paragraph happens. It handles both the content and the layout settings (e.g. width) from the Paragraph item type.

Please note:

  • The Paragraph template inherits the Layout template to make the column selector available.
  • The template also includes a small code block which makes it possible to use the supplied image as a background on the whole paragraph.

The code that renders the content in the Paragraph is shared with the Paragraph container template, and is located in ParagraphRender.cshtml

The paragraph renderer is quite simple. The approach here is to be able to support different configurations. Therefore, each element has its own little helper class, and they are then rendered according to the setting made on the paragraph.

Both the Paragraph, the ParagraphRender, and the ParagraphContainer templates are located in the Templates/Designs/Rapido/Paragraph folder.

The ParagraphContainer template is used to render the contents of a Paragraph container item.

  • The template also includes a small code block which makes it possible to use the supplied image as a background on the whole paragraph.

To be able to use the full width of the site, we use the concept of breaking out of the current position in the markup. For this to work, it is very important that we know exactly how the markup is made in both the master and the page templates. If you change the master and page templates, you may also have to look at how the breakout is made. 

These two templates have related but different uses:

  • Clean.cshtml – Is used for pages where only the clean text should be rendered (XML and Json feeds
  • NoLayout - Is used when a page should simply render the content. No top and no footer. May, for example, be used when rendering an order receipt.

The Json.cshtml template is used to ensure that a JSON feed is nice and clean, so your Ajax content works and everything is shiny. Use this on any page which generates a JSON feed.

You should also make sure that the checkbox Disable performance comment is checked under Settings > System > Solution settings.

Rapido contains a simple and easy to use engine for implementing email templates – an engine which ensures that your emails look good in every client, and are identical across the solution.

The email templating engine uses Razor helpers to render markup. This has the great advantage that the code can be tidy and beautiful, and still be used to create dynamic content and pass variables through the helper methods. The downside, of course, is that using them across templates (via @Include or @MasterPageFile) results in a lot of red lines in Visual Studio, and that it can be difficult to trace errors.

We believe that this tradeoff is worth it – while it may be hard trace errors, using the engine also makes email templates much less error prone.

Currently Rapido contains the following email templates:

  • The EmailMaster.cshtml template must be set as the master template in all email templates. This template is located in the root of the Rapido folder.
  • The EmailTester.cshtml template contains an example implementation of an email created using the Rapido email engine. This template is located in the paragraphs folder of the Rapido design.

The EmailTester template can also be used as a boilerplate when implementing a new email design.

To set up at page for testing simple emails in the browser:

  • Create a page and go to Page properties > Layout and select clean.cshtml as the page template
  • Create a paragraph and select the email template as the paragraph template
  • Click Show page in the ribbon bar of the test page

Try it out – log in to the solution, and go to Content > Tools > Email tester and click Show page.

The current email engine may be viewed as work in progress – we are actively working on making it both more capable and easier to use for the implementer.

Start by creating the template in the appropriate Dynamicweb folder inside the Templates/Designs/Rapido folder, e.g. in /eCom7/CartV2/Mail for an order email. Give it the same name as the default name for the template.

Then add the following to the top of the template:

@inherits RazorTemplateBase<RazorTemplateModel<Template>> @using Dynamicweb.Rendering; @MasterPageFile("../../../EmailMaster.cshtml")

The first two lines are just to declare that we are using a Dynamicweb Razor template.

In the @MasterPageFile you should link back to the design root where the email master is found. Remember to adjust this for each new template.

To add a pre-header with a generic link to an online version of the email, which all clients can read, call the @CreatePreheader() helper.

All content in the email must be enclosed by this table:

<table bgcolor="#FFFFFF" border="0" cellpadding="0" cellspacing="0" width="500" id="emailBody"> //Content must be placed as email rows here </table>

To create a footer with an unsubscribe link – a requirement for e.g. newsletters – simply call the following helper method:

@CreateSubscriptionFooter()

One of the strong points of the email engine is that it uses simple rows with columns inside to structure the email content. This makes it possible to design emails which will work on all email clients – provided that you follow these simple rules:

  • You MUST use the @CreateRow helper method to design your email
  • You MUST NOT under any circumstances introduce new tables or divs in your emails. You WILL lose email client support if you do.

Besides ensuring email client support, the row + column concept is perfectly easy to implement.

The method has three overloads + a row configuration object. That is one overload for each column that you want in the row (One to three columns are supported).

A simple row with a background color is made like this:

Column header = new Column(); header.image = logoimage; header.align = "center"; @CreateRow(header, new RowSettings { backgroundColor = "#0B85C8" });

First you create the Column object, and define what settings it should have. Then you call the CreateRow helper, and if something should be custom on the row, we create the RowSettings object.

The following method with overloads are available:

@CreateRow(Column, RowSetting); @CreateRow(Column, Column, RowSetting); @CreateRow(Column, Column, Column, RowSetting);

One more, simple, helper method is available – it simply creates a divider between two rows. The divider includes a horizontal line:

@CreateRowDivider();

The following properties are available for the column:

Property

Data type

Description

backgroundColor

STRING

 

Padding

STRING

 

The following properties are available for the RowSetting:

Property

Data type

Description

Image

STRING

 

imageSize

 

Do not use this, the property is automatically set by the columns

preheader

STRING

 

introheader

STRING

 

header

STRING

 

subheader

STRING

 

textColor

STRING

 

align

STRING

(Left, Center, Right)

link

STRING

 

linkText

STRING

 

buttonColor

STRING

 

Furthermore, the Column has a method for adding lines of text. Call it like this:

Column.text.Add(“My text”);

Rapido comes with a small set of ready build email blocks the may be re-used all over. This secures continuity in the design, and makes it easier to do recurring design tasks.

To use them, include the helpers in the template where needed:

@Include("../../EmailHelpers.cshtml")

Then just call the helpers where they should render. Sadly you will not get any code hinting on this in Visual Studio, and the helpers will be marked red, as Visual studio does not know that they exist in the included file.

The email helpers available are:

  • RenderHeaderImage()
  • RenderFooterSection()
  • RenderButton(string link, string text)

They should be self-explanatory.

For Ecommerce order emails the following helpers are available:

  • RenderRecurringDetails()
  • RenderComments()
  • RenderAddresses(string billingTitle, string deliveryTitle, string prefix)
  • RenderPaymentAndShipping()
  • RenderOrderline(LoopItem orderline, bool showImage = true)
  • RenderProduct(LoopItem product)
  • RenderGiftcards() 

In Rapido, the CSS is separated into three different projects; Base, Rapido and Ignite. At first this may seem a little messy and unnecessary, but the separation ensures that the parts which should not be messed with are not mixed in with the parts you often work with.

The concept for each of these projects is as follows:

  1. Base contains the styles that will always be needed, such as Normalize, a grid system and extremely basic form styles. This is also the fallback used for default and wireframe design.
  2. Rapido contains the styles defined in Website settings, usually as modifiers on the extremely simple rules from Base.
  3. Ignite is meant as a foundation for making custom designs. The project only contains a framework of empty CSS classes for the implementer to expand.

It is important to note that there is a hierarchy. Rapido can override Base and Ignite can override both Base and Rapido.

All three projects use the Less pre-compiler to make the CSS easier to maintain. The reason for using Less compared to Sass, is that the code footprint is much smaller. And that makes it possible for us to ship Dynamicweb with a server side compiler that compiles the Website settings variables for Rapido.

If CSS was a spoken language, a lot of dialects would exist. This is a huge challenge when working in a team or looking into code written by someone else. Therefore, we must have rules for how we speak the language. In classic programming, these dialects are known as design patterns, and the most well-known of these may be MVC.

The dialect or CSS design pattern we use in Dynamicweb is called BEM, and has been chosen because it has been available for a long time and is still widely popular. Many great sites use it – e.g. bbc.com, whiteaway.dk, mail.ru and Google Material design https://getmdl.io/index.html

BEMs main goal is to construct CSS class-names so they are consistent, isolated, and expressive.

The most basic approach introduced by BEM is that instead of nesting you use Blocks, Elements and Modifiers:

  • Block - a standalone entity which is meaningful on its own, e.g. .header, .container & .menu
  • Element - a part of a block which has no standalone meaning, but is semantically tied to its block, e.g. .menu__item & .menu__link
  • Modifier - a flag on a block or an element, used to change the appearance or behaviour, e.g.  .menu—dropdown & .button--condensed

Instead of using the widely popular approach to make themes for all your different designs, we suggest to use the class “.dw-mod" instead. This makes the CSS much smaller and ensures that no unnecessary styles are loaded, beside the fallback. Furthermore the “.dw-mod” class also makes it fully visible which elements that has been modified.

Instead of typing up a copy of the official documentation here, go read the rules and set aside time to fully understand them: http://getbem.com/introduction/

For further reading, on working effectively with CSS, you may also like these great articles:

The Base project contains styles that will almost always be needed. Do not modify this project, unless you are creating a custom project where new base classes are needed. If you need modifications, they are easy to create in Custom. The only modifications you may have to do directly in Base is configuring the variables in “abstracts/variables.less”.

Think of Base as the blueprint or wireframe, and Rapido and Custom as the real complete design. This means that if you do a lot of modifications in Ignite, it will still be able to fall back on Base.  

The Base framework is built upon http://bemskel.com/ and translated to Less, with the main difference that Sass Functions is removed and not translated. Base also includes https://necolas.github.io/normalize.css/ to let browser render the content consistently and http://leejordan.github.io/reflex/ to make a cross browser Flexbox grid system available.

The Base project provides you with a great grid system, which is available as long as you include Base.css.

The system we use is a mildly modified version of a framework called Reflex. Reflex is much like Bootstraps row + col system, with the huge difference that it uses Flexbox with a fallback to older browsers. The result is much more aligned and much more flexible content.

Basically it looks like this:

<div class=”grid”> <div class=”grid-col-12”></div> </div>

To learn more, and know how to use all the features, check out: http://leejordan.github.io/reflex/docs/

As you may already know, a really great CSS grid system for all browsers, even older versions of Internet Explorer, does not exist. The reason we use Reflex is that it gives os the advantages of using CSS flexbox, while providing fall backs for older browsers.

Reflex is certainly not perfect. When a better system become available, even for the folks who use Internet explorer or mobile Safari, we may change it. There is a few very important obstacles you should know about, while working with Reflex.

  1. Floating content right or left, using u-pull—right and u-pull—left, inside a column requires that the content is inside a div with the “grid__cell” class.
  2. The spacing between columns are defined by a padding on each column block (“grid__col-X”). When creating grids within grids, you must consider “hacking” this padding, to make everything align correctly. A quite irritating design on how this grid system works. But there is a fix. Often you simply put the class “grid__col—bleed-x” or “grid__bleed-y” on the columns, this will solve it in most circumstances. If that does not work, Rapido also has the class “paragraph-container__grid--bleed”. This removes the padding on each side of the column, and may be used inside a paragraph.

In addition to the grid system, Base contains a number of layout containers which can be used to frame and group content with.

  • The .site container contains the whole site. This makes it possible to e.g. define a background image or color on a non-full-width site.
  • The .page container contains the page
  • The .center container frames all the content which is considered to be centered if the site width is not set to 100%. In short, it is used to make the page 1000px while there is still content that stretches to both sides. It can be used in both the header, the main area, and in the footer.
  • The .paragraph container holds a single paragraph

Rapido is born with a set of website settings which can be selected in the administration, and the Rapido project contains the matching styles, usually as modifiers on the extremely simple rules from Base.

The heart of Rapido’s configurable design is that these Website settings are compiled to Less variables and then the Less files are further compiled down to perfect, clean and minified CSS.

This means that the Rapido project is perfect for those projects which require relatively few changes to a standard combination of website settings – and you should have plenty of settings to choose from, so it will be easy to create great designs for your projects.

Another use for Rapido is to make some really quick styles, and then customize them in Ignite. If you do that, we strongly suggest you remove the style-related Website settings when you are done, so no confusion is created when they don’t work as usual.

If you find the styles and website settings supplied by us too limited, it is very simple to create your own custom versions of Rapido. The only drawback is that you lose the ability to upgrade to future versions of Rapido.

The Less project which generates the rapido.min.css file can be found in /Templates/Designs/Rapido/css/Rapido:

  • The folder “abstracts” contains a file named _variables.auto.less - this is an auto-generated file containing all the variables from Website settings. The file must not be modified. But in here you can find all available properties, and then use them to generate styles for Rapido.
  • Most of these styles you will find in the folder “layout”. Here mixins are used as conditionals and generates the style chosen in Website settings. 
  • The styles may override those defined in Base. If you do not use the Website settings created from Rapido, you may remove this project completely.

Rapido comes with a list of predefined settings for configuring the design. The focus is mainly on colors and fonts. A lot of work has gone into optimizing the general user experience, and that covers a lot of the other design decisions as well - especially regarding Ecommerce.

When you save the Website settings, all variables are automatically created as Less variables in the Templates/Designs/Rapido/css/rapido/ folder, and the Less files in that folder are compiled to clean, minified CSS.

There is two things you should be aware of when working with Website settings and Less.

  • Dynamicweb does not supply any error handling while compiling the Less files. If the Less files are not compiled, you can trace for errors by test compiling In Visual studio. This is done by installing the Web compiler, and then going to Templates/Designs/Rapido/css/rapido/rapido.less, save and then trace in the Errors list. Remember to select “Build + Intellisense” in the Errors list. https://marketplace.visualstudio.com/items?itemName=MadsKristensen.WebCompiler
  • When Dynamicweb creates the variables in the auto generated file (_variables_NUMBER.auto.less), it attempts to guess which type of variable it should create. In most cases it does a fine job, but there may be circumstances where the result is a string and you need an object/integer. The fix is then to use this syntax ~'@{navigation-casing}'. For an example, see Templates/Designs/Rapido/css/rapido/layout/_navigation.less

Custom page settings are created in the same way as custom Website settings, but only Website settings are compiled to Less.

Page settings could for example be a checkbox to enable left navigation or a breadcrumb menu.

While the existing combination of settings on the paragraph and the paragraph container should make it easy to create modern and configurable designs, it is easy to expand the default options with custom settings.

For instance, if you want to make it possible to set a background color on the paragraph, simply add a color selector field to the Paragraph item type, and then implement the functionality in the Paragraph template.

As it is only the Website settings which are compiled to Less and then CSS, the corresponding CSS should be handles manually. If you need e.g. a preset color to be compiled into CSS for the paragraph, a solution is to simply render a list of saved colors, by name, on the paragraph – see the ParagraphContainer template for an example.

If you want to make custom designs real fast, Ignite is the answer. The goal of Ignite is to put all the custom, single-solution-specific styles in one place. The approach is exactly the same as when you write Less for Rapido.

There are no styles in Ignite, only empty classes ready to use. When Less compiles to CSS the empty classes are excluded. The recommendation is to primarily create mods on existing classes from Base – this ensures, that if mistakes are made there will always be a fallback.

Creating new classes that are not modifiers on existing content should, in most circumstances, not be necessary – but if you want to create a new class the best way to do so is creating a base CSS class and then a modifier class. The base class should be located in Base and the modification in Ignite.

For example, you can create .sticker in Base, and then .sticker.dw-mod in Ignite. In Base you make the basic positions and grey colors that makes the concept available. Then in Ignite you create the variation and colors.

A lot of stuff is available from the start in Base. If you would like to modify those classes, simply create them by adding .dw-mod in the templates where you want them, and then make the modifications via the Ignite less files.

If you use Ignite for your design, we recommend that you either remove the design elements related to the Website settings completely once the design is fully configured, or that you don't use the Rapido styles at all.

This is done so that no confusion may arise when someone later on goes to Website settings and makes adjustments. 

If needed, you may also create your own custom CSS classes in Ignite, and then compile the CSS directly in Visual studio. But if you do that you should be aware that the Wireframe mode only use the Base CSS and therefore won´t show your changes made in Ignite. 

The Less compiler for Visual Studio is available here: https://marketplace.visualstudio.com/items?itemName=MadsKristensen.WebCompiler

If you have any variables that should be used in Ignite, this is the place to put them.

Here you can modify or make the concepts that is made for globally re-use. A lot of examples can be found in the css/Base/Components folder.

This folder holds the more general classes, primarily for use in the Master template. It is also where the engine for the grid system should be placed. Therefore, if you want another system than the one found in Base, this is where to implement it. 

As Rapido is configurable to the extreme, and our core concept is to have one solution to rule them all, we are not using the elements part of BEM extensively. If we did, by e.g. making the product list item an element, we would have much more CSS to maintain – and this is better handled by using the Grid system and a couple of helpers.

Helpers make it easy to implement small design configurations, and they help keep the overall design very consistent. A helper always has the prefix “u-“(for utility).

To see which helpers are available, simply type “u-“ in Visual Studio – or look in the file Templates/Designs/Rapido/CSS/Base/helpers.less. It contains a collection of generic helper classes – such as the margin and padding helpers which reuse the spacing that the grid and the rest of the CSS classes use.

If you find that the existing helpers and modifiers are not enough to solve a task, you can use the Ignite CSS project to create the exact modification and classes you need.

In the past, JavaScript was the only viable option for toggling design elements on and off. These days, however, most of time you can make do with a simple, hidden checkboxes and a couple of very simple CSS classes.

On Rapido, this is the preferred approach – and the way we have implemented the mobile navigation, expand/collapse content, modals, and dropdowns.

To make this concept even more useful, we’ve created a smart, generic little JavaScript class called RememberState.js, which is used to remember the state of elements such as checkboxes in a cookie.

This means that it’s very easy to have elements such as expandable boxes remember their state the next time a user visits the page. You can also set the checkbox state via an URL parameter, for instance if you want to force a modal to open.

Read more about RememberState.js and the other JavaScript classes in Rapido below.

Rapido ships with a very small, clean and powerful package of JavaScript classes – including a tiny but powerful Ajax templating engine called Dynamo, which makes it very easy to create client-side generated content. And nothing more – no jQuery, no Angular, no nothin’.

Dynamicweb Rapido is vanilla JavaScript and will continue to be so – and we strongly advise you to take the same approach.

The reasons are many:

  • Most frameworks include stuff which will never be used and which will only bloat your project
  • Pure JavaScript is more futureproof – there’s no saying which framework will be popular next
  • Pure JavaScript often supplies simpler and more maintainable solutions to a problem
  • Many of the things JavaScript made possible a few years ago can now be done with clean CSS

So while we agree that the MVC approach supplied by e.g. Angular is great, simpler and more maintainable solutions will often be available directly in JavaScript. For instance, mobile navigations, modals and dropdown menus can now be made in pure CSS – which is what we have done in Rapido.

We also strongly advise you to not create any script blocks directly in your templates, other than the script templates for rendering. And this is very important. It will keep your templates junk-free, and the next time you visit the template it will be much easier to focus on the design. There are a very few circumstances where it is not possible to avoid. Fx. when supply the correct variant object, as we have done in the product template. 

Where JavaScript really shines, is when working with code that must be client side. The greatest example of this is when using the concepts of Ajax.

As a part of Rapido, we’ve built a very small Ajax templating engine called Dynamo. It is highly targeted Dynamicweb and how we already work with templates. The main goal for Dynamo is to separate any logic, and complex JavaScript, from the frontend, so you may fully focus on implementing the design, as you want it, by using simple, clean, markup and CSS.

It also means that every time you need Ajax, you will be implementing exactly the same way. Since most client side changes can be handled with JSON + Dynamo, you should get used to the idea that Ajax is the go-to method for updating small areas of a page. Instead of implementing complex JavaScript solutions to e.g. update a mini-cart, simply:

  • Design a JSON feed for the products in cart
  • Built the necessary script templates
  • In your design, use the Dynamo methods to update the content when a new product is added to cart

You are, of course, still free to use any other templating engine, if you have a particular favorite. We use a homebrewed engine mainly to keep the code as simple and clean as possible, while supplying just the methods and features necessary for implementing with Dynamicweb.

Please note, that future versions of Rapido may widen the scope of the Dynamo engine.

Creating Ajax with Dynamo is quite simple – and requires only knowledge of plain HTML and CSS (besides how to use the engine, of course).

You can find examples of implementations in the /Templates/Designs/Rapido/Master.cshtml template as well as the /Templates/Designs/Rapido/eCom/ProductList/AjaxProductList.cshtml template.

At the most basic level, start by creating a container like this:

<div class="js-ajax-container" id="myAjaxList" data-template="myAjaxListItem" data-json-feed="urlToTheJsonFeed" div></div>

Then create the markup template:

<script id="myAjaxListItem" type="text/x-template"> <div>data.name</div> </script

The variable must be inside markup – or it will fail.

The curly-brackets annotation – {{keyname}} – is the standard annotation used by most templating engines, e.g. Mustache.js. We use it because it is stable, easy to spot, and widely employed.

If you want to create table rows, the container must be of the type table, thead, tbody, or tfooter – see the mini cart part of Master.cshtml for an example.

Rendering sub-items from the feed is just as straight forward: 

<script id="myAjaxListItem" type="text/x-template"> <div>data.name <div id=”Variants” data-template=”variantItem”></div> </div> </script> <script id="variantItem" type="text/x-template"> <div>{{name}}</div> </script>

The sub blocks must use normal element tag names instead of the script/x-template, as you cannot put script elements inside script elements. To make the sub element render the content from JSON, the ID of the element must be the same as the key for the list from JSON you want to iterate.

The main container must use the js-ajax-container class – this is the class which Dynamo looks for when auto-initializing. But you have access to several additional properties:

Property

Value

Notes

data-json-feed

The URL for the JSON feed to retrieve data from.

Automatically updated if Dynamo is used for updating. Obligatory.

data-template

The ID for the x-template to use.

Can also be set via the key “template” in the JSON feed – this overrules the ID set on this attribute.

data-preloader

none, minimal, or overlay

To use overlay the page must contain an element with ID=”content” to let Dynamo know which content to dim and where to place the preloader.

data-save-cookie

true/false

By far the most advanced little gem in Dynamo. If true, the setting is saved in a cookie and Dynamic saves the data in a single-page cache. This makes it possible to change views in a very fast and easy ways – e.g. when changing a product list from grid-view to list-view.

data-init-onload

true/false

If set to ‘false’, Dynamo does not auto-initialize. This is useful if you want e.g. the minicart to only get content when the user mouses over the cart. This saves calls to the server and leads to a faster load time.

data-pre-render-template

The ID for the script template to use.

The pre-render template should not contain data, but is used to make a grid of boxes for rendering while waiting for the final data to load. See Paragraph/ProductsRender.cshtml for an example.

data-no-result-template

The ID of the script template which should render if no results are returned.

For an example, please see the Typehead search field.

Most of what Dynamo does happens in the background – but you do have access to a number of methods, and this section will give you an introduction to some of the most commonly used ones.

 

UpdateTemplate(id, template)

This updates the template for a given Ajax container.

  • id: The id of a particular Ajax container
  • template: The id of the new template

You can use this method to e.g. change views on a product list – here called on a button:

onclick="Dynamo.UpdateTemplate('Products', 'productItem')”

 

UpdateContent(containerId, url, updateUrl)

Use this to update the content of a given Ajax container, e.g. when clicking on a facet in a product list.

  • containerId: the id of a particular Ajax container
  • url: an URL to request new data from
  • updateUrl: true/false – if true, the browser URL will be updated

With this method, you can modify the data received by simple using parameters, added to the URL. For instance, to go to page two on a product list, you simply add &pagenum=2 to the URL. You can learn much more about this approach by examining Facets.js

 

AddContent(containerId, url)

Adds content to an Ajax container – e.g. to a product list.

  • containerId: the id of a particular Ajax container
  • url: an url to request new data from

For an example implementation check out LoadMore.js

For more advanced examples you can check out Variant.js – but please note that this is a complex example, which may be hard to follow if you’re not used to this kind of code.

Dynamo does not supply you with a way to work with conditionals – and since Razor is server side, and script templates are client side, you should generally NOT use Razor conditionals directly in your script templates.

The only circumstance where it makes sense to use C#/Razor conditionals in a template is if you want to use it one a server-side setting which is not changed dynamically, e.g. one of your website settings.

So how do you then hide, select, or disable content?

Dynamo – and most other templating engines – solves this by creating the conditional in a JSON feed, and having it supply a markup attribute or CSS class. For an example, open the Designs/Rapido/Json/ecom/ProductList/AjaxProductList.cshtml template (u-hidden).

While hiding content like this is a very common tactic, it is not always the best approach.

For instance, if a price should only be shown to a specific user, it would be much better to simply change templates for the price element.

While it is technically possible to create a small custom language in Dynamo for creating conditionals, we believe that the approach taken above helps you keep your code clean and maintainable – after all, conditionals make your code more complex, harder to read, and harder to maintain for other members of the project. It also means that there is a clean cut between data and logic – and the design.

Data may live forever, designs change as time goes on.

So if you put hard work into designing a data structure, you may create something that will be used for a very long time – maybe even past the next full site re-design. Plus, a rock-solid data design will also allow you to focus on implementing great designs.

The first rule of working with Ajax is this:

  • FIRST design your data, THEN create the templates which render the data

Since Rapido uses JSON feeds as a data source for Ajax, it’s very important that you learn how to design the JSON feeds correct and in the easiest manner.

We recommend that you use Razor/C# to generate your feeds – that will supply you with clean, understandable code with little risk of errors, and it will be very easy to add and /or reconfigure your data as necessary.

A very basic example of how to generate your feed using Razor/C# can be found in /Templates/Designs/Rapido/Json/ItemPublisher/List/CasesList.cshtml.

Open this template and read the next sections.

When designing JSON data, you start by creating the object definitions. Each object is equal to the data needed for one design template. This template may be repeated, which is done by creating a list of objects. All object definitions must be created inside the @functions {} block.

Since Dynamo uses JSON lists to render template, any template object you may need must be in a list – even if you only need one item.

In the CaseList template we have “feedObject” rendered as a list containing one item; the root object for our Case list rendering. This object, the Root object, contains the list of cases, a list of available solution types and a string telling which solution type that is selected.

When you design the objects (Models), the top model must be at the bottom (of what?). That way Visual Studio and C# will know that the other objects, you put inside, exists. In this case the object “SolutionType” and “Case”.

In the object definition we decide which data we want to be available. This will mostly consist of strings or new lists of objects. We strongly encourage you to always set a unique ID property on each object – this will make it easier to track down any problems, should they occur. Furthermore, the cache in Dynamo can use the unique ID, which means that you will easily be able to retrieve that exact object from the cache, if necessary.

You can now put the correct data into the object definitions. Code hinting should help you see which properties are available on the object you defined before.

As you can see in the CaseList example, the rest of the work is very easy. Just link the data that you are used to get via TemplateTags or the ViewModel, and loop through any lists of data that you want to render.

At the end of our code block we simply add all the newly created objects to our root list, serialize it to perfect JSON and print it out as clean text on our Razor page.

As JSON is somewhat error prone, you should always verify that your JSON lists are being rendered as you want them to be – chances are, the feed is the place to look.

To validate your JSON feed output:

  • In your frontend, right-click and Inspect
  • Go to the Network page and filter so you only see XHR content
  • Refresh the page – your data feeds should appear
  • Right-click the feed you want to inspect and click Open in a new tab
  • Your JSON feed will open in a new tab
  • Select the feed output
  • Copy-paste it into the JSONLint web tool
  • Click Validate JSON

If it validates, and something is still wrong it may be the index that is not set up correctly, a variable is null or you have a typo.

When implementing, sometimes you may need to point to a specific PageID for e.g. the page with your product catalog feed. However, using a variable containing the hardcoded ID is not a very dynamic approach.

Instead you should use the Navigation tag system to solve the task:

  • Log in to the CMS
  • Locate the page you want the PageID from - e.g. the one with the main Product Catalog.
  • Go to Page properties > Options and click on Navigation
  • Write a unique tag name, e.g. “ProductsFeed”.

Then, in the templates where you need it, in the top of the template declare the variable:

@{ Int productsPageId = GetPageIdByNavigationTag("ProductsFeed"); }

While the Dynamo template engine should be used for Ajax/Client side rendering in most circumstances, there will still be areas where small chunks of scripting will be needed.

For maintenance reasons, we advise you to keep your scripts very clean and simple, to keep the code as generic as possible, and to follow the coding style already in place.

In Rapido, we supply a small handful of JavaScript classes – here is what they do and how you use them.

Cart.js is a small class containing scripts related to the mini cart and the cart in general. Amongst other things, it makes the floating mini cart possible, and it makes client side cart actions available.

The floating mini cart is quite simple. You can have one floating mini cart, and it must have the element id “FloatingMiniCart”. The rest is automatic.

There are four cart actions available:

  • EmptyCart(this)
  • AddToCart(this, “PRODUCT_ID”, “QUANTITY”, “OPTIONAL_UNIT_ELEMENT_ID”)
  • UpdateCart(“THE_CONTAINER_HOLDING_THE_DYNAMO_AJAX_CART_CONTENT”, “URL_FOR_THE_CART_PAGE”, “CART_COMMAND”, “OPTIONAL_PRELOADER:BOOL”)
  • UpdateQuantity(“THE_CONTAINER_HOLDING_THE_DYNAMO_AJAX_CART_CONTENT”, “URL_FOR_THE_CART_PAGE”, '&CartCmd=UpdateOrderlines&QuantityOrderLineORDERLINE_ID=' + this.value, “OPTIONAL_PRELOADER:BOOL”))

To use them, you use them on your buttons – most often by putting them inside an onclick or onmouseover element attribute.

Cart commands are commands used by Dynamicweb to manipulate the card, e.g. “&cartcmd=add”, “&cartcmd=emptycart”, plus the URL parameters you wish to add, like for example “&Quantity=1”. You can read more about cart commands in the manual.

For the mini cart, the following action updates it and toggles mouseover events:

  • UpdateMiniCart(event, “THE_CONTAINER_HOLDING_THE_DYNAMO_AJAX_MINI_CART_CONTENT”, “URL_FOR_THE_MINI_CART_FEED”,)

The Search.js class handles typeahead search – and should work out of the box.

As it uses Dynamo, it should be a real breeze to implement the design exactly as you want it.

You can only have one typeahead search field per page – we recommend implementing it directly in the master template (as we have done).

The Facets.js class collaborates with Dynamo to modify the URL parameters when clicking facets on and off. The clickable facet element does not have to be a checkbox – you can use e.g. color boxes, tags, images, etc.

Facets.js is very easy to use. On your clickable facet item element, add: 

onclick="Facets.UpdateFacets(this, 'PRODUCT_DYNAMO_AJAX_CONTAINER_ID');" name="QUERY_PARAMETER” value="VALUE"

For a full implementation, look in the design folder /Paragraph/ProductsRender.cshtml

The ImageList.js class is very basic – it simply changes the URL for a main image when hovering over thumb images. To use it:

  • Add “js-thumb-btn” to all your thumbnails class attributes
  • Then add the “data-for” attribute, and type in the element id for the large image, you wish to render the image on.

If you want selections on the hovered thumbs, you must use the CSS classes found in /css/base/components/_thumbs.less

For a full implementation, look in the design folder /eCom/Product/Product.cshtml

ThieLoadMore.js class makes the advanced features of the “Load more” concept in the product list possible, using the pagination data from Dynamicweb. When creating a Load more button, start by adding: onclick="LoadMore.Next(this)" to the button element. Then you must set these attributes:

  • data-current=”CURRENT_PAGE”
  • data-page-size=”PAGE_SIZE”
  • data-total=”TOTAL_PAGES”
  • data-container=”THE_CONTAINER_HOLDING_THE_DYNAMO_AJAX_CONTENT”

You may also wish to add disable or hidden states on the button, for when there is no more pages. For a full implementation, look in the design folder /Paragraph/ProductsRender.cshtml

While the browser usually remembers a scroll position perfectly, this is not the case when you load Ajax content – and it is very important that auto-scrolling doesn’t happen before all the content is loaded.

And so the Scroll.js class has only one purpose – remembering the scroll position.

To use Scroll.js, simply add onclick=”Scroll.SavePosition(event)” to any link leaving a page where you want the scroll position to be remembered:

<a href="data.link" onclick="Scroll.SavePosition(event)"><img class="grid__cell-img" src="data.image" /></a>

This class exist to make it possible to interact with variants in the product list and on the product page.

The Variants.js class is by far the most complex of all the JavaScript classes in Rapido, and is very difficult to understand. The reasons are hard to combat – variants do not have a simple, linear relations, but a mesh of links which are very difficult to comprehend by simply looking at the data.

Variants are very complex, and hard to work with. We encourage you to simple use the implemented solution. And just know that the feature is available. 

The RememberState.js class is a little gem with two convenient uses:

  • Remember the state of an element (element attribute settings)
  • Set the state of a checkbox by an URL parameter

To remember the state of an element add the class “js-remember-state” on the element where you want the state to be remembered the next time the user visits the page. The element must have a unique id.

The second use case - setting the state of an element by URL – is very useful in Rapido, because it can be used to control UI elements (e.g. modals, dropdowns, etc.) with hidden checkboxes. This is a pure CSS approach rather than a JavaScript approach.

To use RememberState.js for that, simply add a parameter to the URL with the id of the checkbox as the parameter name and true/false as the value:

www.yoururl.com?YourCheckBoxID=true

This little script takes an entire website, and then enables a “wireframe” mode. It basically removes all custom CSS (Rapido + Ignite) and uses only the Base CSS project. Then it attempts to locate all images and replace them with a placeholder image block in instead.

Wireframe.js also includes scripts for an upcoming comment + tools system, which will be in use when choosing Wireframe mode. The full comment system is planned for a later release.

While implementing, you will usually never have a reason for looking into this part of Rapido. 

This has only one purpose; Making it possible to disable and add a preloader to a button, after clicking it. This works especially well with forms, as it makes it visually clear that the form has been submitted while also hinders double submissions.

On the regular button/form submit button, simply add: onclick="Buttons.LockButton(event)"

Everyone who’s ever worked with code knows the challenges of creating maintainable code. What is it that makes a codebase bloat into an incomprehensible monster?

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

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 it most productive to focus on when developing projects based on Rapido.

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

Here are the naming conventions in Rapido:

Type

Rule

Example

Note

HTML Element IDs

Each word must start with a capital letter (PascalCase).

id=”MySpecialElement”

 

Variables

All C# and JavaScript variables must start with a lowercase letter and each of the following words with a capital letter (camelCase)

var = mySpecialVariable

NEVER use shortened variable names like sel, opt, i etc. There are no optimization gains when doing this in frontend programming, and we want code which can be read by both computers and humans.

Methods/Functions and classes

 

Each word must start with a capital letter (PascalCase).

DoThisNow()

This makes it easy to distinguish methods, functions and classes from variables.

CSS class names

We use BEM + prefixes for CSS – no camelCase, no capital letters.

 

Please see the chapter on CSS for more about BEM.

Templates & files

Each word must start with a capital letter (PascalCase).

ProductList.cshtml

This is the most widely used naming convention in Dynamicweb.

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

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 is 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).

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 be 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 default language in the Dynamicweb backend comes from the one that is set in the browser.

  1. In Chrome go to “Settings -> Show advanced settings -> Language and input settings”
  2. Remove extra languages except English and use that as default

Right click anywhere on the page and choose “Inspect element”.

  • Click the little “Inspect element” icon at the left corner of developer tools to quickly inspect elements.
  • The little icon after “Inspect element” gives you the possibility to quick test the responsiveness of your page.
  • Disable cache in the developer tools settings
  • In developer tools settings you may choose theme = Dark, to make it better for the eye
  • While the developer tools is open you may right-click on the page refresh button, to hard refresh the page while hard cleaning the cache.

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 you do the same.
  • While the device is connected you only need choose Developer in the top and the choose the connected device.