Try ShortPoint nowIn this article, we will show you how to filter the news you want your users to view on your page using the Free-Text Query Use Case. This is an advanced feature where you will be able to use query language to filter the news content and present only news that is relevant to your page users.
News posts and links from across your SharePoint tenancy’s site collections can be added as content on your page using any of the ShortPoint News Connections - Site News, Hub News, or Org News. The Free-Text Query Use Case is available within these connection types.
TABLE OF CONTENTS
- Prerequisites
- Before we begin
- How to Filter News Content Using Free-Text Query Use Case
- Step 1: Insert Design Element of your choice
- Step 2: Select News Connection type
- Step 3: Complete Connection fields
- Step 4: Add properties to the Selected Properties field
- Step 5: Choose Free-text Query Use Case
- Step 6: Enter parameters and apply
- Step 7: Map properties to display in the Items tab
- Step 8: Hit Insert and Save
Prerequisites
- You have ShortPoint SPFx version 7.5.x.xx or later on Microsoft Office 365 (SharePoint Online) or SharePoint 2019 environment.
- You are a ShortPoint User with an active license.
- You have news posts and news links that have custom properties and have admin access to Site Pages library or your tenancy’s Search Managed Properties page.
Before we begin
The News Connections use two distinct SharePoint services to be able to query data from your site pages - REST API and Search API. Each API service requires a different set of property names to be used in a Free-text Query.
- REST API displays your content in real-time as news content is added or modified from its source. This is used when you select the Site News connection and pull content from a single site. It requires you to collect the Internal Name of the property you want to filter your content by.
- Search API displays content as it is crawled and indexed. This means there will be a few minutes or more delay for new or modified content to be updated and presented on your page. This is used when you select Site News and add multiple sites, Hub News, and Org News connections. It requires you to collect the Managed Property name of the property you want to filter your content by.
To know more about how to collect property names, please refer to the support article on How to Identify Custom Property Names in SharePoint
In our example, we are connecting to the news content from our site and filtering by the News Feature column.
How to Filter News Content Using Free-Text Query Use Case
Once you have the property name you want to filter your news content by, you can proceed to insert your Design Element and set up the connection.
Step 1: Insert Design Element of your choice
In the ShortPoint web part edit mode, insert or update the ShortPoint Design Element you want to use to display your news content from Page Builder.
In Modern pages
Go to the Row or Column where you want to insert your Design Element and press the blue Insert button to open Page Builder. Then choose the Design Element that best meets your design need.
In Classic pages
Click the space within the Row or Column where you want to display your news content. Go to the Insert tab on your SharePoint ribbon and press the Insert button. This will open Page Builder, where you can select the Design Element you want to use on your page.
Step 2: Select News Connection type
Go to the Connect tab and choose the news connection type you want to use. In our example, we will be using the Site News connection.
Note: Please refer to our articles on Site News, Hub News, or Org News if you need more information about each connection type.
Step 3: Complete Connection fields
Depending on the news connection, you will need to complete a few required fields.
Note: Our articles on Site News, Hub News, or Org News contains a detailed listing of all the fields and how they can be used.
Step 4: Add properties to the Selected Properties field
If you are going to filter news content using a custom column, you will need to add the Internal Name or Managed Property name of that column in the Selected Properties field.
Note: When adding Managed Property names, please ensure that you move the single quotation (‘) to the end of the list. This ensures that the new properties are included when the connection runs.
Here we are adding the Internal Name of our custom News Feature column, which is News_x0020_Feature.
Step 5: Choose Free-text Query Use Case
In the Use Cases section, select Free-text Query.
Note: You can view our article on Getting Started with Use Cases to know more about the Use Case feature.
Step 6: Enter parameters and apply
Once selected, a Use Case Parameters section will appear with an additional field to complete. You will find two types of parameter requirements based on the connection option you have chosen:
Query Parameters
A connection that requires the use of REST API will ask for Query parameters. This is used in Site News connections when you are pulling data from a single site.
Here, you can use Placeholders to have dynamic values for the parameters, and it supports two kinds of query operations: Orderby and Filter.
- Orderby
Syntax: (Column Internal Name order)
where:
Column Internal Name is the property name of the column you want to use to order it by
Order can either be asc for ascending order or desc for descending order
- Filter
Syntax: (Column Internal Name operator value)
where:
Column Internal Name is the property name of the column you want to use to filter it by
Operator can be any of the following supported query operators
Value is the property value you want to filter by
Here are the accepted operators:
| Type | Operators |
| Numeric comparisons | Lt, Le, Gt, Ge, Eq, Ne |
| String comparisons | startswith, substringof, Eq, Ne |
| Date and time functions | day(), month(), year(), hour(), minute(), second() |
In our example, we will be adding this parameter in the Query field:
Created ge datetime'[%TODAY-90%]' & News_x0020_Feature eq 1
This query asks the connection to pull news content created within 90 days from the date today and those that are considered as a News Feature.
Refinement Filters
On the other hand, a connection that will use Search API requires Refinement Filters parameters. This is used in Site News connections that are pulling data from multiple sites, Hub News connections, and Org News connections.
In this field, you can enter Keyword Query Language (KQL) queries in conjunction with the Managed Property name of the column you want to filter by. Placeholders are also supported.
Here is the query used in our example:
Author:[%Me('displayname')%] AND Created > [%TODAY-200%] AND NewsFeatureOWSBOOL:1
This query asks the connection to pull all news with the author as the individual viewing the page, created within 200 days prior to today’s date, filter by the value 1 in the News Feature column.
Note: Sorting is not supported in connections that use Search API.
Once you enter your desired Query or Refinement Filters parameters, press the Apply Parameters button and hit Connect.
Info: To know more about using query text, you can refer to this article from Microsoft that will tell you about constructing queries for Search in SharePoint: Keyword Query Language (KQL) syntax reference.
Step 7: Map properties to display in the Items tab
When the connection is established, proceed to the Items tab to map the properties you want to display on your page.
You can Preview the results to ensure that the Free-text Query filter you indicated works as you intended.
Step 8: Hit Insert and Save
Press the Insert or Update button to ensure your changes are applied to the Design Element. Then Save the web part or Publish your page.
This is a great way to filter the news content that is displayed on your page. We hope you find it useful as you design and deliver a meaningful SharePoint page.
Related articles:
