Widget operations

Overview

The basic flow of editing the layout of a page is the following:

Lock the page
It is important to lock the page before modifying it, because this way other users can see that this page is being edited by someone else and they will see a message that it is currently not available for modifications on their end.
To lock a page, perform procedure Page lifecycle operations » Lock a page.
Edit the layout
After you have locked a page, you can then proceed with adding and removing widgets on and from the page, moving widgets around the page, or updating widgets on the page.
Publish the page
For the changes that you made to the layout of the page to take effect, you must publish the page after editing it.
To publish a page, perform procedure Page lifecycle operations » Publish a page.
Unlock the page
After you have published a page, you must unlock it, so that other users have access to it.
To unlock a page, perform procedure Page lifecycle operations » Unlock a page.

IMPORTANT: The following endpoints are designed to support .NET Core widgets only. You cannot use the widget operations endpoints for MVC widgets.
For a comparison on using .NET Core vs using MVC framework when developing widgets, see Development comparison.

You can obtain the structure of a widget together with its properties and their values.

To do this, execute a GET request to the following endpoint:

{baseurl}/api/default/pages({page_id})/Default.GetPropertyValues(componentId={widget_key})

Where:

{page_id} is the ID of the page where the widget whose properties you want to get is located.
{widget_key} is the ID of the widget whose properties you want to get.

Sample request

GET http://mysite.com/api/default/pages(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.GetPropertyValues(componentId=6fde353b-e1bd-4c77-99f3-23dc7316dd25)

Sample response

Status code: 200 OK

JSON

{
   "@odata.context":"http://mysite.com/sf/system/$metadata#Telerik.Sitefinity.Web.Services.Contracts.Operations.Pages.PropertyEditor.Adaptors.Model.PropertyValueGroupContainer",
   "ComponentId":"6fde353b-e1bd-4c77-99f3-23dc7316dd25",
   "Caption":null,
   "PropertyLocalizationMode":"Default",
   "Properties":[
      {
         "Name":"Content",
         "Value":"Hello world"
      }
   ],
   "PropertyMetadata":[
   ]
}

This request requests a Content block widget and returns its content - Hello world.

This procedure creates a Section widget and places it on a page. You can then place other widgets inside this widget.

To create a Section widget, execute a POST request to the following endpoint:

{baseurl}/api/default/pages({page_id})/Default.AddWidget()

Where {page_id} is the ID of the page where you want to add the widget.

In the request body, you must send the type of the widget and specify that it should be placed on root level.

Sample request

POST http://mysite.com/api/default/pages/(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.AddWidget()

Request body (ASP.NET Core widget)

JSON

{
   "widget":{
      "Id":null,
      "Name":"Section",
      "PlaceholderName":"Body",
      "ParentPlaceholderKey":null,
      "SiblingKey":null,
      "Properties":[
      ]
   }
}

This request creates an ASP.NET Core Section widget and adds it on the specified page.

The Name property specifies the type of widget that you are creating.
In this example, you are creating an ASP.NET Core Section widget.

The PlaceholderName property and the ParentPlaceholderKey property specify where to place the widget on the page. For example, in column one of a particular Section widget.
In this request, the properties are set to body and null, because the Section widget that you are creating will be attached to the body of the page.

Sample response

Status code: 201 Created

JSON

{
   "@odata.context":"http://mysite.com/sf/system/$metadata#Telerik.Sitefinity.Renderer.Editor.WidgetState",
   "Key":"21c95d56-74ad-44ec-82a4-7af800f9ed28",
   "Name":"Section",
   "DeleteAllowed":true,
   "EditAllowed":true,
   "MoveAllowed":true,
   "LabelTooltip":"",
   "IsPersonalized":false,
   "WidgetSegmentId":null
}

The response of this request contains the Key of the Section widget, which you can then use in subsequent requests to add a widget inside this Section widget.

This procedure creates an ASP.NET Core Content block widget and places it inside an ASP.NET Core Section widget.

To create a widget inside another widget, execute a POST request to the following endpoint:

{baseurl}/api/default/pages({page_id})/Default.AddWidget()

Where {page_id} is the ID of the page where you want to add the widget.

In the request body, you must send the type of the widget and where on the page it should be placed.

Sample request

POST http://mysite.com/api/default/pages/(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.AddWidget()

Request body (ASP.NET Core widget)

JSON

{
   "widget":{
      "Id":null,
      "Name":"ContentBlock",
      "PlaceholderName":"Column1",
      "ParentPlaceholderKey":"21c95d56-74ad-44ec-82a4-7af800f9ed28",
      "SiblingKey":null,
      "Properties":[{
          "Name": "Content",
          "Value": "Hello world"
      }]
   }
}

