Dynamicweb Ribbon Extensibility - Dynamicweb online manual

Developers Guide

Dynamicweb Ribbon Extensibility HOW TO WORK WITH THE STANDARD CONTROLS IN DYNAMICWEB

Version: 1.11 2010.06.30 English

Dynamicweb Ribbon Extensibility, How to work with the standard controls in Dynamicweb

LEGAL INFORMATION © Copyright 2010 Dynamicweb Software A/S (Ltd). All rights reserved. Alteration or reproduction of this document or parts hereof is strictly prohibited, regardless of form or means, unless explicit permission has been acquired from Dynamicweb Software. Dynamicweb is a registered trademark of Dynamicweb Software. Company and product names mentioned in this document may be registered trademarks or trademarks of third parties.

© 2010 Dynamicweb Software A/S (Ltd).

3


CONTENTS Legal information ________________________________ iii Contents ________________________________________ iv Introduction ______________________________________v What this document is about .............................................................. v Who this document is for .................................................................... v Related documents ............................................................................. v

1

Getting started ________________________________6

2

The anatomy of an add-in _______________________7 2.1 2.2 2.3 2.4 2.5 2.6

3

Pop-up windows ______________________________12 3.1 3.2 3.3

4

The concept ........................................................................... 12 Creating new pop-up window ................................................ 12 Client-side support................................................................. 13

Data access __________________________________16 4.1 4.2 4.3

5

Targeting your add-in .............................................................. 8 The lifecycle of an add-in......................................................... 8 Creating the UI ........................................................................ 9 Rendering additional markup................................................. 10 Embedding custom resources ............................................... 10 Resolving multiple Ribbon instances ..................................... 11

Providing the data ................................................................. 16 Retrieving the data ................................................................ 16 Events handling ..................................................................... 17

Other features ________________________________18 5.1 5.2

Disabling add-ins ................................................................... 18 Displaying trace information .................................................. 18


4


INTRODUCTION What this document is about This document describes the new functionality which allows third-party developers to inject their controls and logic into the Dynamicweb RibbonBar control.

Who this document is for This document is for developers that want to extend the backend of Dynamicweb with the custom functionality.

Related documents •

