Working with Items

The idea behind items is to provide administrators with a generic and powerful way of creating, managing and presenting content or data on a website.

Additionally, an item-based structure provides editors with an easy-to-use editorial interface, designed for their business needs.

At the most basic level, you can use items to:

  • Create pages and paragraphs from item types
  • Extend website, user and page properties with item fields
  • Collect data submitted by your users through an item

In order to get started with items:

  • Familiarize yourself with item types – which are the item ‘molds’ you build, and from which you and your users (e.g. editors) create new items.
  • Determine if the Item Creator app – which enables you to create item-based pages and paragraphs from the frontend – is useful for your purposes.
  • Determine if the Item Publisher app – which lets you publish items and item fields on the frontend – is useful for your purposes.

Pay special attention to the item type fields available to you – these will give you a very hands-on idea of what you can do with items.

Since items are so flexible, a comprehensive document detailing all the different ways you can work with items is impossible. The possibilities are almost endless, and that’s the point of items.

To give you, the implementer, a toolbox with which you can do almost everything you want with content.

And to give you, the editor, an easy, intuitive way of working with these endless possibilities.

The following article will therefore be limited to showing you how to do concrete, basic things with items, such as:

  • Creating and rendering item based pages and paragraphs
  • Extending website and page properties with item fields
  • Creating and using named item lists

If your license type allows only for a limited number of pages, be aware that item based pages are not exempt from this limit, and will count as part of your total number of pages.

If you have an item type created, which is enabled for pages, you will be able to create item based pages containing the fields from that item type.

Here's how.

To create an item based page from an item type:

  • Click New page on your content tree
  • Select the item type you want to use to create your page
  • Name your page and click OK

This creates the page, and takes you to the edit page view (Figure 3.1).

You can now work with the page in a regular manner, filling out the fields of your item type

Figure 3.1 Creating a new item takes you directly to the item fields, which you can then interact with

In the page footer, you will see a number next to the page ID – in this case 2. This means that this is the second page built with this particular item type. 

You can combine an item based page with features from regular pages - simply click the paragraphs button (Figure 3.3) in the ribbon bar to access a standard paragraph list.

From the standard pararaph list you can do all the things you usually do with paragraph - attach apps, add text, and so forth.

Figure 3.3 You can access a standard paragraph list using the paragraphs button

To delete an item based page simply:

  • Open a context menu for the page (Figure 4.1)
  • Click Delete page

When prompted, confirm your decision to delete the page (including all subpages and content)

Figure 4.1 Click Delete page to delete an item based page

If you delete the item type a page is created from, all pages based on that item type will be deleted. Read more about deleting item types.

To select a template for your item-based page:

  • Open the page properties
  • Go to the Layout tab on the page properties ribbon
  • Select a template using the template selector dropdown (Figure 5.1)
  • Save
Figure 5.1 Selecting a template for your item based page

You can set default templates for your item types. Read more here.

If you have an item type created, which is enabled for paragraphs, you will be able to create item based paragraphs containing the fields from that item type.

To create an item based paragraph:

  • Go to the page where you want the paragraph to be located
  • Click New Paragraph
  • Select the paragraph item type you want to use to create your paragraph
  • Name your paragraph and click OK

This creates the paragraph, and takes you to the edit paragraph view (Figure 7.1).

You can now work with the paragraph in a regular manner, filling out the fields of your item type.

Figure 7.1 Creating a new paragraph item takes you directly to the item fields, which you can then interact with

You cannot add item-based paragraphs to an item-based page. Well, you can – but not in this manner. Rather, use item specific item fields, such as the Link to item field, Item type field or Item list field. Read more about item type fields.

To attach an app to an item-based paragraph you need to check the allow app attachment checkbox in the item type settings

To delete an item based paragraph:

  • Right-click the paragraph to open the context menu (Figure 8.1)
  • Click Delete
  • When prompted to confirm, click OK
Figure 8.1 Click delete to delete an item based paragraph

