contentXXL Customization: How It Works (Mailform)

contentXXL: Customization – How does it work (Mailform )

Current Situation • contentXXL brings a lot of „out-of-the-box“ modules, so in typical web projects often there is no programming required • partners can write there own modules, if completely different functionallity is required (needs some training & experience) • existing modules can be „shadowed“ completely, but often only some features only should be modified and/or added • existing modules have a limited set of customization settings and customization points e.g. - script in templates- shadow of basic data • BUT • there is often no way to change the general behavior of modules by programming • This has been changed with the introduction of customization points, events and activities (starting with mail form module). contentXXL BUILD 2593 or higher required.

Idea: Customization Plugin Concept • each module type can have several predefined „customization points“ • On this customization points special methods are called inside the „original“ business logic, to provide the posibility to1. add additional logic on defined customization events(e.g. „beforerender“ or „aftersave“)2. to replace existing logic for defined customization activities(e.g. „send mail“ by „write to database“) • customization point methods will get the necessary objects as ByRef parameters (so that objects can be modified) • customization methods are implemented in customization plugin classes (so that no additional compilation of whole project is required) • each customizable module type publishes a plugin base class with overridable customization point methods, that can contain custom business logic • To publish your own customization plugin: • implement a .ascx file (inherits from the moduletype customization baseclass) • put the customization plugin(s) in the shadow-folder of your portal(path shadow/contentxxl/*moduletype*/plugin/customization/) • the filenames of the controls are the customization plugin names which are displayed in the plugin selection dropdown.

Idea: Customization Plugin Concept • configurable plugins • implement a plugin configuration settings control(inherited from ContentXXL.Admin.Common.CustomSettings – works just like the normal customsettings plugin) • put it in the customization settings folder(shadow/contentxxl/*moduletype*/plugin/customization/settings) • all configuration settings from the configuration part are stored in the modulesettings table (best practise: use a prefix for your settings-keys) • access to the plugin configuration settings viaCustomSettings hashtable

Prototype Implementation – The Mailform Module – Customization Activities • Baseclass: ContentXXL.Modules.Mailform.mailformcustomization • Public Overridable Sub DataBind(ByVal mi As ContentXXL.Admin.ModuleInfo, ByRef mailformrepeater As System.Web.UI.WebControls.Repeater) • called for binding „dummy data“ to the Repeater-Form-Controldefault behavior: mailformrepeater.DataBind() • Public Overridable Function ValidateInput(ByVal mi As ContentXXL.Admin.ModuleInfo, ByRef mandatoryfieldsfilledout As Boolean, ByRef formdata As DataTable) As Boolean • called for validating the input data (formdata)default behavior: return mandatoryfieldsfilledout • Public Overridable Sub SendMail(ByVal mi As ContentXXL.Admin.ModuleInfo, ByVal mail As MailMessage) • called for sending the mail objectdefault behavior: sending the mail object with smtpmail • Public Overridable Sub ShowResult(ByVal mi As ContentXXL.Admin.ModuleInfo, ByRef ThankYouMessage As String, ByRef mailformrepeater As System.Web.UI.WebControls.Repeater) • called for showing the result after the mail has been successfully sentdefault behavior: showing the content of the configured HTML-“thankyou“ module

Prototype Implementation – The Mailform Module – Customization Events • Baseclass: ContentXXL.Modules.Mailform.mailformcustomization • Public Overridable Sub BeforeDataBind(ByVal sender As Object, ByVal mi As ContentXXL.Admin.ModuleInfo, ByRef mydv As DataView, ByRef mailformrepeater As System.Web.UI.WebControls.Repeater) • called before DataBind() is executed for the mailformrepeaterdefault behavior: does nothing • Public Overridable Sub AfterDataBind(ByVal sender As Object, ByVal mi As ContentXXL.Admin.ModuleInfo, ByRef mailformrepeater As System.Web.UI.WebControls.Repeater) • called after DataBind() is executed for the mailformrepeaterdefault behavior: does nothing • Public Overridable Sub BeforeMailSend(ByVal sender As Object, ByVal mi As ContentXXL.Admin.ModuleInfo, ByRef formdata As DataTable, ByRef mail As MailMessage) • called when the default mail object is already prepared but not sent yetdefault behavior: does nothing • Public Overridable Sub AfterMailSend(ByVal sender As Object, ByVal mi As ContentXXL.Admin.ModuleInfo, ByRef formdata As DataTable, ByRef mail As MailMessage) • called after the default mail object is sent (after calling the sendmail method)default behavior: does nothing

