Difference between revisions of "Developer Tutorials"

Revision as of 13:25, 23 June 2015

Creating a Development Website

This tutorial takes you through the steps required to create a website on your development workstation. You can use websites like these to create and modify functionality before transferring to other environments, like QA, UAT or production.

You should already have your workstation configured with IIS and Contensive. If you wish to use PHP to control the Contensive framework, it should already be installed.

Creating a New Site

1. Start Contensive Application Manager.

Click the start button > all programs > Contensive > Application Manager

2. Click the Local node on the Application Manager.

On the left side of the Contensive Application Manager, you first see the Enterprise node at the top. Under it, you should at least see a grey Local node. Click it to connect to your Local Contensive server. This node represents the Contensive applications running on your local machine. If you already have applications running, a [plus] sign will appear that you can open to see each application.

3. Add an application to the local Contensive Server.

To add a application, right click the Local node and select "Add/Import Site"This will start a wizard that include up to eleven dialog boxes.

4. Select a Site Name.

Select a one word name for your application. It must be unique to this server and it can not contain any spaces or special characters. For this demonstration I will use MySampleSite as the site name.

In most cases when creating a new development site, this is the only screen you will have to change. All the following screens you can leave the default and just hit Continue.

5. Enter the type of Site.

You can hit OK and accept the default in most development site cases.

Enter which type of page you prefer using, php or asp. The site is created entirely within Contensive SMS, but scripting technologies are used create and control the Contensive Framework. In most installations, there is only one scripted host page created for each site. Having a host page written in a familiar technology gives you a very versatile, very rapid environment to handle emergencies.

6. Pick the IP Address.

You can hit OK and accept the default in most development site cases.

Set to 127.0.0.1 for development sites. They are not typically viewed from other machines. If you will need to others to view the site from other machines, pick an IP address on your machine.

7. Pick a Domain name.

You can hit OK and accept the default in most development site cases.

For development sites, the domain can be simply the Site Name from the earlier step. Contensive will configure your computer's host file so on your local machine you can just type the site name and the browser will use the local site. For sites on public machines, enter the primary domain for the site.

8. Enter the HTML documents folder.

You can hit OK and accept the default in most development site cases.

This is the folder where the web server will look for the host page created in an earlier step.

9. Enter the content files folder.

You can hit OK and accept the default in most development site cases.

This is where Contensive will store a majority of your content.

10. Enter an ODBC connection string.

You can hit OK and accept the default in most development site cases.

A blank ODBC connection will cause the wizard to create a new site.

11. Enter the ODBC DSN file folder.

You can hit OK and accept the default in most development site cases.

This is a location to store the ODBC information about the new connection that will be created automatically.

12. Enter the database file folder.

You can hit OK and accept the default in most development site cases.

This is the folder where Contensive will store the new database file created for the site.

13. Enter an SMTP Email server.

You can hit OK and accept the default in most development site cases.

If you have an SMTP email server configured on your machine you can include it here. Contensive SMS has extensive email features. Be aware if you configure the SMTP server that if you add email features to your development site, it may send email to the users you configure.

14. Enter your email address as the Admin Email address. The site will begin building itself. That will take less than 5 minutes.

You can hit OK and accept the default in most development site cases.

You can skip this if you do not plan to enable email on your development workstation.

At this point, you should have a running website on your local IIS server that uses Contensive SMS to create pages.

Accessing Your Site And Updating Your Username and Password

1. Open a browser and go to http://MySampleSite/admin (where MySampleSite is the site name you used in Creating Your Website, step 4).

You should see the Login box.

2. The default username and password are:

username: root

password: contensive

When you log in, be sure to edit the record and change them as you need. This log in account will expire in 7 days.

3. To edit the default user account, open the Navigator on the left to Manage Users >> click on People.

You will see a list of the users configured for the site. If it is a new site, there will be only the root user. To edit the user account, click the edit icon in the left-most column of the row. You are now editing the user account. Click on the Permissions tab and update your username and password. You can also update the name field in the details tab if you wish.

Creating a New Add-On

This tutorial shows you how to create a new Contensive Add-on.

The purpose of an Add-on is to hold all the elements of a site feature (like the code, javascript, css, html, etc.) together in one element that can used on the site. It may be placed on a page, handle an ajax call, run as a process in the background, etc.

You should already have created a new developer site on your workstation.

Steps to create an add-on:

1. On the Admin Navigator on the left, Open Manage Add-ons >> Advanced >> click on Add-ons.

You will see a list of all the Add-ons installed on the site.

2. Click the Add button to create a new Add-on.

You will see a new add-on record. Set the name. I will use "Sample Add-on" and in the HTML Content box, enter "Hello World"

In the Placement tab, check "Place on Pages" and "Admin Navigator"

3. Click OK at the top of the page to save the Add-on and exit the edit page.

4. Execute the new add-on.

On the Admin navigator on the left Open Manage Add-ons >> Advanced >> Add-ons With No Collection >> click on Sample Add-on. You should see the words Hello World in bold on the left pane.