If you delete the item type a paragraph is created from, all paragraphs based on that item type will be deleted. Read more about deleting item types.

To apply a template to an item-based paragraph, click the template drop down menu in the paragraph content ribbon (Figure 9.1) and select the appropriate template.

Figure 9.1 Click the appropriate template to select that template for your paragraph

Read about modifying your templates to render item field content below.

You can select default templates for your item types. Read more here.

Since items are flexible, item field content is NOT rendered automatically in frontend. Rather, you must modify or create page and paragraph templates and output content using our tags and loops.

Here’s an example, which you can modify to suit your needs.

<div class="container"> <h1>@GetValue("Item.SystemName")</h1> @foreach (var group in GetLoop("Item.Groups")) { <fieldset> <legend>@group.GetValue("Item.Group.Name")</legend> <dl> @foreach (var field in group.GetLoop("Item.Group.Fields")) { <dt>@field.GetValue("Item.Field.Name") (@field.GetValue("Item.Field.SystemName"))</dt> <dd>@field.GetValue("Item.Field.Value")</dd> } </dl> </fieldset> } </div>

For more advanced rendering options, you can use our public API - e.g. the SelectByReference method.

Read more about item tags in the template tag documentation, e.g. for Item.[FieldSystemName], Item.Area.[FieldSystemName], and the Item.Fields loop – and page loops and paragraph loops in general.

You can use items to extend page or website properties with extra fields – adding, for instance, a background color selector, a footer text, or a background image.

In this manner, you can create a number of website setting which can be used to configure the website, without having to edit any templates.

To extend website or page properties:

  • Create an item type with the relevant fields - enable it for website and page properties
  • Go to the website settings for the website you want to extend
  • Click Item type in the ribbon bar
  • Select the website properties item type using the dropdown (Figure 2.1)
Figure 2.1 Select the appropriate item type to add the item fields to your website or page properties

If you want to add variables, mixins, functions, and so forth to your CSS projects, Dynamicweb contains an implementation of the dotless project, which is set up to automatically compile all item-based website settings to a .less variable file, which is then converted to clean, minified css.

The first time a website is saved, a .config file is generated inside the /Files/Templates folder with the name Less_1.config, where 1 is the website ID.

This configuration file contains instructions for dotless – here a configuration file for Dynamicweb Rapido:

XML
<LessConfiguration> <DesignName>Rapido</DesignName> <Minification>true</Minification> <LessFilesFolder>/Files/Templates/Designs/Rapido/css/rapido/</LessFilesFolder> <VariableFiles>/Files/Templates/Designs/Rapido/css/rapido/_variables_1.auto.less,/Files/Templates/Designs/Rapido/css/base/abstracts/_variables.less</VariableFiles> <OutputPath>/Files/Templates/Designs/Rapido/css/rapido/</OutputPath> </LessConfiguration>

The nodes should contain:

  • DesignName contains the name of the design folder. If a layout is set on the website when it is saved for the first time, this will be auto-filled. Left blank, the less compiler will not run at all – which can be useful.
  • MInification controls whether the auto-generated CSS should be minified or not – set to either true or false
  • LessFilesFolder should contain the root folder where you place your project .less files – menu.less, header.less, footer.less, etc.
  • VariableFiles should contain a comma separated list of paths to the less files containing the variables used in the design-specific .less files – menu.less, etc.
  • OutputPath should contain the path to where you want the compiled min.css file – e.g. Files/Templates/Designs/YourProject/css/

Once the nodes are properly configured, a file called _variables_[areaid].auto.less is generated in the LessFilesFolder whenever a website is saved – the variables in that file can then be used inside your design-specific .less files, which are compiled to a min.css file in the folder defined in the OutputPath node from the config file.

To use the variables, simply include min.css in your master template.

If something goes wrong, you can find an error log in Files/System/Log/LessCompiler – this folder will be generated when the first error occurs.

Note: To use the same configuration across several websites, create a configuration file called less.config. When a new website or language layer is added, appropriately named .config files will be generated from this template.