Prototype Implementation – The Mailform Module inside module implementation (mailform.ascx.vb) • Plugin Control Protected WithEvents customizationPlugin As ContentXXL.Modules.Mailform.mailformcustomization • Customization Points Protected Sub Customize_BeforeDataBind(ByVal sender As Object, ByRef prepareddataset As DataView) customizationPlugin.BeforeDataBind(sender, Me.ModuleConfiguration, prepareddataset, mailformrepeater) End Sub Protected Sub Customize_DataBind(ByRef mailformrepeater As System.Web.UI.WebControls.Repeater) customizationPlugin.DataBind(Me.ModuleConfiguration, mailformrepeater) End Sub Protected Sub Customize_AfterDataBind(ByVal sender As Object) customizationPlugin.AfterDataBind(sender, Me.ModuleConfiguration, mailformrepeater) End Sub Protected Function Customize_ValidateInput() Return customizationPlugin.ValidateInput(Me.ModuleConfiguration, allmandatoryfilledout, formdata) End Function Protected Sub Customize_BeforeMailSend(ByVal sender As Object, ByVal formdata As DataTable, ByVal formmail As MailMessage) customizationPlugin.BeforeMailSend(sender, Me.ModuleConfiguration, formdata, formmail) End Sub Protected Sub Customize_AfterMailSend(ByVal sender As Object, ByVal formdata As DataTable, ByVal formmail As MailMessage) customizationPlugin.AfterMailSend(sender, Me.ModuleConfiguration, formdata, formmail) End Sub Protected Sub Customize_SendEmail(ByVal mail As MailMessage) customizationPlugin.SendMail(Me.ModuleConfiguration, mail) End Sub Protected Sub Customize_ShowResult() customizationPlugin.ShowResult(Me.ModuleConfiguration, thankyoumessage, mailformrepeater) End Sub

Prototype Implementation – The Mailform Module loading the plugin (e.g. in Page_Init) If File.Exists(Server.MapPath(Me.ModuleConfiguration.Instance.Customization)) Then Try customizationPlugin = Me.LoadControl(Me.ModuleConfiguration.Instance.Customization) Catch ex As Exception customizationPlugin = New ContentXXL.Modules.Mailform.mailformcustomization() Response.Write("") End Try Else customizationPlugin = New ContentXXL.Modules.Mailform.mailformcustomization() End If inside the logic (for example: sendmail-activities) Customize_BeforeMailSend(Me, formdata, formmail) If ConfigurationSettings.AppSettings("mailServer") <> "" Then SmtpMail.SmtpServer = ConfigurationSettings.AppSettings("mailServer") End If Customize_SendMail(formmail) Customize_AfterMailSend(Me, formdata, formmail)

Mailform Customization Example 1 – send confirmation mail to the webuser • Idea: after the regular mail is sent, the user who filled out the form will get a templated confirmation mail • file ~/portaldata/x/shadow/contentxxl/modules/mailform/plugin/customization/cc_to_webuser.ascx <%@ Control Inherits="ContentXXL.Modules.Mailform.mailformcustomization"%> <%@ Import Namespace="System.Web.Mail" %> <%@ Import Namespace="System.Data" %> <%@ Import Namespace = "ContentXXL.Runtime.Helpers" %> <script runat="server"> Public Overrides Sub AfterMailSend(ByVal sender As Object, ByVal mi As ContentXXL.Admin.ModuleInfo, _ ByRef formdata As DataTable, ByRef mail As MailMessage) mail.To = formdata.Rows(0)("email") If mi.instance.CustomSettings("usermailtemplate") <> String.Empty Then mail.BodyFormat = MailFormat.Html mail.Body = "<html></head><body>" & _ ContentXXL.Runtime.Helpers.RenderHelper.getRenderedRepeater(formdata, _ mi.instance.CustomSettings("usermailtemplate"), _ Context.Items("lang")) & _ "</body></html>" End If SmtpMail.Send(mail) End Sub </script>

Mailform Customization Example 1 – send confirmation mail to the webuser • Settings Control for Plugin configuration (template selection) • file ~/portaldata/x/shadow/contentxxl/modules/mailform/plugin/customization/settings/cc_to_webuser.ascx <%@ Control Inherits="ContentXXL.Admin.Common.CustomSettings" %> <%@ Register TagPrefix= "xxl" TagName="TemplateSelect" Src="~/contentxxl/admin/AdminControls/TemplateSelect.ascx" %> <table class="admin-inner-table"> <tr> <td class="adminlabel" align="right" > Mail Template</td> <td class="admin-settingsvalue"> <xxl:TemplateSelect ID="usermailtemplate" runat="server" UniqueName="mailtoform"></xxl:TemplateSelect> </td> </tr> </table>

