Reference library

Article number: 301655
Last updated: 25 April 2018

Extending posts

This section describes how the posts outputs and functionality can be extended via exposed methods for use with data islands. It also covers post searches and configuring the front end populations of posts. In addition to the web service access below posts can also be manipulated via query strings and form posts.

The Searchposts.aspx options

The searchposts page can be used to output many different display and filtered content from posts. Output is generally in XML so can be combined with XSL in a Sitekit data island in order to modify output. For example:

/Admin/Post/SearchPosts.aspx?custom_venue=7&field_like_name=a%27&orderby=Name%20DESC

Will return all posts with custom field 'venue' set to 7 and standard field 'name' beginning with the letter 'a' ordered by reverse name order. Searchposts only outputs approved posts.

Search posts takes the following arguments:

Argument

What it's for

id

a single post type id for the type of post to return

posttypeid_csv

a comma-separated list of post type ids

sitekit_ShortcutID

Shortcut ID of the page used to make the details page links (make sure to use allowedParameters in dataislands if not on the listings and details page)

top

no of rows [without paging]

start

first row of result to return [for paging]

rows

no of rows [for paging] (10.1)

orderby

order by fields (posts can only be ordered by non custom fields). Can also use 'orderby=hits' to sort the results by popularity. Added in 11.1

output

XML(default), RSSor ical to change output format. JSON (in 10.2)and forumXML and forumdiscussionXML also available. These latter two can be used when overriding the default forum outputs

custom_x

where x is a custom field name will search a custom field

custom_in_x

where x is a custom field name, will match when the value of custom field 'xxx' is in the list. e.g. &custom_in_gmcNum=126,535,86

custom_like_x

where x is a custom field name will allow wildcards (10.1). Uses any encoded SQL wildcards for example custom_like_dept=a%27

field_x

where x is a standard field name will search a standard field

field_in_x

will match when the value of of the pre-defined field 'x' is in the list

field_like_x

where x is a standard field name will allow wildcards

includerelated

set to 1 to include related items

top

max number of rows to return

year

year to return posts from

month

month to return posts from

day

day of month to return posts from

alldates

(for recurring events/items) set to 1 to to control whether an instance is returned for every recurring date or whether the post is just returned once

striphtml

set to 1 to remove html from the body field (10.1). Useful for preserving summaries in RSS news feeds

maxage

sets how long in days date based posts are still included (10.1)

startingbefore

Allows you to do a date range search, uses 30/09/2014 format (10.2). There is also the hotword "today" to represent toady's date (10.3)

endingbefore

Allows you to do a date range search (10.2). There is also the hotword "today" to represent toady's date (10.3)

startingafter

Allows you to do a date range search (10.2). There is also the hotword "today" to represent toady's date (10.3)

endingafter

Allows you to do a date range search (10.2). There is also the hotword "today" to represent toady's date (10.3)

postdiaryid_csv

(Added in 10.3)

cacheinmins

The period in minutes to cache for in order to improve page performance. Any kind of output from SearchPosts.aspx is cacheable except for csv, i.e. works with rss, ical, xml (Added in 10.5)

cachekey

Any integer can be used as a key to help speed up retrieval of cached searches for that script or custom data island. Basically, you would choose a random number as the key and use that particular key value in all requests from that script or island. (Added in 10.5)

facets

The facets field takes a comma-separated list of custom field names. When you use the facets field, the faceted values are inserted into the XML output, together with their counts. When you filter on these custom fields, or other fields, then these counts will change accordingly. All possible values for the facet field will be listed even when the counts are zero. (Added in 10.3)

If several custom or field names are entrained together the are combined via a logical AND.

 

Overriding the list and details XSLs

As mentioned previously it's possible to override the listing page XSL (but not for calendars) and the details page that these click through to. The output to these pages is XML from the searchposts function above. The default XSLs are below:

There's also distinct version for forums (via posts)

The best approach would be to copy a version of these URLs locally to your site, override the reference to them for the relevant page and then edit them locally to get the desired display. A tip for finding out what the automated display uses as it's searchposts input is to add the parameter skdebug=1 to the end of the page string and then view the page source. The relevant data islands will be output including references to the XSL and XML sources in use.

Custom settings in post pages

Some of the XSLs above have custom settings that can be changed (10.4). To change a setting add the desired setting name as a querystring parameter to the request url with the value set to one of the possible values.

Below are the current available settings with the default marked in square braces.

XSLSetting NamePossible Values
PostListPage.xslindexListtrue/[false]This controls if the post listing items will be included in any indexed searches.
postArchiveListPage.xslrestLinkstrue/[false]This turns on the rest urls for the archive months. This requires restful urls set up in the following formats:
Path stemParameter Template
/news/archive/year
/news/archive/year/month
/news/archive/
postArchiveListPage.xslshowCurrenttrue/[false]This sets whether the current month is included in the month lists.

Creating posts from public pages

The create posts web service described here allows posts to be created from front-end by submitting a form or sitekit form to this page. The process is to create a normal sitekit form however the form field names need to be drawn from the table below. Also in the form properties admin panel you need to submit the form to a third part URL in order for the post to be created. An example URL is below:

/admin/post/CreatePost.aspx?a=1&posttypeid=23&sitekit_siteid=3192

Argument

What it's for

sitekit_siteid or siteid

the relevant site's id

sitekit_LoggedInUser or peopleID

Current logged in user, can be passed in as a hidden field in the form auto-populated via a magic word

posttypeid

Post type to add

name

Post title

summary

Summary text

body

Body text

startdate

Start date of the relevant post

enddate

End date of the relevant post

foldershortcutid

The shortcutid the folder on the asset tree that the uploaded files will be created in. You'll need 'write' permission on that folder. (10.1)

forceuniquenames

Will generate a unique name if the same file is upload more than once. If it is 0 or false, then upload will not be allowed if file already exists (10.1)

postfiles

Multipart file upload location(10.1)

any custom field

Any of the custom fields in a given post type can also be populated via the createPosts web service. Note that their values are set via their name alone and don't need a 'custom_' prefix (10.1)

active

used to set the approved flag from front-end post submissions to bypass moderation if needed. Can only be used if the submitting user has 'administer' permissions on the asset class used for that post. If no parameter is supplied it defaults to unapproved and need manually approved in admin before its displayed either on pages or returned by the searchposts web service. (10.1)

 

All parameters are optional. If a user has publish/administrator permission in the asset class for the post type then it will let them create the post. If no rights it responds with a '403 Forbidden'. Returns the text 'SUCCESS' if it works. Input is moderated by default unless 'active' parameter is set and relevant user has administer rights.

You can only upload files via the webservice when passed through from a sitekit form. The relevant user needs to have administer rights on the target folder. The multi-file uploader field needs to be used in the form and it needs to be named 'postfiles'

Typical output is below:

front end form

A note on security

It is possible to include a front end rich text editor (RTE) for form posts. Both the RTE and its input need sanitised to an extent to maintain security. The RTE to has no option for inputting image or link buttons. There is a setting to enable posting of html into posts. Front-end values inserted into posts are made safe by escaping potentially damaging tags. Escaping is done by replacing '<' and '>' with '&lt;' or '&gt;'. If html-posting is enabled, only critical tags are escaped that are potentially exploitable for injection but if html-posting is disabled, then all tags are escaped. When creating/editing posts in admin, no tags are escaped and posts that have restricted markup added in admin should still be rendered front-end. These changes were added as security enhancements in 11.0 with reference this article and advice from Microsoft

RSS output

In addition to the searchpost XML output, posts can also output their data as standard RSS XML. The RSS-posts arguments are exactly the same as those for searchposts above the only difference being that the 'output' argument is not necessary as it only outputs in RSS format. The URL for each posts RSS feed is displayed on each respective post type editor. The RSS feeds take the following form  

/RSS-Posts.aspx?id=33&maxage=100&striphtml=1

Will provide an RSS formatted feed from posttype 33 for the last 100 days and strip any markup from the body block.

Related questions


This article was last updated on 25 April 2018. Did you find it helpful?