Walkthrough: Using the ActionControl component

Abstract

You use the ActionControl component to crate a button that shows a list of clickable items when clicked.

You use the ActionControl component to create a panel with action links. This gives users quick access to a set of actions that are useful, in the context they are in.

This walkthrough describes how to:

Use an ActionControl

To use an ActionControl component on a SPEAK page:

  • Add an ActionControl component to the page. Usually you add the control to a container that you can set horizontal alignment for, because the ActionControl works best when it is right-aligned.

  • Some components provide placeholders for the ActionControl: the ApplicationHeader page substructure has the Actions placeholder and the AdvancedExpander control has the ActionBar placeholder. When you use these placeholders, SPEAK styles and positions the ActionControl component according to the SPEAK visual guidelines.

  1. Create a folder for configuration items as a child of the PageSettings item.

  2. Bind the DataSource property of the ActionControl component to the ActionControl item you created in the configuration items folder under PageSettings.

  3. Add an ActionControl item to this folder. This item is the start of the structure that forms the menu. You do not need to set any values in this item.

  4. Add ActionColumn items as children of the ActionControl item. Add one ActionColumn item for each column you want in the menu. You do not need to set any values in this item.

  5. Add an ActionGroup item as a child of an ActionColumn item for each group heading you need. Specify the heading text in the Text field of the item.

  6. Add Action items as child items of the ActionGroups. Add one Action item for each action you want to add to the menu. Each item shows a menu item that users can click. Set the name that it shows in the Title field and the action in the Click field.

  • You can specify the action in the same way that you specify interactions in other components.

Enable and disable actions

The ActionControl component enables all actions it contains by default. You can disable and enable individual actions in several different ways:

  • To disable an action, select the Disable check box of the Action item, and to enable it, clear the check box.

  • You can use the actions array that the ActionControl component provides in JavaScript. For example:

    this.ActionControl1.viewModel.actions()[0].disable()to disable the first action in the array. Use the enable function to enable actions.

  • You can use the getAction method of the View model. For example:

    this. ActionControl1.viewModel.getAction(‘[data-sc-actionId=\”Sitecore ID of Action item\”]\’).disable() to disable the action where the Action item has the Sitecore ID that you specify. Use the enable function instead to enable it.

Use the Data property

You can specify data in the Data property of an ActionControl, and you can access this data from, for example, the Click event of an Action item in the ActionControl.

The following example shows how you can use the Data property. The example data binds an ActionControl component to a ListControl. The ActionControl has an Action item called Show Item. The ActionControl component is initially disabled, and SPEAK enables the ActionControl when the user selects an item in the ListControl. When the user clicks the Show Item action, SPEAK shows an alert that contains the name of the selected item (the value of $displayName).

To implement this functionality:

  • Set the Data property of the ActionControl to something similar to this: {Binding ListControl1.SelectedItem}. This means that the Data property of the ActionControl always contains a pointer to the currently selected item of the ListControl – if any.

  • Set the IsEnabled property of the ActionControl to something similar to this: {Binding ListControl1.HasSelectedItem}. This means that SPEAK only enables the ActionControl (and the Actions it contains) when the ListControl has a selected item.

  • Set the Click property of the Show Item action to this: javascript:this.viewModel.app.showItem(this.get("data")). This means that SPEAK will call a method called showItem in the PageCode script file when users click the Show Item action, and pass the content of the Data property as an argument. The content of this property is the currently selected item.

  • Define the showItem function like this in the PageCode script file:

    showItem: function(item)
    {
      alert(item.get("$displayName"));
    }