Tutorial 3: Items
The idea behind items is to provide website designers and content designers with a toolbox for creating item types, like ‘Blogpost’ or ‘GalleryEntry’, with exactly the fields and controls needed for that type of content.
You can create item-based paragraphs and pages – and you can extend website properties, page properties, and user properties with item fields as well.
An item type consists of:
- The item type settings which define what it is (a paragraph, a page, website properties, etc.) and other related things
- A number of item type fields and item type field groups which define and organize item content
- A set of item type restrictions which defines where an item may be used– websites, allowed parents, allowed children
The possibilities are pretty much endless – and the setup procedure may be a bit confusing at first, since you have so many options available to your, but you’ll get the hang of it in no time.
In this tutorial we are going to create item types for creating News articles and Newsletters.
- Creating an NewsArticle item type containing the fields associated with simple news articles
- Creating a Newsletter item type which can contain a number of NewsArticles
- Using Razor to render item content in frontend
- Using an Item Publisher module to publish article blurbs on a News page
If you find items exciting, you can also do the extra exercises and learn more about named item lists, the item creator module, and how to extend website and page properties using items.
Creating a NewsArticle item type
A classic news article consists of:
- A headline
- An image with a caption
- Text and image credits
- A kicker/introduction
- A number of paragraphs with sub headers and body text
Magazine articles may also contain a number of pull quotes, which are highlighted quotes rendered in the layout in a large fancy font.
To keep things simple, we will create all of these fields on a single item-based page:
- Go to Settings and click on the Item types node to open the item types overview (Figure 2.1).
- Click New item type in the toolbar to open the Item type settings overlay (Figure 2.2)
- Name the item type NewsArticle or equivalent
- In the Enable Item type for section check Page
- Set the Default view to be Item
Ignore the other settings for now and click OK.
Creating the item fields
Ok, so now you have created an item type – it is time to add some fields to it.
After creating the item type, you will see the item type interface (Figure 3.1) – this is where you create the fields you want the editor to fill in when using the item type.
We want to create a headline field first:
- Click New field in the toolbar to open the field setting (Figure 3.2)
- Name it ‘Headline’
- Select the Text type (selected by default, actually)
- Click OK - the field will be added to the General group
Repeat these steps and:
- Create two Text type fields called Author and Photographer
- Create a Long Text type field called Kicker – in the Parameters section, enter a reasonable value in the Rows field. Many field types can be configured using parameters.
- Open the file manager
- In the /Images directory, create a subfolder called News
- Go back to Settings and create a File type field called Image – check ‘Allow file upload from frontend’ and select the News folder as the base directory for the field.
- Create a Text type field called Image caption
- Create a Rich Text type field called Body Text
This is a good start, but most news articles contain more than one text section:
- Click New Group in the toolbar
- Name the group Paragraph One, then click OK
- Add a Text type field called Subhead
- Add a Rich Text type field called BodyText - system name: BodyText2
Repeat this a few times – you should have at least three paragraph groups in addition to your General group.
- Click Settings in the toolbar
- In the Use field for title dropdown, select the Headline field
You couldn’t do this before, as no fields had been created, but this will disable the regular paragraph title field which you won’t need.
Configuring the item restrictions
It is now time to define where the NewsArticle item type can be used. We want to be able to create it under a regular page, e.g. a News page, but not in the root of the website:
- Click Restrictions in the toolbar to open the restrictions overlay (Figure 4.1)
- Check your tutorial website on the list of websites
- Check Allow under a regular page in the Allowed Parents section
Creating a NewsArticle item
You can now create news articles, provided that they are located under a regular page:
- Go to your content area and create a new page called News.
- Create a subpage to News – you should be able to select your NewsArticle page item type
You should now see a page containing all the item fields you created on the item type (Figure 5.1).
Rendering item content in frontend
For each item type you create, you must create a corresponding layout template and set your item to use it.
- In your design folder, create a new Razor-file (e.g. NewsArticle.cshtml) and copy the following code to it:
- Open the website settings and switch to the Layout tab
- Click the Item page layouts button in the toolbar
- Find your item type and select the NewsArticle.cshtml in the item page layouts overlay (Figure 6.2)
- Save, then open your news article and see how it looks in frontend
Tags and Loops in Dynamicweb
In all Dynamicweb templates, you can use the @TemplateTags() command to see which template tags and loops are available to you in that context.
You can then retrieve the data inside a tag using a Get*-method:
They return safe values, so GetInteger will always return a valid integer – or a ‘0’ if the data is not an integer or the tag does not exist. If you don’t know what data type you are retrieving, use GetValue, but keep in mind that this will slow down performance in the long run.
To use a loop you must use a method called GetLoop:
Then, to get the value of a loop item, use the GetValue() method inside the loop:
You can also use the TemplateTags() helper method inside a loop to get an overview of the data available in the loop context:
Try it out now in the NewsArticle.cshtml layout – it should be fairly trivial to create something better than the example provided.
Remember, use @TemplateTags() to see which tags and loops are available in the context.
Creating a ‘Newsletter’ item type & layout
OK, so you know all the steps – let’s create a Newsletter item type:
- Create an item type called Newsletter and enable it for Page – set the default view to Item
- Create some fields – this can be anything you’d like, as long as you create one or more Link to item fields with the parameter Enable page selection checked – this will allow you to select (News articles) pages when creating a newsletter and render their content in the Newsletter.
- Configure the item type restrictions so the item type can be used on your website and under a regular page
You typically don’t want Newsletters to be directly available from your website, so go to your content tree and create a new folder called Newsletters (Figure 9.1).
Finally create a newsletter item based on your item type, then use your new implementation skills to create a Newsletter layout template.
Using the Item Publisher module
Ok, so you have news articles and newsletters, but the News page you created your news articles under is still empty. Let’s change that.
Dynamicweb contains a very handy module called the Item Publisher, and it can be used to, well, publish items somewhere.
- Open the Content area and click on the News page to open the paragraph list
- Click New paragraph and name it News List
- In the ribbon bar, click App to open the App list and select the Item Publisher module
This will open the Item Publisher module settings (Figure 10.1), where you should:
- Select your NewsArticle item type
- Specify from where you want to publish items – choose select items under the current page
Now, there are a lot of additional options and settings here, but you don’t need to worry about them right now.
Simply save and close the settings.
Open the News page in frontend – and nothing has changed, the page is still empty.
This is because no paragraph template has been selected for the News List paragraph, and this means that it defaults to using the first paragraph template in the Paragraphs folder – in my case a Footer.cshtml template. That’s not very good, so:
- Create a new template in the Paragraphs folder of your design called ModuleOnly.cshtml and write @GetValue("ParagraphModule") in it – and nothing else. This will be the template to select when you only want module output to be rendered.
- Create a new template in the Paragraphs folder of your design called default.cshtml – if this exists, it will be used by default rather than the first template in the folder. Add the following code to it:
Go back to the News List paragraph, select the ModuleOnly template and click save. Then open the News page in frontend – you should now see an output of some sort, e.g. a table listing NewsArticle items and their fields.
Now, let’s make that output a little nicer.
The Item publisher module output is controlled by two templates, a List template and Details template (Figure 11.1).
In this case, we only want to render a list of news articles and then link to the actual NewsArticle page, which contains the full article.
You can access existing templates from the module settings, as above, but when creating a new template it’s easier to go through the file manager:
- Open the Files area
- Go to Templates > ItemPublisher > List
- Create a new Razor-template called NewsList.cshtml
All templates used in Dynamicweb are placed in equivalent folders inside the Templates folder, so you can always go there and edit or view templates for the modules you have installed. Go to the module settings and select the (empty) NewsList.cshtml template as your list template, save the settings, then go back to Files and edit the template.
Since all NewsArticle items are structurally similar, and since you can create and delete items at will, it makes sense to simply use Razor to loop through all the items available and render them in the same way.
A quick @TemplateTags() in the template should reveal a number of loops available to you:
- ItemPublisher:Items.Paging.Pages, (etc.)
Use the @TemplateTags() method inside the ItemPublisher:Items.List loop to see the data available to you inside that loop:
You will have access to pretty much the same data as when you created your Newsletter template, so you can probably reuse some of your code from that template.
It should be evident, from the example below, that using the item publisher module to publish item content is pretty straight forward.
Once you’re happy with your news list, open the module settings and check out some of the other options for Select items from, to get an idea of how you can use the Item Publisher app to publish item content.
What you’ve learned – and what’s next
During Tutorial 3, you have learned:
- How to create and configure item types
- How to create items from an item type
- How to render item content in frontend using Dynamicweb template tags and loops
- How to use the item publisher module to publish item content elsewhere
Of course, this is only a very basic introduction to Item types – if you’re feeling adventurous, check out some of the extra exercises below for more options.
In the next tutorial we will get started with Dynamicweb Marketing, specifically some of the cool stuff you can do with our Email Marketing tool.
If you have extra time, or you’re extra curious, consider doing one or more of the extra exercises below.
Named item lists
Instead of creating NewsArticles as pages, and controlling whether or not they are published using the navigation settings in your templates, you can create them in a named item list instead.
Items in a named item list:
- Are not published automatically
- Must be explicitly published using an item publisher
- Are not counted as pages (if your solution has a page limit)
To try it out:
- Go to Settings > Item types
- Right-click the NewsArticle item type and copy it – call It NewsArticle2, or something similar
- Open the Settings and check the ItemLIst option under Enable item type for
- Save and close the item type
That takes care of the item type, now you must create a named item list:
- Open the Content Area click on the News page
- Click Properties in the ribbon bar to open the page properties
- Go to the Advanced tab and click item lists (Figure 15.1)
This opens the item list page (Figure 15.2).
- Click Add list, name it, then select the NewsArticle2 item type
You can now create NewsArticle2 items inside this list, then use an item publisher to publish them somewhere:
- Create a dummy article in the named item list
- Go to your news page and create a paragraph with an item publisher module attached, then:
- Select NewsArticle2 as the item type
- Under Select items from check Named item list, then select the News page and the NewsArticles list
- Select the same NewsList.cshtml template you used when publishing the NewsArticle pages before
Try out some of the Filtering options available from the Item Publisher module settings – you can filter on any field on an item.
Now, using named item lists like we did here is a bit silly, but consider the following uses:
- Create calendar items, publish them in a JSON feed and import them in external calendard
- Create a single list of gallery items, with titles, images, descriptions, and a series of categories etc. and publish them in multiple galleries across your site depending on their categorization
- Create ‘Employee’ items and publish it in all them teams an employee belongs to
And so on and so forth.
Creating items from frontend
The Item Creator module lets you create items from frontend – which means that you can have users create content without backend access.
To try it out:
- Create a page called Editor Tools
- Create a new paragraph – call it Create an article – then attach an Item Creator module to it
- Configure the module:
- Select a target page (default is the page with the module attached)
- Select create item as page as the content structure
- Select the NewsArticle item type
- Select Unpublished as the publish state on create – this lets you review user created content before publishing it, which is useful
- Select the default template (Create.html)
When you open the page in frontend, you should see a list of item fields to be filled out and saved. Try it out. The page will be created under the current page (News)
If you’ve followed this tutorial, the article should be published alongside the articles you created during the main part of the tutorial – it’s in the right location and it’s the right item type.
If you need an extra challenge, try creating a Razor based Create.cshtml template for the Item Creator.
Website & Page properties
Items can also be used to extend page or website properties with extra fields. You can then retrieve the values of those field in frontend, and render things differently according to them.
To extend website properties:
- Create a new item type called Website Settings
- Open Restrictions and enable it for your tutorial website
- Open the item type Settings and check Website- and page properties under Enable item type for
- Add a Color type field called ‘Background Color’ – enter some values in the Presets parameter if you like (e.g. #EED3D5 #EEE0E1 #D0E7CC #EFEAE1)
- Save and close
Next, go to the Content area and open the website settings for your tutorial website, then click the item type button (Figure 17.1) – then select your item type using the website properties dropdown.
At the bottom of the website settings you can see the website properties extended with the color selector (Figure 17.2) from your item type.
Select a color (or enter a color code), then save – and go to your layout file and use @TemplateTags() to observe the tags associated with the settings show up under Item.Area.*.
Use a conditional statement to check the value and do something based on it: