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%20DESCWill 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:
- list page - http://yourdomain/Admin/Post/PostListPage.xsl
- archive list page - http://yourdomain/Admin/Post/PostArchiveListPage.xsl
- details page - http://yourdomain/Admin/Post/PostPage.xsl
There's also distinct version for forums (via posts)
- forum list page - http://yourdomain/Admin/Post/forum.xsl
- forum details page - http://yourdomain/Admin/Post/ForumDiscussion.xsl
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.
| XSL | Setting Name | Possible Values | |||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|
| PostListPage.xsl | indexList | true/[false] | This controls if the post listing items will be included in any indexed searches. | ||||||||
| postArchiveListPage.xsl | restLinks | true/[false] | This turns on the rest urls for the archive months. This requires restful urls set up in the following formats:
| ||||||||
| postArchiveListPage.xsl | showCurrent | true/[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:
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 '<' or '>'. 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=1Will provide an RSS formatted feed from posttype 33 for the last 100 days and strip any markup from the body block.