The Name property specifies the type of widget that you are creating.
In this example, you are creating a Content block widget.
The ParentPlaceholderKey property specifies the Key of the widget where the current widget should be placed.
In this example, the widget should be placed inside the Section widget with Key 21c95d56-74ad-44ec-82a4-7af800f9ed28.
The PlaceholderName specifies the container of the widget where the current widget should be placed.
In this example, the widget should be placed inside column 1 of the Section widget.
The Properties collection contains pairs of names and values defining the properties of the widget.
In this example, you are providing the Content and its Value only.

Sample response

Status code: 201 Created

JSON

{
   "@odata.context":"http://localhost/sf/system/$metadata#Telerik.Sitefinity.Renderer.Editor.WidgetState",
   "Key":"0a1ecd64-33d6-41e7-801d-98bde3e1d3ca",
   "Name":"ContentBlock",
   "DeleteAllowed":true,
   "EditAllowed":true,
   "MoveAllowed":true,
   "LabelTooltip":"",
   "IsPersonalized":false,
   "WidgetSegmentId":null
}

To update the content or the properties of a widget, execute a POST request to the following endpoint:

{baseurl}/api/default/pages({page_id})/Default.SetProperties

Where {page_id} is the ID of the page where the widget whose properties you want to update is located.

In the request body, you must specify which widget you want to update and which properties of that widget you want to edit.

Sample request

POST http://mysite.com/api/default/pages(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.SetProperties

Request body (ASP.NET Core widget)

JSON

{
   "propertyValueGroup": {
      "ComponentId": "c9cd38c3-3a8c-44e4-a9dd-ed3d81579724",
      "Properties": [
         {
            "Name": "Content",
            "Value": "Hello world edited"
         }
      ]
   }
}

Sample response

Status code: 204 No Content

No response body

You can move a widget on a different place on the page – for example, in a different Section widget or in a different column of a Section widget.

To do this, execute a POST request to the following endpoint:

{baseurl}/api/default/pages({page_id})/Default.MoveWidget

Where {page_id} is the ID of the page where the widget that you want to move is located.

In the request body, you must specify which widget you want to move and where you want to move it.

Sample request

POST http://mysite.com/api/default/pages(917ef635-3099-4a8e-bbd0-298191a4b547)/ Default.MoveWidget

Request body (ASP.NET Core widget)

JSON

{
   "widget":{
      "Id":"{widget id}",
      "PlaceholderName":"Column1",
      "ParentPlaceholderKey":"{parent section id}",
      "SiblingKey":null
   }
}

Sample response

Status code: 204 No Content

No response body

To remove a widget from a page, execute a POST request to the following endpoint:

{baseurl}/api/default/pages({page_id})/Default.ExecuteWidgetOperation

Where {page_id} is the ID of the page where the widget that you want to delete is located.

In the request body, you must specify which widget you want to remove from the page and the type of operation that you want to perform – in this example, delete.

Sample request

POST http://mysite.com/api/default/pages(917ef635-3099-4a8e-bbd0-298191a4b547)/Default.ExecuteWidgetOperation

Request body (ASP.NET Core widget)

JSON

{
   "operation":{
      "WidgetKey":"0a1ecd64-33d6-41e7-801d-98bde3e1d3ca",
      "Name":"delete"
   }
}

Sample response

Status code: 200 OK

JSON

{
   "@odata.context":"http://mysite.com/sf/system/$metadata#Telerik.Sitefinity.Renderer.Editor.WidgetOperationResult",
   "Link":null,
   "Success":true,
   "Title":null,
   "AvailableActions":[

   ],
   "Message":null,
   "MultipleItemsMessage":null,
   "SucceededItemsIds":[

   ],
   "FailedItemsIds":[

   ],
   "Type":"None",
   "State":{
      "Key":null,
      "Name":null,
      "DeleteAllowed":false,
      "EditAllowed":false,
      "MoveAllowed":false,
      "LabelTooltip":null,
      "IsPersonalized":false,
      "WidgetSegmentId":null
   },
   "Properties":[

   ],
   "UndoOperation":null
}

Want to learn more?

Enhance your Sitefinity skills by enrolling in free training sessions. Become Sitefinity certified through Progress Education Community to strengthen your professional credentials.

Get started with Integration Hub | Sitefinity Cloud

This free lesson teaches administrators, marketers, and other business professionals how to use Sitefinity Integration Hub to create automated workflows between Sitefinity and other business systems.

Web Security for Sitefinity Administrators

This free lesson teaches administrators the basics about protecting your Sitefinity instance and your sites from external threats. Configure HTTPS, SSL, allow lists for trusted sites, and cookie security, among others.

Foundations of Sitefinity ASP.NET Core Development

The free on-demand video course teaches developers how to use Sitefinity ASP.NET Core and take advantage of its decoupled architecture and modern development model.

Widget operations

Overview

Get the properties of a widget

Create a widget on top level

Create a widget inside another widget

Update the properties of a widget

Move a widget

Remove a widget from a page