Introduction
A contentcard is a placeholder for something else. It's called contentcard because the placeholder will be connected to other content or contents, so that you can create more flexible layouts with different sources of information, all displayed in one page.
If you're used to modular webpages consisting of x amounts of preconfigured modules that can be included in random order, contentcard can be considered a new type of module. The difference is that a contentcard is not preconfigured, but dynamic and developed in the Edit interface and doesn't need a new deploy of code. Another difference is that you can add a contentcard inside an existing module or any HTML property in any content.
As contentcard is the placeholder object connected to the actual content to be displayed, a contentcard template is the template defining the layout of the contentcard.
A contentcard template is a dynamic template that is compiled and rendered without a corresponding static file like a MVC View. It uses the same technology and have the same features, but you can dynamically change the layout of the view, and in some cases also the model.
A contentcard template consist of a few things:
- The code to be compiled and rendered, using Razor syntax to define the view.
- The content classes, defining the classes that can use the template
- Model source, which is one of five different use cases in how the model is defined, and how it is rendered.
- A preview model which can be used to preview the template while coding.
Why use contentcard templates?
Any template, however well designed can be too rigid in some cases. You may have a working article template, but the client want to display some dynamic content from another source which the template was not created for, and they only want to show this in one specific article.
In another scenario you may need to display some kind of contact information in templates that do not support this.
Example: How to add an article contentcard
Before delving into the different types of model sources and how they differ from each other, here is an example of how a contentcard is used. The example is an article, and in the article we want to include something from another content.
Figure 1: A HTML Editor property with Lorem Ipsum.
We press the 
symbol to insert a contentcard.
Figure 2: Select the contentcard template to use. We will use ArticleTemplate.
After the contentcard template is selected only the classes associated with the template will be listed and you pick the content you want. Since we chose the ArticleTemplate which is only valid for articles we pick the correct article from the filtered list.
Figure 3: How an inserted contentcard looks like when added. Doubleclicking it will open the content. You can move the contentcard around inside the HTMl editor, copy or delete it as you like.
How to create a contentcard template
Contentcard templates are found under the System module and you create it like any other content. A newly created template will show you an example code.
Pressing "Details" will show you the different options for using the template. They will be covered in detail further down.
If we continue from the article example above we can modify the default code into something like this:
Figure 4: An example of how a preview of an article can look like.
This code will result in the article example looking like this.
Figure 5: The article contentcard added into the HTML editor of another article.
Explanation of the details section
The contentcard template gives the editor a lot of freedom, but there intricacies that need some explanation.
Content classes
A contentcard template can be used in different contents and don't need to be matched with any concrete class type, but because the template code often is specific to a certain class type and its properties, adding content classes will minimize possible error sources. So an article template should be matched with the Article content class, a user template with the User content class etc.
Model source
5 model sources are supported.
- One content
- Multiple contents
- Current page content
- Custom model as JSON
- Cusom model as string
One content
This model source will support one content as a model, so when you add a contentcard to another content using a "One content template" you also pick the one content to be used. Correspondingly the Model in the Razor code refers to this one content.
Multiple contents
Similar to the "One content" source type, but you pick serveral contents when adding the contentcard, and the Razor code model refers to a list of contents to be iterated over.
Current page content
This model source will use the model of the current page the contentcard template is added to as model. With this model source you can add information from the same model, that might not be displayed normally.
Custom model as JSON
This model source is a bit different from the ones using other content types as models. Here you specify a JSON object in the "Custom Model" property, and this object will be parsed to a dynamic c# object and added as the Razor Model. Since this model is hardcoded to the template, you will not be able to use the templace with another model.
Custom model as string
As with the previous JSON type, here you have a custom model, but as a simple string. Maybe you want to add a disclaimer or description to a specific content?
Preview Model
When developing a template code you probably want to preview how the code looks like, that is has no compilation errors and so forth. It is only the Current page model source that do not support preview. This is because the current content is the contentcard template itself, and it makes no sense in previewing it, or making Razor code that will display it.
For the other model sources you can preview, but you need to hit the preview symbol on the blade with the Razor code editor. Doing it from the Details section will not work.
One content and Multiple contents
For the model sources One content and Multiple contents, you can add a preview model using the content picker and hit the preview symbol at the top of the blade. Depending on your model source and Razor code, the preview model will be displayed one or three times. Three is picked as default for Multiple contents in preview mode.
JSON and string contents
As the JSON object can be of any kind, the preview vil reflect that exact model. Similarly with the string. As these models are hard coded to the template, this preview is also how it will look like when added to other contents.
Advanced use and error messages
As the Razor code behaves like and is compiled like a static .cshtml view file you can write Razor code that accesses the server and server environment, giving you a very flexible component.
Error messages can be cryptic and is often provided by the compiler. Most often these errors are related to Razor code references to Model properties that does not exist, or of course incorrect c# code.
The Razor template code is compiled once and a cached version is used every time a contentcard template is previewed or rendered. In some rare cases you can get an error message complaining about "duplicate keys", indicating that the code is already compiled, but it tried to compile again. Fix this by making a small change to the code and save the code again. The save date (ticks) is used as key, identifying if a template needs to be compiled again or use a cached version.
Use external stylesheet
When you work in an MVC application each page uses a MVC template pointing to the controller and method that will render the view. Therefore an article will be linked to a corresponsing MVC template.
A MVC template can have stylesheets added to the template. So if you have an article MVC template with a stylesheet added to it and you create a contentcard template for rendering articles, then you can add the MVC template to the contentcard template under "Details" -> "Options". the MVC template's stylesheet will then be includes in the preview, and also when rendered in another content.