Mailform Customization Example 2 – Write Formdata in XML file • Idea: after regular mail is sent the formdata should be stored in an XML file on the server • file ~/portaldata/x/shadow/contentxxl/modules/mailform/plugin/customization/formdata_to_xml.ascx <%@control Inherits="ContentXXL.Modules.Mailform.mailformcustomization"%> <%@ Import Namespace="System.Web.Mail" %> <%@ Import Namespace="System.Data" %> <%@ Import Namespace="System.IO" %> <%@ Import Namespace="ContentXXL.Admin" %> <script runat="server"> Public Overrides Sub AfterMailSend(ByVal sender As Object, ByVal mi As ContentXXL.Admin.ModuleInfo, _ ByRef formdata As DataTable, ByRef mail As MailMessage) Dim outputstring As String = "" outputstring &= "<mailformcontent>" & Environment.NewLine For Each col As DataColumn In formdata.Columns outputstring &= "<" & col.ColumnName & ">" & formdata.Rows(0)(col.ColumnName) outputstring &= "</" & col.ColumnName & ">" & Environment.NewLine Next outputstring &= "</mailformcontent>" & Environment.NewLine Dim oEncoder As Encoding = Encoding.GetEncoding(65001) 'UTF-8 Dim bytes As Byte() Dim fs As FileStream fs = New FileStream(Server.MapPath(mi.instance.customsettings("xmlfilepath")) & _ Date.Now().ToString("yyyyMMddHHmmss") & "_" & formdata.Rows(0)("email") & ".xml", _ FileMode.Create) bytes = oEncoder.GetBytes(outputstring) fs.Write(bytes, 0, bytes.Length) fs.Close() End Sub </script>

Mailform Customization Example 2 – Write Formdata in XML file • file ~/portaldata/x/shadow/contentxxl/modules/mailform/plugin/customization/settings/formdata_to_xml.ascx <%@ Control Inherits="ContentXXL.Admin.Common.CustomSettings" %> <table class="admin-inner-table"> <tr> <td class="adminlabel" align="right" > XML File Path</td> <td class="admin-settingsvalue"> <asp:textbox id="xmlfilepath" runat="server" class="admin-element-width"></asp:textbox> </td> </tr> </table>

Mailform Customization Example 3 – Write Formdata in XML file / don‘t send mail • Idea: the formdata should be stored in an XML file on the server, and the admin can configure if a mail should be sent anyway • file ~/portaldata/x/shadow/contentxxl/modules/mailform/plugin/customization/formdata_to_xml_nomail.ascx <%@control Inherits="ContentXXL.Modules.Mailform.mailformcustomization"%> <%@ Import Namespace="System.Web.Mail" %> <%@ Import Namespace="System.Data" %> <%@ Import Namespace="System.IO" %> <%@ Import Namespace="ContentXXL.Admin" %> <script runat="server"> Public Overrides Sub SendMail(ByVal mi As ContentXXL.Admin.ModuleInfo, ByVal mail As MailMessage) if mi.instance.customsettings("sendmail") = "True" mybase.SendMail(mi, mail) end if End Sub Public Overrides Sub AfterMailSend(ByVal sender As Object, ByVal mi As ContentXXL.Admin.ModuleInfo, _ ByRef formdata As DataTable, ByRef mail As MailMessage) Dim outputstring As String = "" outputstring &= "<mailformcontent>" & Environment.NewLine For Each col As DataColumn In formdata.Columns outputstring &= "<" & col.ColumnName & ">" & formdata.Rows(0)(col.ColumnName) outputstring &= "</" & col.ColumnName & ">" & Environment.NewLine Next outputstring &= "</mailformcontent>" & Environment.NewLine Dim oEncoder As Encoding = Encoding.GetEncoding(65001) 'UTF-8 Dim bytes As Byte() Dim fs As FileStream fs = New FileStream(Server.MapPath(mi.instance.customsettings("xmlfilepath")) & _ Date.Now().ToString("yyyyMMddHHmmss") & "_" & formdata.Rows(0)("email") & ".xml", _ FileMode.Create) bytes = oEncoder.GetBytes(outputstring) fs.Write(bytes, 0, bytes.Length) fs.Close() End Sub </script>

Mailform Customization Example 3 – Write Formdata in XML file / don‘t send mail • file ~/portaldata/x/shadow/contentxxl/modules/mailform/plugin/customization/settings/formdata_to_xml_nomail.ascx <%@ Control Inherits="ContentXXL.Admin.Common.CustomSettings" %> <table class="admin-inner-table"> <tr> <td class="adminlabel" align="right" > XML File Path</td> <td class="admin-settingsvalue"> <asp:textbox id="xmlfilepath" runat="server" class="admin-element-width"></asp:textbox> </td> </tr> <tr> <td class="adminlabel" align="right" > Send Mail</td> <td class="admin-settingsvalue"> <asp:checkbox id= "sendmail" runat="server" ></asp:checkbox> </td> </tr> </table>

contentXXL Customization: How It Works (Mailform)