Widget operations

Overview

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

  1. 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.
  2. 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.
  3. 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.
  4. 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.

Get the properties of a widget

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

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

Create a widget on top level

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()

This request creates a .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 a .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

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.

Create a widget inside another widget

This procedure creates a .NET Core Content block widget and places it inside a .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()

  • 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 places.
    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

Update the properties of a widget

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

Sample response

No response body.

Move a widget

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

Sample response

No response body

Remove a widget from a page

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

Sample response

Increase your Sitefinity skills by signing up for our free trainings. Get Sitefinity-certified at Progress Education Community to boost your credentials.

Get started with Integration Hub | Sitefinity Cloud | Sitefinity SaaS

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

Web Security for Sitefinity Administrators

This free lesson teaches administrators the basics about protecting yor Sitefinity instance and its 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 .NET Core and leverage its decoupled architecture and new way of coding against the platform.

Was this article helpful?

Next article

Templates operations