Extensions

Håkan Edling edited this page Mar 16, 2016 · 2 revisions

In Piranha CMS you use extensions to customize and add data to the different core models. The framework separates extensions in two categories, Regions and Extensions where regions are used when designing Page types and extensions are plugins attached to models.

Creating an extension

An extension is made up of at least two files, one class defining the different properties that should be stored in the database for the extensions and one view that the manager should use when editing the extension.

Creating the extension class

All extensions must implement the IExtensions interface in the Piranha.Extend namespace. For convenience we have included an abstract base class in the same namespace called Extension that you can inherit to get the defult implementations for all of the methods. Extensions are discovered using MEF.

using System; using System.ComponentModel.Composition; using Piranha.Extend;

[Export(typeof(IExtension))]
[ExportMetadata("InternalId", "AuthorExtension")]
[ExportMetadata("Name", "Author information")]
[ExportMetadata("Type", ExtensionType.User)]
[Serializable]
public class AuthorExtension : Extension {
  public string Twitter { get ; set ; }
  public string LinkedIn { get ; set ; }
  public string Biography { get ; set ; }
}

By exporting the meta data above we have specified that the extension will be visible in the manager interface as Author information and that it should be attached to the user model.

Creating the view

In order for this extension to show up in the manager interface we also need to create a partial .cshtml view for it that will be inserted into the edit view for the user. All extensions should be placed in the folder:

~/Areas/Manager/Views/Extensions/

in your web site. The name of the view must be identical to the name of your extension class in order for the manager interface to locate it. This would mean that the correct placement for the view for our AuthorExtension would be:

~/Areas/Manager/Views/Extensions/AuthorExtension.cshtml

Now let's take a look at how the view for the author extension could be implemented:

@model AuthorExtension
<ul class="form">
  <li>
    @Html.LabelFor(m => m.Twitter)
    <div class="input">@Html.TextBoxFor(m => m.Twitter)</div></li>
  <li>
    @Html.LabelFor(m => m.LinkedIn)
    <div class="input">@Html.TextBoxFor(m => m.LinkedIn)</div></li>
  <li>
    @Html.LabelFor(m => m.Biography)
    <div class="input">@Html.TextAreaFor(m => m.Biography)</div></li>
</ul>

As you can see, apart from following the html markup of the manager interface, this is just standard MVC notation for building a form. This of course means that you can include any validation attributes for your extension as it will be validated with the standard model validation.

Attaching extensions to multiple models

The ExtensionType works as a bitmask which means that you can attach an extension to several entities. For example, to attach the author extension to both users and media objects you would use the following syntax in the attribute:

[Export(typeof(IExtension))]
[ExportMetadata("InternalId", "AuthorExtension")]
[ExportMetadata("Name", "Author information")]
[ExportMetadata("Type", ExtensionType.User|ExtensionType.Media)]
[Serializable]
public class AuthorExtension : IExtension {
  ...
}

Events

The IExtension interface contains a number of events that have an empty virtual implementation in the Extension base class. You can use these methods to manipulate the content of your extensions or perhaps initialize resources that's needed either for the manager interface or by the application.

Ensure

The ensure method is called once for every extension in the app domain on application start. This method can be used to install meta data, create additional tables or other initializations that the extension need. The method takes an authenticated data context as input.

void Ensure(Piranha.DataContext db)

Init

This method is called when the extension is loaded by the client API and can be used to initialize it depending on the other data available in the model it is attached to.

void Init(object model)

InitManager

This method is called when the extension is loaded in the edit view for the manager interface and should be used for initializing meta data that is only needed when editing the extension in the manager interface. The method takes the edit model of the entity it is attached to as an argument.

void InitManager(object model)

OnManagerSave

This method is called when the entity that the extension is attached to is saved from the manager interface. It can be used to pre process the data of the extension or perhaps store information in another table.

void OnManagerSave(object model)

OnManagerDelete

Just like OnManagerSaved this method is called from the manager interface. It can be used to clean up resources or data in other tables related to the extension before it is deleted.

void OnManagerDelete(object model)

GetContent

This method can be used to manipulate the content before it is sent out to the client API. In our AuthorExtension we would probably not override this method, but in other cases you want the content to be something completely different than the actual data that you store in the database.

object GetContent(object model)
You can’t perform that action at this time.
You signed in with another tab or window. Reload to refresh your session. You signed out in another tab or window. Reload to refresh your session.
Press h to open a hovercard with more details.