Dynamicweb Controls: Gives an overview of standard controls that ship with Dynamicweb CMS (see http://engage.dynamicweb-cms.com/Controlsdocumentation-416.aspx).


5


1

GETTING STARTED The new release of Dynamicweb comes with the extensibility API for the RibbonBar control. This API allows you to extend the functionality of the RibbonBar by writing addins. If you already familiar with the Extensibility API you will find that writing an add-in is almost the same as writing a custom module or a notification subscriber. An add-in represents a standalone .NET assembly file (*.dll) which is placed into the /bin folder of your Dynamicweb CMS installation.


6


2

THE ANATOMY OF AN ADD-IN From the technical perspective an add-in is a class which derives from the Dynamicweb.Controls.Extensibility.RibbonBarAddIn class. This class helps the application to identify all Ribbon add-ins during the run-time. Also it exposes properties and methods that help your add-in to interact with the execution environment. An example of an add-in is shown below:

Figure 1. An example of an add-in.

The first thing you have probably already noted is the meta-information applied to an addin. Here is the description of all attributes recognized by the system: • AddInName Specifies the unique name of your add-in. • AddInDescription Specifies the brief description of what your add-in does. • AddInTarget Specifies the path to page(s) where your add-in should appear. This attribute will be described more detailed in the next section.


7


2.1

Targeting your add-in When you write your add-in you probably do not want it to appear on all pages that contain the RibbonBar control. To specify the page(s) where your add-in should be rendered use the AddInTarget attribute. The attribute takes one argument – the virtual path to the page with the RibbonBar control on it. For standard Dynamicweb backend pages we strongly recommend you to use constant values from the Dynamicweb.Controls.Extensibility.RibbonBarTarget class. This class provides a list of all pages where the RibbonBar control is used. There are several ways you can specify the place for your add-in. • Specifying a single target Apply the AddInTarget attribute only once to specify a single page. • Specifying multiple targets Apply the AddInTarget attribute multiple times to specify two or more pages where you want your add-in to appear. • Using regular expression You can specify the regular expression pattern as an argument of the AddInTarget attribute. In this case all pages that match the given pattern will contain your addin.

2.2

The lifecycle of an add-in The lifecycle of the Ribbon add-in is illustrated in the following:

Figure 2. Add-in lifecycle.

There are three stages (except of the object creation) that your add-in passes before the page content is sent to the client. Here they are:


8


• Initialization Occurs during the page Init stage. The corresponding method which you can override from your add-in – Initialize. • Loading Occurs during the page Load stage. The corresponding method which you must override from your add-in – Load. • Rendering Occurs during the page Render stage. The corresponding method which you can override from your add-in – Render. Please note that the Load method must be implemented. All the UI should be created within this method.

2.3

Creating the UI It is a typical case that your add-in will expose some UI to the user (this can be a single button, a group of controls or a whole tab). Creating the UI is pretty simple. You just need to add the desired controls to the RibbonBar control containing your add-in. Here is an example of creating a single button:

Figure 3. Creating a single button.

Note that in the previous example we have placed a button into the default group. (The group is called “General” and resides in the “Add-ins” tab) using the CreateDefaultContainer method to get a reference to this group. If you want your add-in to render some complex UI you can use the methods exposed by the RibbonBar control to do it. For example the following code snippet adds a tab called “History” with a single group on it containing two controls – a button and a check-box.


9


Figure 4. Creating a complex UI. Note that if the tab with the name “History” already exists then the reference to the existing tab will be retrieved and no exception will be thrown. The same is applied for groups..

2.4

Rendering additional markup Sometimes you might want your add-in to render some additional markup. In this case you can override the Render method like shown below:

Figure 5. Rendering additional markup.

2.5

Embedding custom resources Sometimes some additional files are required for your add-in to function properly. If you want to embed your custom resource files into the page you can implement the Dynamicweb.Controls.IResourceLoader interface (this interface is used by most of the Dynamicweb controls for resource embedding). The interface exposed one method called LoadResources. Register your custom resources using the special class Dynamicweb.Controls.ControlResources. The example implementation of the method is shown below:


10


Figure 6. Embedding custom resources into the page.

2.6

Resolving multiple Ribbon instances It is a rare case but it can happen that several RibbonBar control instances are placed on the same page. In this case you probably want to be able to “choose” where your add-in will appear. This is done my overriding the CanInstantiate property. The example of doing this is shown below:

Figure 7. Resolving an ID of the RibbonBar control.


11


3

POP-UP WINDOWS The functionality within the RibbonBar control is often organized in such a way that a group of related settings are gathered in a dialog, which appears when the user clicks the button. This makes it easier for the user to navigate among the large amount of settings. Also sometimes it’s not possible to fit the desired controls inside the Ribbon. So it’s a good practice to use the dialogs. As we mentioned earlier your add-in can render some complex UI. It can also require some fields to be filled out by the user. Placing these fields inside the Ribbon could result in a bad usability. Also rendering the dialog and all its content manually by overriding the Render method could be pretty hard task. Here pop-up windows come to the rescue.

3.1

The concept Every add-in could contain one or more pop-up windows. The pop-up window (Dynamicweb.Controls.PopUpWindow class) is based on the Dynamicweb.Controls.Dialog control. Each pop-up window has a content URL which specifies the page that should be displayed within the pop-up window (the page is displayed using the tag). Placing the content of the pop-up window inside the iframe solves the identity problems. Also the content is only loaded when the pop-up window is displayed so no overload is occurred when the parent page is being requested (additionally you can set the AutoReload property to “true”. This will reload the pop-up window every time it is displayed and not only once).

3.2

Creating new pop-up window The following code snippet shows how to register a new pop-up window:

Figure 8. Creating a pop-up window.

After the pop-up window has been created we need to be able to display it somehow. Let’s say that we want it to appear when the user clicks the button. The code which implements this idea is shown below:


12


Figure 9. Displaying a pop-up window

Now when the user clicks the button the pop-up window will be displayed and the content of the inner page will be loaded:

Figure 10. Pop-up window in action.

Please note that by default the content of the help topic (the message which is displayed when you click “Help” button) is based on the information taken from the attributes of your add-in class. You can change this behavior by overriding the FormatWindowHelpTopic method of your add-in class.

3.3

Client-side support The pop-up window is designed in such a way that you have a full control over it from the Javascript. The following is the list of client-side events exposed by PopUpWindow class: © 2010 Dynamicweb Software A/S (Ltd).

13


• load Occurs when the pop-up window finishes loading. • ok Occurs when the user hits the “OK” button. • cancel Occurs when the user hits the “Cancel” button. • help Occurs when the user hits the “Help” button. • show Occurs when the pop-up window becomes visible. • hide Occurs when the pop-up window becomes invisible. Here is an example of subscribing to pop-up window events from Javascript:

Figure 11. Interacting with the pop-up window from Javascript.

You can subscribe to client-side events from your add-in code file as well:

Figure 12. Subscribing to a client-side events from the server-side code.

In the previous example the “windowShown” is the name of an event handler. So you will have a JavaScript block similar to the one shown below:

Figure 12. Event handler. © 2010 Dynamicweb Software A/S (Ltd).

14


As you can see almost each event can be canceled (meaning that you will provide your own logic in the event handler and do not want the standard behavior to be triggered). You can get access to the client-side object instance of the pop-up window from the content page by calling the current method (you need to pass an instance of DOM window representing a content page as an argument). The following code illustrates how this can be achieved:

Figure 13. Interacting with pop-up window from the content page.


15


4

DATA ACCESS It is often needed to have access to the data object(s) that are being maintained by the RibbonBar control. For example on the “Page edit” screen you probably would like to get access to the instance of the page which is currently being edited. The following picture illustrates how the data object is represented on a page that contains RibbonBar control:

Figure 14. Data context.

4.1

Providing the data If you are developing the page which contains the RibbonBar control and you want addins to be able to access the data object which is being maintained by the Ribbon then you need to expose this data object through the data context. This is done with the single line of code you need to place into the code-behind:

Figure 15. Initializing data context on the host page.

4.2

Retrieving the data Data retrieval process is very simple. You just need to call the property DataSource which is exposed by the DataContext property of the RibbonBar control. The following example illustrates how to set the title of the pop-up window using the provided data source (add-in is placed on the “Page edit” screen, so the data source type will be Dynamicweb.Content.Page):


16


Figure 15. Using the provided data object.

4.3

Events handling It is also possible for your add-in to handle situations when the data object has been saved or deleted. This is done by subscribing to the Save or Delete events of the data context. Please note that this functionality is only available for data objects that derive from the Dynamicweb.Modules.Common.DbObject class. Otherwise you need to write your own data context which will raise these events when it is needed. The following example shows how to handle Save event:

Figure 16. Handling data saving.


17


5

OTHER FEATURES This section describes some useful features that can make add-in development even easier. The first sub-section describes how to disable add-in support for a particular instance/page. The next sub-section describes how to enable tracing in order to see what is happening with your add-in when it is not possible to debug it (for example if an add-in is placed into the production environment).

5.1

Disabling add-ins To disable add-ins support for a particular RibbonBar control instance set the DisableAddIns property to “true”. If you want to disable add-in support on the whole page you can pass the query-string parameter called Ribbon.DisableAddIns which should be set to “true”. For example requesting the page the following way will result in no add-ins being rendered on this page: /Admin/Content/PageEdit.aspx?Ribbon.DisableAddIns=true This technique can be used to temporarily disable add-ins on the particular page and can help to isolate problems.

5.2

Displaying trace information There is one more feature that can help you to debug your add-ins. You can write debug information into the Trace object and see it in the HTML comments when the page is rendered. To include the trace information set the ShowTrace property of the RibbonBar control to “true”. Alternatively you can provide the query-string parameter called Ribbon.ShowTrace which should be set to “true” (this will output the trace information for all RibbonBar controls placed on the page). An example of using the Trace object is shown below:

Figure 17. Writing a message to the trace.

After enabling the trace output you will see the following lines in your page markup:

Figure 18. Trace output.

Including the trace information might also help to isolate problems with your add-in.


18