5. Add the add-on to a website page.

Go to the public home of your website and turn on Quick Edit. Place the cursor in the page editor where you want your add-on and select it from the Add-ons drop down. A green icon will appear when you place the add-on in the copy. Click OK to save and close the editor. Your add-on will run here and show "Hello World" where you placed the icon.

Creating a New Add-On Collection

This tutorial shows you how to create a new Add-on Collection. The Collection we will create here will include one add-on. The purpose of an Add-on Collection is to gather all the elements of an application feature into one single location that can be exported and installed on other sites. You should already have created a new add-on.

Steps to create an add-on collection:

1. On the Admin Navigator on the left, open: Manage Add-ons >> Advanced >> click on Add-on Collections.

You will see a list of all the Add-on Collections installed on the site.

2. Click the Add button to create a new Add-on Collection. You will see a new add-on collection record. Set the name. I will use "Sample Collection". Click OK at the top of the page to save the Add-on Collection and exit the edit page.

Steps to add an add-on to the add-on collection:

1. On the Admin navigator on the left, open: Manage Add-ons >> Advanced >> click on Add-ons.

2. Edit the add-on you want to include in the collection. In this case I will edit the add-on I created in the earlier tutorial, names "Sample Add-on"

3. In the field marked "Collection", select the add-on collection you just created. In this case I will select "Sample Collection"

4. Click OK to save and exit the editor.

The add-on is now in the Add-on Collection. You can test this by opening the Admin Navigator on the left: Manage Add-ons >> Sample Collection >> click on Sample Addon

Exporting and Installing an add-on Collection

This tutorial shows you how to export a Collection to a collection file, then install that collection to a different site. You should already have created a new developer site on your workstation and created an add-on collection.

Steps to export an add-on collection:

1. Install the Collection Exporter Tool.

Go to the admin site and open the navigator Tools, open the Add-on Manager, check the install checkbox next to the Collection Exporter. Click OK to install the tool. When it installs, you can find it under Tools in the Navigator.

2. Open the Collection Exporter and select your new collection. Click Export Collection. In a few seconds you get a link to download the collection file.

3. Right click the link and download the file to your local drive. This file is the collection zip file. It contains all the code and settings for the add-ons and the collection you created.

4. If your collection uses a dotnet assembly you have created on your workstation, the assembly DLL file needs to be added to the collection zip file manually.

The latest copy of the assembly can be found in the \Addons folder of your Contensive installation, at \program files (x86)\kma\Contensive by default. Copy the file(s) and paste it into the collection zip file.

Steps to install a collection file on a new site

1. Create a new development site on your workstation.

2. On the new site, run the Add-on Manager. The add-on manager is on the Navigator directly under Manage Add-ons.

3. Open the tab labeled "Add Manually", select your new add-on collection zip file and click OK. In a few seconds it will come with basic instructions, and your collection will be installed on the navigator.

Integrating a Visual Studio Assembly into an Add-on

This tutorial demonstrates how to integrate a Visual Studio windows library assembly into a Contensive Add-on. The Add-on Collection used in this tutorial is the one created in the earlier tutorial.

Steps to download and Install the Contensive Add-on Visual Studio Project and Item Template:

1. Get the Visual Studio Template Project from GitHub or Download a zip file.

2. Open the appropriate project, Visual Basic or C sharp.

3. Create a Project Template.

Click File > Export Template. Select Project Template and click Next. On the template options page, change the Template Name to "Contensive Add-on Collection" and click Finish. Use this new template when starting a new add-on collection project.

4. Create an Item Template.

Click File > Export Template. Select Item Template and click Next. Select the addonClass and click next. Do not add any item references and click next. Click Finish to create an item template. Use this template when adding a new add-on class to a project.

Steps to create a new Visual Studio Project that you can call from a Contensive Add-on:

1. Open Visual Studio and create a new project. In the New Project dialog, select the Contensive Add-on Collection template. This is the template you created in the first section of this tutorial. Set the project and solution names and select the location to save your project. Click OK.

2. When the project is finished building, open the project properties and configure as follows:

In the Application tab, set the assembly name similar to the project's name. In this example I will use SampleCollection. For visual basic, set the Root Namespace to empty. For c-sharp, you can ignore the default namespace.

Set the Build Events. For c-sharp they are in the Build Events tab. For visual basic, click the Build Events button in the Compile tab. There are two copy commands in the Post Build section. You only need the one that applies to your machine. If you have a 64-bit machine, delete the line with "Program Files". If you have a 32-bit machine, delete the one with "Program Files (x86)". If you leave them both, it still works, you will just see a copy error for one of them after each build.

Under references, add the Contensive API object, cpBase.dll found typically found in Project Files (x86)\kma\Contensive

3. The class created with the project, named addonClass by default will contain your add-on executable code. Configure the class as follows.

Open the addonClass and set the namespace to represent your collection. In this case I will use SampleCollection.

Change the public class name to represent the addon functionality. In this case I will use helloWorldClass.

