Item Publisher
The Item Publisher app is an app which is used to publish items to frontend – typically in a list or a grid format, but it's up to you.
To use this app you attach it to a paragraph in the usual manner and then:
- Select an item type and a source for the items you want to publish
- Select or create a template which controls how the items are rendered in frontend
- Set up filters if appropriate
- Enable or disable frontend-editing of items
Please note that the item publisher app comes with some perfomance overhead when the source contains many items. If you experience slow rendering speeds please consider using the query publisher to publish items instead.
App settings
Using the app settings (Figure 2.1) you control which items and item fields you want to publish.
Here you can:
- Select the item type you want to publish
- Select the area you want to publish items from. Your options are:
- Select items from this language/area – publish items from a specific website
- Select items from current language/area – publish items from the website with the app attached
- Select items under the current page – publish all items under current page (the page with the app attached)
- Select items under the following pages – publish items from one or more pages.
- Select specific item(s) – publish specific items from the item repository.
- Named item list – publish items from a named item list
- Include paragraph items – also publish the paragraph items belonging to the pages you publish
- Include child items – publish all items (children, grandchildren, and so on) under the selected page/website.
- Include inherited items – publish all items inherited from a base item type. Available from 8.6.1.0
- Show login for restricted items – list restricted pages, but require login for accessing the details
- Item fields – lists: Specify which item fields you want to show in the list view when publishing items
- Item fields – details: Specify which item fields you want to show in the details view when publishing items
The list settings (Figure 3.1) control how you render lists of items.
Here you can:
- Select the template you want to use for the list view
- Specify a sort order
- Select you list view type
- Normal provides you with ordinary paging. Write the number of items you want on a page in the Page Size field.
- Partial provides you with the option of selecting a partial list of items to show – enter the item to start from in the item from and the item to end with in item to field
- Specify a page size in items
The details settings (Figure 4.1) control how you to render the details view of each list item.
With the details settings you:
- Create or select a template
- Specify the paragraph you want to display the details view on, when a user clicks view or edit on an item – the selected paragraph needs to also have the item publisher app attached, with the same item type selected.
If you're publishing page items, you don't need to use the details template at all. You can link directly to the page instead.
With the filter settings, you can set up conditions (rules) in order to limit the subset of items published.
To set up a rule:
- Click add new rule
- Choose a field to filter on
- Add a condition and a value to test for
- Conditions available: is/is not, contains/does not contain, starts with/does not start with, and ends with/does not end with
- You may choose between the operators AND and OR when combining your filtering rules.
You can use values from the context to control which items are published:
@Request() – get value from System.Web.HttpContext.Current.Request
@Session() – get value from System.Web.HttpContext.Current.Session
@Page() – get value from current Page object, if any. (Current page exists if a valid PageID is in the query string).
@User() – get value from the current User object.
@Code() – evaluate C# code
@Paragraph() – get value from current paragraph object, if any. (Current paragraph exists if a valid ParagraphID is in the query string).
@ProductID() – get value from current product object, if any. (Current product exists if a valid ProductID is in the query string).
Examples:
@Page(MenuText) – Get title of page
@User(Name) – get name of user
@User(Email) – get email of user
@Code(System.DateTime.Now.AddDays(1)) – get tomorrow’s date
@Code(1+2) – get 3 (possible, but stupid, granted)
Finally, the Edit settings allow you to enable frontend editing of items, and the error messages settings allow you to customize the errors shown when users try to save empty or invalid field entries.
With the edit settings you can:
- Enable editing of item fields in the frontend
- Select the template you want to use for the edit page
With the error messages settings you can:
- Specify the error message on an incorrect field value used
- Specify the error message on an empty field
Read about item types and field types to learn how to make an item field required, and how to introduce validation on an item field.
Query string parameters
The Item Publisher supports query string filtering.
System type string fields can be filtered using the following operators:
Example | Filtering effect |
Name=Razor | Exact match |
Name=t* | Starts with |
Name=*t* | Contains |
Name=*t | Ends with |
System type numeric fields can be filtered using the following operators:
Example | Filtering effect |
Number=10 | equals |
Number=10&Number.op== | equals (operator specified) |
Number=10&Number.op==eq | equals (operator specified) |
Number=10&Number.op=!= | not equal to |
Number=10&Number.op=<> | not equal to |
Number=10&Number.op=< | less than |
Number=10&Number.op=<= | less than or equal to |
Number=10&Number.op=> | greater than |
Number=10&Number.op=>= | greater than or equal to |
Number.from=10&Number.to=20 | range (explicit) |
Number=10-20 | range (implicit) |
System type double fields can be filtered using the following operators:
Example | Filtering effect |
Double=0&Double.op=lt | less than |
Double=0&Double.op=gt | greater than |
System type date fields can be filtered using the following operators:
Example | Filtering effect |
DateAndTime=2014-08-01 | equal |
DateAndTime=2014-08-01&DateAndTime.op=< | before |
DateAndTime=2014-08-01&DateAndTime.op=lt | before |
DateAndTime=2014-08-01&DateAndTime.op=> | after |
DateAndTime=2014-08-01&DateAndTime.op=gt | after |
DateAndTime.from=2014-08-01&DateAndTime.to=2015-08-01 | range (explicit) |
Other useful parameters are:
Parameter | Effect |
PageSize | Forces a pagesize. Overrides the page size defined in the item publisher settings. |
orderby=[field] | Selects a field to sort by |
orderby2=[field] | Select an additional field to sort by |
direction=[ASC/DESC] | Selects a sort direction |
direction2=[ASC/DESC] | Selects an additional sort direction |
Finally, you can also override (or set) most of the app settings from the query string:
- ItemType
- IncludeParagraphItems
- IncludeAllChildItems
- IncludeInheritedItems
- sourceArea
- sourcePage
- SourceItemEntry
- SourceItemEntries
- sourceType
- ListTemplate
- DetailsTemplate
Rendering items directly in a template
The Item publisher extension tags - Item.Render/RenderItem() & Item.RenderList/RenderItemList() - are methods to render an item directly in a template without the use of a page or paragraph.
For example:
The following parameters are available to you when using the tags:
Property |
Description |
Type |
Condition |
Default |
Possible values |
ItemType |
A specific item type that you use for pages. The item fields from the selected item type is published in frontend. |
string |
Mandatory |
|
Item type system name |
ListSourceType |
Source to render item publisher list |
string |
Optional |
ItemEntry |
Area, |
ListSourceArea |
ID of a specific website to take data from all published content based on the ItemType |
string |
Mandatory if ListSourceType=Area |
|
ListSourceArea:10; |
ListSourcePage |
ID of one or multiple pages divided by semicolon to take data from the published content based on the ItemType under this/these pages |
CSV string of page ID’s |
Mandatory if ListSourceType=Page |
|
ListSourcePage:313,298; |
SourceItemEntries |
ID of one or multiple specific item type used for content. |
CSV string of tem ID’s |
Mandatory if ListSourceType=ItemEntries |
|
SourceItemEntries:3,9; |
ItemFieldsList |
Defines field set to render |
CSV string |
Mandatory if ListSourceType is Area, Page, SelfPage or ItemEntries |
|
ItemFieldsList:Fld1,Fld2; |
ListTemplate |
Defines template to render frontend |
string |
Mandatory if ItemFieldsList is used |
|
ListTemplate:ItemPublisher/List/List.html; |
ListOrderBy |
Allows to order by a specific field via its system name. You can also use Sort value which is the order that the pages are sorted in the menu tree or Created/Updated value to order the list by date creation/updating |
string |
Optional |
Created |
ListOrderBy:FldName; |
ListOrderByDirection |
Defines that order should be Ascending or Descending |
string |
Optional |
Ascending |
Ascending, Descending |
ListViewMode |
Defines ordinary paging or a partial list of items |
string |
Optional |
Normal |
Normal, Partial |
ListShowFrom |
Defines ‘from’ item in the partial list |
number |
Mandatory if ListViewMode=Partial |
1 |
ListShowFrom:1; |
ListShowTo |
Defines ‘to’ item in the partial list |
number |
Mandatory if ListViewMode=Partial |
End item |
ListShowTo:6; |
ListPageSize |
Defines list paging, parameter value is item quantity on page |
number |
Mandatory if ListSourceType is enabled |
All items |
ListPageSize:10; |
IncludeParagraphItems |
This will publish items of the defined type that are paragraphs as well as pages. |
boolean |
Optional |
False |
IncludeParagraphItems:True; |
IncludeAllChildItems |
This will return all pages (children, grandchildren and so on) under the defined source |
Optional |
|
False |
IncludeAllChildItems:False; |
ShowSecurityItems |
Allows to show items gathered within content under security |
boolean |
Optional |
False |
ShowSecurityItems:True; |
SourceItemEntry |
Defines to render data from specific item (ID) used within a content |
number |
Mandatory if ListSourceType is ItemEntry(not specified) |
|
SourceItemEntry:9; |
ItemFields |
Allows to specify item field set |
CSV string |
Mandatory with SourceItemEntry |
|
ItemFields:FieldName1. FieldName2; |
DetailsTemplate |
Defines template to render the item entry |
string |
Mandatory with SourceItemEntry |
|
DetailsTemplate:ItemPublisher/Details/Details.html; |
Filter | Default filtering value | string | Optional | All filtering values, see previous section |