Variable names are generated based on the item type field system name – following these rules:

  • If a capital letter is encountered at the beginning of a work, it is replaced by the lowercase letter
  • If a capital letter is encountered inside a system name, it is replaced by a dash and the lowercase letter

For example; GoogleFont becomes google-font, and LayoutWidth becomes layout-width.

You can generate variables from all item type field types except those who generate a complex objectItem Relations list, Product, User, Editable list, geolocation, etc. This is because these objects must be analyzed in order to determine which part(s) of the object is a meaningful property.

Named item list are used for storing items, without automatically publishing them.

Items put into a named item list:

  • Are not published automatically
  • Cannot be rendered with template tags, but must be explicitly published with an Item Publisher app
  • Are not counted as pages, if your solution has a page limit

Named item lists are created on and attached to a page, but can be published anywhere you add an Item Publisher app (including the page which the named item list is attached to).

Before you can create a named item list you must have an item type enabled for use in a named item list.

To create a named item list:

  • Go to the page properties view of a page
  • On the Advanced tab click the Item lists button (Figure 6.1) to open the item list overview
Figure 6.1 Click the item lists button to open the item list overview
  • Click Add list in the upper right corner to open the New named item list dialog (Figure 6.2)
Figure 6.2 Creating a new named item list
  • Name the (named) item list and select the appropriate item type
  • Click OK

You can now start using your named item list - which is to say; add items to it and publish them where you need them to be.

You can add items to a named item list in two ways:

  • By creating items directly in the named item list
  • By using an Item Creator which has been configured to create items in the named item list

To create an item directly in the named item list:

  • Go to the page properties of the page where your named item list is attached
  • Go to the Advanced tab
  • Click the Item list button – this opens the Item list overview window
  • Select your named item list from the dropdown menu in the upper left corner
  • Click the Add [item type name] in the lower left corner (Figure 7.1)
Figure 7.1 You can add items to an item list directly, by clicking the Add-button in the lower left corner of the item list overview

This opens a window with your item type fields, which can be filled out and saved in the standard manner. You have now created and added an item in the named item list

You can also use the Item Creator to create items

To do so:

  • Add an item creator to a paragraph, on the page which has the named item list attached
  • Configure it to fit your scenario
  • Go frontend and start creating items

Read more about the item creator and how to configure it.

Database

There is no database specific information for this subject.

ItemList

Defines which item type (ItemListItemType) is used for a given item list (ItemListId

Field name Data type Length
ItemListId int 4
ItemListItemType nvarchar 255

ItemListRelation

Links instances of items (ItemListRelationItemId) to an item list (ItemListRelationItemListId) and keeps track of sorting within that item list (ItemListRelationSort).

Field name Data type Length
ItemListRelationId int 4
ItemListRelationItemListId int 4
ItemListRelationItemId nvarchar 255
ItemListRelationSort int 4

ItemNamedItemList

Contains data on named item lists (ItemNamedItemListName) as defined in backend page properties.

Field name Data type Length
ItemNamedItemListId int 4
ItemNamedItemListName nvarchar 255
ItemNamedItemListSourceType nvarchar 50
ItemNamedItemListSourceId bigint 8
ItemNamedItemListItemListId int 4

ItemType_Database

All item types have an ItemType_{SystemName} table associated where {SystemName} = name of item type. Each column represents a field and each row an instance.

Field name Data type Length
Id nvarchar 255
ItemInstanceType nvarchar 255
Description nvarchar Max
Sort bigint 8
TableName nvarchar Max

ItemTypeId

System table for keeping track of id numbering for item types

Field name Data type Length
ItemType nvarchar 255
Current int 4
Seed int 4
ItemTypeIdAutoId int 4

ItemTypeDefinitions

Contains item type definitions on solutions where they are stored in the database rather than as XML-files.

Field name Data type Length
ItemTypeDefinitionsSystemName nvarchar 255
ItemTypeDefinitionsMetadata nvarchar Max
ItemTypeDefinitionsModified datetime 8
ItemTypeDefinitionAutoId int 4