The only method in the class is Execute(). It simply returns the string "Visual Studio Contensive Addon - OK Response"

4. Build the project.

Steps to call your Visual Studio assembly from a Contensive Add-on:

1. Go to your Contensive development site and open the admin page (/admin). If the sample collection from the earlier tutorial is not in your site, go to the earlier tutorial and create it.

2. Edit the add-on in the collection. Click the DLL Tab and enter the Dot Net Class Full Name as collectionName.className. In this case I entered SampleCollection.helloWorldClass. Save.

3. Run the add-on from the Navigator on the left by opening Navigator >> Manage Addons >> Sample Collection >> click on Sample Addon.

4. When the add-on runs, the screen includes the returned message from your Visual Studio class, "Visual Studio Contensive Addon - OK Response"

Single-Step Debugging a Visual Studio Assembly

This tutorial shows you how to debug a dot net assembly used as an add-on in a Contensive site. You should already have completed the tutorial Integrating a Visual Studio Assembly into an Add-on Collection. This tutorial starts where this previous tutorial left off.

Steps to set a break point to single-step through your code:

1. Open your development website to the Admin site Admin Navigator >> Manage Add-ons >> Sample Collection >> Click on Sample Addon.

Your sample addon runs and displays the text returned from the Visual Studio Assembly. The default string was "Visual Studio Contensive Addon - OK Response"

2. Open the Visual Studio solution for this add-on.

3. Set a breakpoint in the code (put the cursor on the line and hit F9). I set it on the returnHtml line.

Steps to attach the Visual Studio Debugger to the running process and break on the break-point:

1. Open a command prompt "As Administrator" and run IISReset.

2. Build the project.

If you get an error copying in the post-build step of the build, make sure you have not hit site since the last IISReset. You may need to reset again.

3. In your browser, hit a page on your website.

4. Go to Visual Studio and attach to the new IIS Process you just created by hitting a page.

In Visual Studio, click the Tools menu. Click the Attach to Process (Ctrl-Alt-P). If your development site runs on PHP, the process(es) will be php-cgi.exe. Be sure to attach to all processes you find.

5. Go back to your site and hit the page that includes your addon. The Visual Studio break point hits and you can single-step through your assembly code.

If you followed these steps and the breakpoint does not hit:

1. Try again.

2. In the Attach to process dialog, verify a new process has not started. If so, select it as well and hit the page again.

3. In the Attach to Process dialog, under Attach To:, open the Select Code Type dialog and try both Automatic (the default), and "Managed (v2.0, v1.1, v1.0)"

Creating a Manager Add-on

A manager environment is a group of add-ons that work together to create a single place where a user goes to manage one type of work. For instance, the Invoice Manager gathers all the features needed to handle system accounting.

1. Create a development site on your local development machine (earlier tutorial).
2. Install the Developer Add-on Samples collection from the Contensive Addon Manager. This installs a samples collection with a few sample addons. One of the sample addons is the Manager Sample.
3. Open the Add-on Samples collection and transfer dependencies to your collection.
4. Open the manager sample add-on and clear the guid in the control tab. This will prevent future installations of the samples collection from overwriting your work.
5. Now you can use the addon manager to uninstall the addon samples collection.
6. Get the "Add-on Samples" code from GitHub, Contensive/Addon Samples. This gives you access to all the source code for the Visual Studio project. When you compile this project, it should match the Manager Sample.
7. Go to the Visual Studio and change the namespace to represent your project.
8. Go to your development and edit the Manager Sample addon, changing the DotNet name space in the DLL tab to match the changes you made in the project.
9. Recompile and the pr

Theme Manager Quick Import Tutorial

This tutorial shows you how to use the Quick Import tool in the Theme Importer. The purpose of the Theme Importer Quick Import to to scrape a template from an existing website and setup a Template record under Manage Design that can be used on the current site.

Steps to capture a website page into a site template:

1. Install the Theme Manager from the Addon Manager.
2. Go to Navigator >> Manage Addons >> click on Theme Manager.
3. Click on Quick Import at the top of the the page.
4. In Template Name, enter "TestTheme". This name has to be unique, so if this template already exists either delete in the templates, or modify this name to make is unique.
5. In Source URL, enter http://www.contensive.com.
6. For Import, select Save To File
7. Click [Begin Import]
8. When complete, there will be a few errors relating to resources that could not be copied to the site because they are reserved. That is OK.
9. Go to Navigator >> Manage Design >> click on templates.
10. Edit the new record named TestTheme.
11. It contains an import statement with the filename that was created during the import, "Template_TestTheme"
12. To see the file, use the Website File Manager (Navigator >> Tools >> click on Website File Manager) and edit the new template file. All the templates resources will be that as well.

Steps to use the new TestTheme for a page

1. Go the the public site for your website and turn on Edit.
2. Navigate to a page you want to convert to the new template, or add a child page.
3. Edit the new page.
4. Go to the Features tab, and select Test Theme in the Template selector.
5. Hit OK to save the page and when you return to the public site, it will use the new template.