Using The Installation System

mojoPortal CMS provides a system for perfoming tasks needed to install, upgrade and configure features. It is used to install and upgrade mojoPortal features and you can leverage it for doing the same with your own features. Its basically a matter of copying files to the correct location and the mojoPortal installation system will do the rest. If you structure your folders correctly beneath your own Web.UI project, you can package your feature in a way such that you just copy from the root/Setup/aspplications/[yourfeaturename] of your Web UI project for your custom feature to the root/Setup folder of the mojoPortal Web UI project, aka in the source code this is te "Web" folder, if using pre-compiled deployment files it corresponds to the wwwroot folder (though you do not want to copy the Web.config file as this would overwrite the mojoPortal one. See Setting Up Your Projects for more info on setting up your Web.UI project. During development, you can copy these files using a post build event. For packaging your feature for xcopy deployment, you can use UnleashIt to copy just the needed files without C# source code to a folder, then remove the Web.config as it is not needed in the package and will cause problems if you leave it there because it will overwrite the mojoPortal Web.config.

The basic folder structure of your WebUI project should be something like this:

yourfeature.Web.UI (root folder of your web application project) (use post buildevents to copy your files up to the mojooportal project)
yourfeature.Web.UI/App_GlobalResources (.resx files for localizing your labels and buttons go here)
yourfeature.Web.UI/yourfeaturename/ (your pages and controls go in here)
yourfeature.Web.UI/Data/HelpFiles (you can put your help files here)
yourfeature.Web.UI/Setup/applications/yourapplicationname/FeatureDefinitions (put config files here for configuring your feature and any module settings)
yourfeature.Web.UI/Setup/applications/yourapplicationname/SchemaInstallScripts/mssql (your first db script goes here, if supporting more dbs you will have /mysql, /sqlite etc)
yourfeature.Web.UI/Setup/applications/yourapplicationname/SchemaUpgradeScripts/mssql (all subsequent scripts go here)
yourfeature.Web.UI/Setup/indexbuilderconfig/ if you implement searchable features you will put a config file here to configure your indexbuilderprovider

Note that whatever you choose for yourapplicationname should be unique enough to avoid conflicts with other things. One idea is to use some kind of prefix like I might name mine sts-myapplication and it likely will never clash even if someone else has a myapplication.

Your first version will only have the first sql script and it should be named 0.0.0.1.config and placed in the folder:
Web.UI/Setup/applications/yourapplicationname/SchemaInstallScripts/mssql

As you continue to develop your feature and need to run addtiional scripts put them in the folder:
Web.UI/Setup/applications/yourapplicationname/SchemaUpgradeScripts/mssql
and name them sequentially according to version, so the first upgrade script will be 0.0.0.2.config using only 1 digit for each segment so after 0.0.0.9.config comes 0.0.1.0.config not 0.0.0.10.config

Visitng the /Setup/Default.aspx page in your mojoportal web will run the scripts

You application may contain multiple features, in mojoportal terminology, each feature has one part called a module control that plugs into the content pages in mojoportal. From there it may link to feature specific pages or if its a simple feature the module control may be all there is. The important thing is this is the part that plugs into the mojoportal content managment system and will appear in the feature list as something that can be placed on a page. The module control is basically .ascx UserControl, but it must inherit from mojoPortal.Web.SiteModuleControl (which itself inherits from UserControl). So part of installing your feature is letting mojoportal know it exists. You could install it manually using the UI from Administration Menu > Feature Modules > Add New Feature, but its much better to do it with configuration files and let the setup system install it for you. You can place these configuration files in:
Web.UI/Setup/applications/yourapplicationname/FeatureDefinitions

So for example, I'm currently developing a more advanced Event Calendar to sell so I might name my config file 4000_STS_EventCalendar.config
The file must end with .config but the name itself is not very important. If there is more than one they will be installed in file system sort order so you might use numbers as the first part of the name to control how they sort. Example syntax of the file is like this:

<?xml version="1.0" encoding="utf-8" ?>
<featureDefinitions>
    <featureDefinition
    featureGuid="284357cd-3542-4544-9682-43143193c3b9"
    supportedDatabases="MSSQL,MySQL,pgsql,SQLite,FirebirdSql"
    resourceFile="CustomModule"
    featureNameReasourceKey="CustomModule"
    controlSource="Modules/CustomModule.ascx"
    sortOrder="500"
    defaultCacheTime="360"
    excludeFromFeatureList="false"
    icon="blank.gif"
    >
        <featureSetting
            resourceFile="CustomModule"
            resourceKey="CustomModuleSettingInt"
            defaultValue="false"
            controlType="TextBox"
            controlSrc=""
            helpKey=""
            sortOrder="100"
            regexValidationExpression="^[0-9][0-9]{0,4}$"
        />
        <featureSetting
            resourceFile="CustomModule"
            resourceKey="CustomModuleSettingBool"
            defaultValue="false"
            controlType="CheckBox"
            controlSrc=""
            helpKey=""
            sortOrder="110"
            regexValidationExpression=""
        />
        <featureSetting
            resourceFile="CustomModule"
            resourceKey="CustomModuleSettingString"
            defaultValue="false"
            controlType="TextBox"
            controlSrc=""
            helpKey=""
            sortOrder="120"
            regexValidationExpression=""
        />
        <featureSetting
            resourceFile="CustomModule"
            resourceKey="CustomModuleSettingCssClass"
            defaultValue="false"
            controlType="TextBox"
            controlSrc=""
            helpKey=""
            sortOrder="130"
            regexValidationExpression="^(\s*[a-zA-Z]+[_\-a-zA-Z0-9]+)*\z"
        />        
    </featureDefinition>
</featureDefinitions>

This file is fairly self explantory, but a few important notes.

Make sure and use a new Guid for your featureGuid. You can generate one in code using Guid.NewGuid.ToString() or in SQL using SELECT newid().

FeatureSettings aka module settings are settings you can define for your features. They are editable by clicking the gear icon next to the title of a feature instance. You can define TextBox, CheckBox or ISettingControl. If you use ISettingControl, you must enter the path to a UserControl (.ascx file) in the controlSrc and inside that UserControl you must declare and implement ISettingControl interface. See Web/Controls/GMapTypeSetting.ascx for an example.

Once the config files are in place, visiting /Setup/Default.aspx will install and configure it.

Valid Options for the controlType Property

The controlType property can be set to:

TextBox
CheckBox
DropDownList
ISettingControl
CustomField (similar to ISettingControl but has more functionality)

Control Type Features

TextBox and CheckBox do not have any additional functionality.

DropDownList will show an HTML select element. To populate the options for this element, the options must be added to the featureSetting.

</featureSetting>

Control Attributes

With mojoPortal 2.6.0.2 or higher, attributes can be added to the rendered controls. This allows developers to add any attribute to the rendered html control they would like to add. One could even get a little creative and add extra controls like links or divs. Adding the attributes is very simple as shown below.

which renders as

<div class="settingrow blip">
<label class="settinglabel blop" for="EnterSomething5">Enter Something</label>
<input name="EnterSomething5" id="EnterSomething5" type="text" class="forminput blap" value="" data-foo="bar" placeholder="Put Your Setting Here">
<a title="Help" class="mhelp cblink cboxElement" href="/Help.aspx?helpkey=sflexi-Help-help"><img title="Help" src="/Data/SiteImages/question.png" alt="Help"></a>
</div>

Last Modified by Joe Davis on Dec 03, 2020