<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" >
<head>
<title>Eucalypto documentation</title>
</head>
<body>
<h1>Eucalypto</h1>
<img src="EucalyptoLogoBig.png" alt="Eucalypto Logo" />
<p>
<small>Lib Version: 0.8.6.0 BETA<br />
Doc Version: 1.7 DRAFT</small>
</p>
<ul>
<li><a href="http://www.devage.com/archive/Eucalypto_0_8_6_0.zip">Download source and binary</a></li>
<li><a href="http://www.devage.com/eucalypto/">Online demo website</a></li>
<li>Subversion repository: <a href="https://svn.quanticosoft.com/devage/">https://svn.quanticosoft.com/devage/</a></li>
</ul>
<div id="TOC"></div>
<h2>Introduction</h2>
<p>Eucalypto is an open source .NET business/server library to help writing ASP.NET content management web sites.
Eucalypto currently supports these features:</p>
<ul>
<li>Users/Membership</li>
<li>Roles</li>
<li>Profiles</li>
<li>Forum
<ul>
<li>Categories</li>
<li>Attachments</li>
<li>Answer notifications</li>
<li>Formatted text</li>
<li>RSS</li>
<li>Category level permissions</li>
</ul>
</li>
<li>Content management
<ul>
<li>Categories</li>
<li>Formatted text</li>
<li>Attachments</li>
<li>RSS</li>
<li>Category level permissions</li>
</ul>
</li>
<li>News
<ul>
<li>Categories</li>
<li>RSS</li>
<li>Category level permissions</li>
</ul>
</li>
</ul>
<p>Eucalypto uses NHibernate for all data access and can work with any database supported by NHibernate (SQLite, SQL Server, MySql, Firebird, Access, Oracle, ...).</p>
<p>Eucalypto is well integrated with ASP.NET 2.0 using the standard provider model classes (MembershipProvider, RoleProvider, ProfileProvider, ...).</p>
<img src="Architecture.png" alt="Architecture" />
<h2>Why Eucalypto?</h2>
<p>My goal is to create a light project that can be used with any ASP.NET compatible enviroment, without requiring a specific database or additional framework.
Eucalypto is composed by a set of .NET assemblies that you must only reference from your project.</p>
<p>Unlike many other similar projects Eucalypto doesn't have a predefined user interface. Eucalypto is simply a library that can be used from your pages.</p>
<p>Eucalypto is not an all-or-nothing solution. You can use only a subset of the features of Eucalypto. For example you can use the forum from Eucalypto but continue to use an existing solution for the users and roles. Each feture is isolated.
For this reason is very easy to integrate Eucalypto in an existing ASP.NET web site.</p>
<p>If configured and used in the right way I think that Eucalypto is suitable for many situations expecially because it is easy to extend if required.
You can always implement a custom provider implementation or change the default implementation for your special needs.</p>
<p>Eucalypto use NHibernate for all the data access, for this reason you can use a wide range a database server. See the NHibernate documentation for a list of supported databases.</p>
<p>There are a lot of projects that can be used to create a CMS portal, free or commercial, with similar features of Eucalypto;
what are the advantages of Eucalypto?</p>
<ul>
<li>you can integrate Eucalypto with existing site or architecture (Web Parts, SharePoint, an existing CMS portal, ...)</li>
<li>you can support advanced or customized user interfaces (accessibility, globalization, wap, xaml/wpf, ajax, ...) or use a different presentation layer but the same business layer</li>
<li>you can easily extend/change the business layer (thanks to the provider architecture)</li>
<li>you are not limited by the features of the portal</li>
<li>you can use a wide range of database types (thanks to NHibernate)</li>
<li>there is a clean separation between the presentation layer and the business layer</li>
<li>you can use the full power of ASP.NET and use well known technologies (master pages, themes, user controls, membership, ...)</li>
</ul>
<h2>Appropriate uses for Eucalypto</h2>
<p>Eucalypto uses SQLite as a default database but thanks to NHibernate you can configure Eucalypto to use many other solution (SQL Server, MySql, Oracle, ...).
SQLite database is a perfect solution for small web site. If you have thousands of users and visits probably it is better to use another kind architecture.</p>
<p>Eucalypto must be used by developers, it is not for end users or power users.
You must known how to develop an ASP.NET application.</p>
<p>Eucalypto has some important advantages, but also some disadvantages.
The most important consideration is that creating a web site with Eucalypto require some development and configuration.
Eucalypto it is not a complete web portal, it is a library. You need some time to create a complete and running web site.</p>
<p>If you are looking for a complete portal or different solution you can probably try with one of these other projects:</p>
<ul>
<li><a href="http://office.microsoft.com/sharepoint/">http://office.microsoft.com/sharepoint/</a></li>
<li><a href="http://www.joomla.org">http://www.joomla.org</a></li>
<li><a href="http://www.atlassian.com/">http://www.atlassian.com/</a></li>
<li><a href="http://www.rainbowportal.net/">http://www.rainbowportal.net/</a></li>
<li><a href="http://www.dotnetnuke.com/">http://www.dotnetnuke.com/</a></li>
<li><a href="http://www.communityserver.org/">http://www.communityserver.org/</a></li>
<li><a href="http://www.phpnuke.org/">http://www.phpnuke.org/</a></li>
<li><a href="http://www.yetanotherforum.net/">http://www.yetanotherforum.net/</a></li>
<li><a href="http://www.codeplex.com/MyWebPagesStarterKit">http://www.codeplex.com/MyWebPagesStarterKit</a></li>
<li>Many others ...</li>
</ul>
<h2>Requirements</h2>
<p>Currently Eucalypto is developed using .NET 2, Windows, IIS and SQLite (or SQL Server).
Eucalypto is written using 100% managed code, but some references are not compiled as managed library (for example SQLite).
</p>
<p>Probably using the right database (like MySQL) Eucalypto can be executed also on Linux and Mono but I don't have tested it for now.
I don't known if the latest release of NHibernate and Log4net are fully compatible with other platforms but I hope to don't have many problems in the future.
</p>
<h2>Packages</h2>
<p>Eucalypto is composed by 2 package:</p>
<ul>
<li><code>Eucalypto1</code> - Main Eucalypto package. Contains the source and binary files for Eucalypto.
<ul>
<li><code>Eucalypto</code> - Eucalypto.dll assembly</li>
<li><code>Eucalypto.Test</code> - Eucalypto NUnit test assembly</li>
</ul>
</li>
<li><code>Eucalypto1.Demo</code> - Demo package.
<ul>
<li><code>WebSite</code> - Demostration ASP.NET website</li>
</ul>
</li>
</ul>
<h2>Demostration web site</h2>
<p>If you want you can try the demo project online at: <a href="http://www.devage.com/eucalypto/">http://www.devage.com/eucalypto/</a>.</p>
<p>You can also install the demo project on your server if you want to look at the code or modify it.
Here the steps to run on your server the Eucalypto demo project:</p>
<ul>
<li>download the Eucalypto.Demo package, open it with Visual Studio 2005 and run WebSite project</li>
<li>open the Setup.aspx page to configure the database and create an administrator user</li>
<li>open administration page at Admin/Default.aspx for the administrative tasks</li>
</ul>
<p>Now you can start to use the Eucalypto demo project.
See the following sections if you need more informations on the available configurations.</p>
<h2>Creating your web site</h2>
<p>One common method of using Eucalypto is by downloading the Eucalypto.Demo package and use it as a starting point.
Eucalypto.Demo contains some useful classes and a working configuration. Here a short description of the Eucalypto.Demo components:</p>
<ul>
<li><code>\web.config</code> - Main configuration file.</li>
<li><code>\Site.master</code> - Page used for the master page.</li>
<li><code>\Global.asax</code> - Main application class.</li>
<li><code>\Controls\*.*</code> - Some common user controls.</li>
<li><code>\Admin\*.*</code> - Administration pages.</li>
<li><code>\App_Themes\*.*</code> - Themes, skin, css and images</li>
<li><code>\Setup.aspx</code> - Page used to create the database schema (can be removed in the production enviroment).</li>
<li><code>\User\*.*</code> - User management pages (user settings, change password, ...).</li>
<li><code>\Forum\*.*</code> - Forum management pages.</li>
<li><code>\Wiki\*.*</code> - Wiki/articles management pages.</li>
<li><code>\News\*.*</code> - News management pages.</li>
</ul>
<p>Many of the pages can simply used as a starting point and if you are already familiar with ASP.NET you can see
that the code used is quite simple.</p>
<p>For more informations about the configuration file see <a href="#Configuration">Configuration section</a>. For more informations about the required references see <a href="#References">References section</a>.</p>
<h2>Providers overview</h2>
<p>All the base features of Eucalypto are created using a Provider Model pattern (a patter similar to the Inversion Of Control).
Provider Model pattern guarantee an easily customized and extended.
If you want you can create your own providers to save data to another data source or with a different format or with special business rules.</p>
<p>ASP.NET 2 already use the provider pattern for for the membership, roles and profiles features.</p>
<p>Currently Eucalypto implements these providers:</p>
<ul>
<li><code>Eucalypto.Membership.EucalyptoMembershipProvider</code> - An implementation of the System.Web.Security.MembershipProvider.</li>
<li><code>Eucalypto.Roles.EucalyptoRoleProvider</code> - An implementation of the System.Web.Security.RoleProvider.</li>
<li><code>Eucalypto.Notification.EucalyptoSmtpNotificationProvider</code> - A new provider that can be used to send notification to users using SMTP and preconfigured e-mail templates. Used by the forum provider to notify users.</li>
<li><code>Eucalypto.Profile.EucalyptoProfileProvider</code> - An implementation of the System.Web.Profile.ProfileProvider.</li>
<li><code>Eucalypto.Forum.EucalyptoForumProvider</code> - A new provider that can be used to create a complete forum solution.</li>
<li><code>Eucalypto.Wiki.EucalyptoWikiProvider</code> - A new provider that can be used to insert, update and retrive articles.</li>
<li><code>Eucalypto.News.EucalyptoNewsProvider</code> - A new provider that can be used to manage news.</li>
</ul>
<p>Each provider is isolated from the other.
For example you can use the forum provider with eucalypto database and the membership provider using the default SQL Server database.</p>
<h2><a id="Configuration">Configuration</a></h2>
<p>Depending on what part of Eucalypto you want to use you need different settings.
Usually the most important setting is the connection string.</p>
<p>You can create a standard <code>connectiostring</code> element inside the web.config,
and set a connection string with this format:</p>
<pre>DriverClass=DRIVER;Dialect=DIALECT;CONNECTION_STRING</pre>
<p>The connection string is formed by 3 section:</p>
<ul>
<li>DriverClass=DRIVER - The NHibernate driver to use. See NHibernate documentation for more details about drivers.</li>
<li>Dialect=DIALECT - The NHibernate dialect to use. See NHibernate documentation for more details about dialects.</li>
<li>CONNECTION_STRING - The other part of the connection string is used directly and can be different for each driver.</li>
</ul>
<p>The first 2 properties are used for the NHibernate configuration.
You can also use a special variable <code>|DataDirectory|</code> that will be replaced with the site server application data path.</p>
<h3>SQLite</h3>
<p>In the following code you can see an example of a connection to a SQLite database.</p>
<pre>
<connectionStrings>
<clear/>
<!-- SQLite connection string -->
<add name="DefaultConnection"
connectionString="DriverClass=NHibernate.Driver.SQLite20Driver;Dialect=NHibernate.Dialect.SQLiteDialect;Data Source=|DataDirectory|\data.db3" />
</connectionStrings>
</pre>
<p>Remember that you must use a directory where the ASP.NET process has read and write permissions.
Below an example on how to configure write permission to the App_Data folder on Windows 2003:</p>
<img src="AppDataSecurity.png" alt="Config App_Data Security" />
<p>SQLite driver automatically create the database file if doesn't exist.</p>
<h3>SQL Server</h3>
<p>In the following code you can see a connection string for SQL Server 2005.</p>
<pre>
<connectionStrings>
<!-- SQL Server 2005 connection string -->
<add name="DefaultConnection"
connectionString="DriverClass=NHibernate.Driver.SqlClientDriver;
Dialect=NHibernate.Dialect.MsSql2005Dialect;
Data Source=localhost;Initial Catalog=Eucalypto;Integrated Security=SSPI;"
/>
</connectionStrings>
</pre>
<p>You must manually create the empty database and then give to the ASP.NET process read and write permissions to the database using "SQL Server Management Studio" or an appropriate SQL script.
For more informations about security try to look at the following MSDN article: <a href="http://msdn2.microsoft.com/en-us/library/ms998292.aspx#paght000008_step3">'How To: Connect to SQL Server Using Windows Authentication in ASP.NET 2.0'</a>.
</p>
<p>To create the database you can use this script:</p>
<pre>CREATE DATABASE Eucalypto</pre>
<h3>Other databases</h3>
<p>Here a list of connection strings for the most common databases:</p>
<ul>
<li><strong>SQLite</strong> - <code>DriverClass=NHibernate.Driver.SQLite20Driver;Dialect=NHibernate.Dialect.SQLiteDialect;Data Source=|DataDirectory|\data.db3</code></li>
<li><strong>SQL Server 2005</strong> - <code>DriverClass=NHibernate.Driver.SqlClientDriver;Dialect=NHibernate.Dialect.MsSql2005Dialect;Data Source=localhost;Initial Catalog=Eucalypto;Integrated Security=SSPI;</code></li>
<li><strong>SQL Server Express 2005</strong> - <code>DriverClass=NHibernate.Driver.SqlClientDriver;Dialect=NHibernate.Dialect.MsSql2005Dialect;data source=.\SQLEXPRESS;Integrated Security=SSPI;AttachDBFilename=|DataDirectory|data.mdf;User Instance=true</code></li>
<li><strong>SQL Server 2000</strong> - <code>DriverClass=NHibernate.Driver.SqlClientDriver;Dialect=NHibernate.Dialect.MsSql2000Dialect;Data Source=localhost;Initial Catalog=Eucalypto;Integrated Security=SSPI;</code></li>
<li><strong>MySql</strong> - <code>DriverClass=NHibernate.Driver.MySqlDataDriver;Dialect=NHibernate.Dialect.MySQLDialect;Database=Eucalypto;Data Source=SomeServer;User Id=SomeUser;Password=SomePassword</code></li>
<li>...</li>
</ul>
<h3>Create database schema</h3>
<p>Now you must create the Eucalypto database schema.
I have written a page, Setup.aspx (inside the WebSiteTest project), that can be used to create the required database schema.
You can usually copy this page inside your project and open it with your browser (NOTE: for security reason this page can be executed only from the local server machine).</p>
<img alt="Setup" src="Setup.png" />
<p>This page use the <code>Eucalypto.SchemaGenerator.GenericGenerator</code> class to generate the schema for the selected connection string.
You can select the connection string using the drop down at the top of the page (this drop down is loaded with the current connections configured inside the web.config)
and then click on the 'Create schema' button to generate the schema.</p>
<p>The <code>Eucalypto.SchemaGenerator.GenericGenerator</code> class use <code>NHibernate.Tool.hbm2ddl.SchemaExport</code> code to generate the schema.
If you have problems you can always create manually the database tables.</p>
<p>Remember that for now this tool cannot upgrade an existing table. If the table already exist its content will be deleted.</p>
<p>Always in the Setup.aspx page, there is also a feature to create the administrative user and role, you must simply choose a new passowrd and click on the 'Create admin user' button.</p>
<h3>Administrator features</h3>
<p>I have created a set of pages for the most important administrative tasks. You can copy the Admin folder of the WebSiteTest project inside your web site.
In this folder you can find some pages to configure many features of Eucalypto.</p>
<p>Open the Admin/Default.aspx page for an overview of the available configurations.
This page requires you to login as an administrator (<code>administrators</code> role), so you must first have correctly configured the user and roles and have created an admin user.</p>
<p>After you have configured the main features you can start to use Eucalypto.
See the sections below for the configuration for each feature.</p>
<h2>Membership and Roles</h2>
<p>The Membership provider is an ASP.NET provider. ASP.NET membership gives you a built-in way to validate and store user credentials, it can be integrated with ASP.NET role management to provide authorization services for your site.</p>
<p>Database diagram:</p>
<img src="DBDiagram_Membership.png" alt="Database diagram membership" />
<h3>Configuration</h3>
<p>To use the membership and role features you must configure ASP.NET to use the Eucalypto providers, adding this section inside the web.config file.</p>
<pre>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
<system.web>
<!-- Authentication mode -->
<authentication mode="Forms">
<forms loginUrl="Login.aspx" defaultUrl="Default.aspx">
</forms>
</authentication>
<!-- Authorization-->
<authorization>
<!-- Allow all -->
<allow users="?"/>
</authorization>
<!-- Membership Provider -->
<membership defaultProvider="EucalyptoMembershipProvider">
<providers>
<clear/>
<add name="EucalyptoMembershipProvider" type="Eucalypto.Membership.EucalyptoMembershipProvider, Eucalypto"
connectionStringName="DefaultConnection"
applicationName="Default"
minRequiredNonAlphanumericCharacters="0"
minRequiredPasswordLength="4"
/>
</providers>
</membership>
<!-- Role Provider -->
<roleManager enabled="true" defaultProvider="EucalyptoRoleProvider">
<providers>
<clear />
<add name="EucalyptoRoleProvider"
connectionStringName="DefaultConnection"
applicationName="Default"
type="Eucalypto.Roles.EucalyptoRoleProvider, Eucalypto" />
</providers>
</roleManager>
</system.web>
</configuration>
</pre>
<p>You can configure the users and roles using the standard ASP.NET Configuration web site.</p>
<img src="ASPNetConfiguration.png" alt="ASP.Net Configuration" />
<h3>Usage</h3>
<p>There are many good articles about Membership and Role features of ASP.NET, here some links:</p>
<ul>
<li><a href="http://msdn2.microsoft.com/en-us/library/yh26yfzy.aspx">MSDN - Introduction to Membership</a></li>
<li><a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnpag2/html/PAGExplained0002.asp">MSDN - Explained: Forms Authentication in ASP.NET 2.0</a></li>
<li><a href="http://aspnet.4guysfromrolla.com/articles/120705-1.aspx">4guysfromrolla.com - Examining ASP.NET 2.0's Membership, Roles, and Profile, By Scott Mitchell</a></li>
<li><a href="http://www.odetocode.com/Articles/427.aspx">OdeToCode.com - Membership and Role Providers in ASP.NET 2.0, by Scott Allen</a></li>
</ul>
<p>Please not that for now the EucalyptoMembershipProvider supports only Hashed password and don't support the password retrieval feature (EnablePasswordRetrieval), supports only password reset.</p>
<h2>Profile</h2>
<p>The profile provider is an ASP.NET provider. You can provide users of your Web site with a custom experience by defining and using profile properties. You can use profile properties to track any custom information your application requires.</p>
<p>Database diagram:</p>
<img src="DBDiagram_Profile.png" alt="Database diagram profile" />
<h3>Configuration</h3>
<p>To use the profile features you must configure ASP.NET to use the Eucalypto providers, adding this section inside the web.config file.</p>
<pre>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
<system.web>
<!-- Profile -->
<!-- Enable anonymousIdentification only if really required -->
<anonymousIdentification enabled="true" />
<profile defaultProvider="EucalyptoProfileProvider">
<providers>
<clear />
<add name="EucalyptoProfileProvider" type="Eucalypto.Profile.EucalyptoProfileProvider, Eucalypto"
connectionStringName="DefaultDB" applicationName="Default" />
</providers>
<properties>
<!-- Just for test -->
<add name="FavoriteColor" type="String" defaultValue="Blue" allowAnonymous="true" />
</properties>
</profile>
</system.web>
</configuration>
</pre>
<h3>Usage</h3>
<p>There are many good articles about profile features of ASP.NET, here some links:</p>
<ul>
<li><a href="http://msdn2.microsoft.com/en-us/library/at64shx3.aspx">MSDN - ASP.NET Profile</a></li>
<li><a href="http://www.codeguru.com/csharp/.net/net_asp/controls/article.php/c10179/">codeguru.com - ASP.NET 2.0 Profile: Simple User Personalization for Your Web Apps, by Thiru Thangarathinam</a></li>
<li><a href="http://www.odetocode.com/Articles/440.aspx">OdeToCode.com - Profiles In ASP.NET 2.0, by Scott Allen</a></li>
</ul>
<h2>Notification</h2>
<h3>Configuration</h3>
<p>To use the notification features you must first configure the notification provider, adding these sections inside the web.config:</p>
<pre>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
<configSections>
<!-- Add the notification provider section -->
<section name="notificationManager" type="Eucalypto.Notification.NotificationProviderConfiguration, Eucalypto"/>
</configSections>
<!-- EMail SMTP configuration -->
<system.net>
<mailSettings>
<smtp>
<network host="yourSmtpServer" port="25" userName="username" password="password" />
</smtp>
</mailSettings>
</system.net>
<!-- Notification provider -->
<notificationManager>
<providers>
<add name="EucalyptoForumSmtp" type="Eucalypto.Notification.EucalyptoSmtpNotificationProvider, Eucalypto"
template="App_Data\MailTemplate_Forum.xml" />
</providers>
</notificationManager>
</configuration>
</pre>
<p>Use the <code>enabled</code> property to enable or disable the provider.
The <code>template</code> property must be configured with a valid xml file that contains the template data used when sending e-mails.
Here an example:</p>
<pre>
<?xml version="1.0" encoding="utf-8" ?>
<template>
<sender>youremail@yourserver.com</sender>
<subject>[Eucalypto - Forum ?forumDescription?] ?title?</subject>
<body html="true">
<![CDATA[
<p>Forum: <strong>?forumDescription?</strong></p>
<p>You have received a response from ?user?.</p>
<p>Title: <strong>?title?</strong></p>
<p><i>?body?</i></p>
<a href="http://yourserver/Forum/ViewTopic.aspx?id=?idtopic?">View topic</a>
]]>
</body>
</template>
</pre>
<p>You can use some parameters specified by who will use the notification provider (for example ?title?, ?user?, ...) that will be replaced by the actual data of the notification. In this case I have used the parameters used by the forum provider.</p>
<h3>Usage</h3>
<p>The <code>EucalyptoSmtpNotificationProvider</code> provider can send notification using SMTP (e-mail).
You can use the static property <code>Eucalypto.Notification.NotificationManager.Providers</code> to read a list of the configured providers.</p>
<p>Here a simple example to send a notification:</p>
<pre>
//Create the parameters list
Dictionary<string, string> parameters = new Dictionary<string, string>();
parameters.Add("?title?", message.Title);
parameters.Add("?body?", xhtml);
parameters.Add("?user?", message.Owner);
System.Web.Security.MembershipUser destinationUser = System.Web.Security.Membership.GetUser(user);
if (destinationUser != null &&
NotificationProvider.UserCanReceiveNotification(destinationUser))
{
//Send a notification
NotificationProvider.NotifyUser(destinationUser, parameters);
}
</pre>
<h2>Forum</h2>
<p>Database diagram:</p>
<img src="DBDiagram_Forum.png" alt="Database diagram forum" />
<h3>Configuration</h3>
<p>To use the forum features you must first configure the forum provider, adding these sections inside the web.config:</p>
<pre>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
<configSections>
<!-- Add the forum provider section -->
<section name="forumManager" type="Eucalypto.Forum.ForumProviderConfiguration, Eucalypto"/>
</configSections>
<!-- Forum provider -->
<forumManager defaultProvider="EucalyptoForumProvider">
<providers>
<clear/>
<add name="EucalyptoForumProvider" type="Eucalypto.Forum.EucalyptoForumProvider, Eucalypto"
connectionStringName="DefaultConnection" notificationProvider="EucalyptoSmtp" />
</providers>
</forumManager>
</configuration>
</pre>
<p>You can configure the forum provider with these properties:</p>
<ul>
<li><code>connectionStringName</code> - The connection used to store forum data.</li>
<li><code>notificationProvider</code> - Notification provider to use to notify users if someone responde to a message. See the Notification section for more details. Leave blank to don't use a notification provider.</li>
</ul>
<p>The default provider is the <code>EucalyptoForumProvider</code> that use NHibernate to store any forum related data.
Consider that if required you can always implement your custom forum provider.</p>
<p>Internally the forum provider use the Notification provider, so usually you must also configure it.</p>
<h3>Usage</h3>
<p>You can find all the forum related classes inside the <code>Eucalypto.Forum</code> namespace.
You must use the <code>Eucalypto.Forum.ForumManager</code> class to insert, read or delete forum data. The main entities are:</p>
<ul>
<li>Category - a forum category represents a forum. A forum category is composed by a list of topics.
</li>
<li>Topic - a topic represents the subject of discussion, the initial message posted to the discussion. A topic is composed by a list of messages.
</li>
<li>Message - a message is the main entity of a forum. Represents the text posted by the user of the forum.
</li>
</ul>
<p>You can enable or disable attachments, accepted extensions and maximum file size or configure the security for each forum. Use the administration section to configure each forum.</p>
<p>The forum messages are saved using the XHTML format.</p>
<p>Here an example to create a forum category, insert some messages and search for it:</p>
<pre>
//Create category
Eucalypto.Forum.Category category = Eucalypto.Forum.ForumManager.CreateCategory("test", "test");
//Create a topic (with a message)
Eucalypto.Forum.Topic topic;
Eucalypto.Forum.Message message;
Eucalypto.Forum.ForumManager.CreateTopic(category, "user1", "Title 1",
"<p>Body text</p>", null, out topic, out message);
//Create an answer (message)
Eucalypto.Forum.Message message1 = Eucalypto.Forum.ForumManager.CreateMessage(topic, message.Id,
"user1", "RE: Title 1", "<p>Response</p>", null);
//Create a second answer (message)
Eucalypto.Forum.Message message2 = Eucalypto.Forum.ForumManager.CreateMessage(topic, message1.Id,
"user1", "RE: Title 1", "<p>Response</p>", null);
//Create a second topic
Eucalypto.Forum.Topic topic2;
Eucalypto.Forum.Message message3;
Eucalypto.Forum.ForumManager.CreateTopic(category, "user2", "Title 2", "<p>Body text</p>",
null, out topic2, out message3);
//Find the previous messages (filtering the owner field)
Eucalypto.PagingInfo paging = new Eucalypto.PagingInfo(10, 0);
Eucalypto.Forum.ForumManager.FindMessages(Eucalypto.Filter.MatchOne( category.Name),
null,
Eucalypto.Filter.MatchOne("user1"),
null,
null, null,
paging);
//Find the previous messages (filtering by a field)
Eucalypto.Forum.ForumManager.FindMessages(Eucalypto.Filter.MatchOne(category.Name),
Eucalypto.Filter.ContainsOne("RE:"),
null, null, null, null, paging);
//Delete a topic
Eucalypto.Forum.ForumManager.DeleteTopic(topic);
//Create another topic
Eucalypto.Forum.Topic topic3;
Eucalypto.Forum.Message message4;
Eucalypto.Forum.ForumManager.CreateTopic(category, "test", "Title 3", "<p>Body text</p>", null, out topic3, out message4);
//Delete the category
Eucalypto.Forum.ForumManager.DeleteCategory(category);
</pre>
<h2>Content Management (Wiki articles provider)</h2>
<p>Database diagram:</p>
<img src="DBDiagram_Article.png" alt="Database diagram wiki" />
<h3>Configuration</h3>
<p>To use the content management features you must first configure the wiki provider, adding these sections inside the web.config:</p>
<pre>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
<configSections>
<!-- Add the wiki provider section -->
<section name="wikiManager" type="Eucalypto.Wiki.WikiProviderConfiguration, Eucalypto"/>
</configSections>
<!-- Wiki provider -->
<wikiManager defaultProvider="EucalyptoWikiProvider">
<providers>
<clear/>
<add name="EucalyptoWikiProvider" type="Eucalypto.Wiki.EucalyptoWikiProvider, Eucalypto"
connectionStringName="DefaultDB" />
</providers>
</wikiManager>
</configuration>
</pre>
<p>You can configure the wiki provider with these properties:</p>
<ul>
<li><code>connectionStringName</code> - The connection used to store article data.</li>
</ul>
<p>The default provider is the <code>EucalyptoWikiProvider</code> that use NHibernate to store any article related data.
Consider that if required you can always implement your custom provider.</p>
<h3>Usage</h3>
<p>You can find all the wiki related classes inside the <code>Eucalypto.Wiki</code> namespace.
You must use the <code>Eucalypto.Wiki.WikiManager</code> class to insert, read or delete article data. The main entities are:</p>
<ul>
<li>Category - a wiki category. A category is composed by a list of articles.
</li>
<li>Article - an article represents the content. A article can contains a list of FileAttachment and a list of VersionedArticle.
</li>
<li>FileAttachment - a message is the main entity of a forum. Represents the text posted by the user of the forum.
</li>
<li>VersionedArticle - Each time the user update the Article the previous version is saved in a new VersionedArticle instance.
</li>
</ul>
<p>You can enable or disable attachments, accepted extensions and maximum file size or configure the security for each category. Use the administration section to configure each category.</p>
<p>The article contents are saved using the XHTML format.</p>
<p>Here an example to insert some articles:</p>
<pre>
//Create a category
Eucalypto.Wiki.Category category = Eucalypto.Wiki.WikiManager.CreateCategory("test", "test");
//Create an article
Eucalypto.Wiki.Article article = Eucalypto.Wiki.WikiManager.CreateArticle(category, "owner1",
"article1", "Title 1", "Description", "<p>body 1</p>");
//Create a second article
Eucalypto.Wiki.Article article2 = Eucalypto.Wiki.WikiManager.CreateArticle(category, "owner2",
"article2", "Title 2", "Description",
"<p>bla bla bla search1 bla bla bla</p>");
//Update an article
article.Body = "<p>body 1 v2</p>";
string myTag = Guid.NewGuid().ToString();
article.Tag = myTag;
Eucalypto.Wiki.WikiManager.UpdateArticle(article, true);
//Read the first version of the article
Eucalypto.Wiki.ArticleBase articleV1 = Eucalypto.Wiki.WikiManager.GetArticleByVersion(article, 1);
//Find an article (filtering using the search string)
Eucalypto.PagingInfo paging = new Eucalypto.PagingInfo(10, 0);
IList<Eucalypto.Wiki.Article> articles = Eucalypto.Wiki.WikiManager.FindArticles(Eucalypto.Filter.MatchOne(category.Name),
Eucalypto.Filter.ContainsAll("search1"),
null, null, null, null, null,
Eucalypto.Wiki.ArticleStatus.All,
paging);
//Find another article (filtering using the Tag)
articles = Eucalypto.Wiki.WikiManager.FindArticles(null, null, null, null,
Eucalypto.Filter.MatchOne(myTag), null, null, Eucalypto.Wiki.ArticleStatus.All, paging);
//Delete an article
Eucalypto.Wiki.WikiManager.DeleteArticle( article );
//Delete the category
Eucalypto.Wiki.WikiManager.DeleteCategory( category );
</pre>
<h2>News</h2>
<p>Database diagram:</p>
<img src="DBDiagram_News.png" alt="Database diagram news" />
<h3>Configuration</h3>
<p>To use the news features you must first configure the news provider, adding these sections inside the web.config:</p>
<pre>
<configuration xmlns="http://schemas.microsoft.com/.NetConfiguration/v2.0">
<configSections>
<!-- Add the news provider section -->
<section name="newsManager" type="Eucalypto.News.NewsProviderConfiguration, Eucalypto"/>
</configSections>
<!-- News provider -->
<newsManager defaultProvider="EucalyptoNewsProvider">
<providers>
<clear/>
<add name="EucalyptoNewsProvider" type="Eucalypto.News.EucalyptoNewsProvider, Eucalypto"
connectionStringName="DefaultDB" />
</providers>
</newsManager>
</configuration>
</pre>
<p>You can configure the news provider with these properties:</p>
<ul>
<li><code>connectionStringName</code> - The connection used to store news data.</li>
</ul>
<p>The default provider is the <code>EucalyptoNewsProvider</code> that use NHibernate to store any news related data.
Consider that if required you can always implement your custom news provider.</p>
<h3>Usage</h3>
<p>You can find all the news related classes inside the <code>Eucalypto.News</code> namespace.
You must use the <code>Eucalypto.News.NewsManager</code> class to insert, read or delete news data. The main entities are:</p>
<ul>
<li>Category - a news category represents a news. A news category is composed by a list of items.
</li>
<li>Item - a item represents a single news. An item is composed by Title, URL, Description, ...
</li>
</ul>
<p>Use the administration section to configure each news category.</p>
<p>Here an example to create a news category and insert some items:</p>
<pre>
//Create a category
Eucalypto.News.Category category = Eucalypto.News.NewsManager.CreateCategory("test", "test");
//Create an item
Eucalypto.News.Item item = Eucalypto.News.NewsManager.CreateItem(category, "owner1",
"Title 1", "Description 1", "http://www.devage.com/", "DevAge home page", new DateTime(2006, 1, 3));
//Create a second item
Eucalypto.News.Item item2 = Eucalypto.News.NewsManager.CreateItem(category, "owner1",
"Title 2", "Description 2", "http://www.devage.com/", "DevAge home page", new DateTime(2006, 10, 3));
//Update an item
item.Description = "Description modified";
Eucalypto.News.NewsManager.UpdateItem(item);
//Find the previous items
Eucalypto.PagingInfo paging = new Eucalypto.PagingInfo(10, 0);
Eucalypto.News.NewsManager.FindItems(Eucalypto.Filter.MatchOne(category.Name),
null, null, null,
paging);
//Delete an item
Eucalypto.News.NewsManager.DeleteItem(item2);
//Delete the entire category
Eucalypto.News.NewsManager.DeleteCategory(category);
</pre>
<h2>Implementation details</h2>
<h3>NHibernate</h3>
<p><cite>"NHibernate is a port of Hibernate Core for Java to the .NET Framework. It handles persisting plain .NET objects to and from an underlying relational database."</cite></p>
<ul>
<li><a href="http://www.hibernate.org/">http://www.hibernate.org/</a></li>
</ul>
<p>You can configure NHibernate to use many kind of databases: SQL Server, Oracle, MySql, ... The default database for Eucalypto is SQLite.</p>
<h3>SQLite</h3>
<p><cite>"SQLite is a small C library that implements a self-contained, embeddable, zero-configuration SQL database engine."</cite></p>
<ul>
<li><a href="http://sqlite.phxsoftware.com/">http://sqlite.phxsoftware.com/</a> - Modified version of SQLite project for .NET. (I have used this version, a special thanks to Robert Simpson for his work)</li>
<li><a href="http://www.sqlite.org/">http://www.sqlite.org/</a> - Original SQLite project</li>
</ul>
<p>To query or update a SQLite database I really suggest to use SQLite Spy, a very powerful and useful tool. Thanks to Ralf Junker. You can download it from: <a href="http://www.yunqa.de/delphi/sqlitespy/">http://www.yunqa.de/delphi/sqlitespy/</a> </p>
<p>Usually you can find the SQLite database inside the App_Data directory.</p>
<p><strong>IMPORTANT NOTES</strong>: SQLite is currently written with C++ as an unmanaged library.
For this reason you must remember that SQLite must be executed with full trust permissions.
If you want to use a shared hosting (run your web site on a hosting company) you must consider that they are usually configured
as medium trust. Medium trust security blocks any P/Invoke code and SQLite cannot run.<br />
In this case you can ask to your hosting company to run your app with full trust or ask to install SQLite library inside GAC.
Remember anyway that Eucalypto can be used with many other databases. For example many hosting companies offers MySql, Access or SQL Server.</p>
<h3>Log4Net</h3>
<p><cite>"log4net is a tool to help the programmer output log statements to a variety of output targets. log4net is a port of the excellent log4j framework to the .NET runtime."</cite></p>
<ul>
<li><a href="http://logging.apache.org/log4net/">http://logging.apache.org/log4net/</a> - Official Log4Net web site</li>
</ul>
<p>Eucalypto internally use log4net for logging exception and warning.
All the log4net configuration can be changed in the <code>web.config</code> file. In the <code>global.asax</code> file I configure Eucalypto with this code: <code>log4net.Config.XmlConfigurator.Configure()</code>
Usually you can find the log4net log file inside the App_Data directory.</p>
<h3>CSS</h3>
<p>I hate CSS .... Every time I must work on a page layout I fight with CSS. For this reason I always look for some simple and clear examples.</p>
<p>I want to thanks Alessandro Fulciniti, <a href="http://blog.html.it/layoutgala/">http://blog.html.it/layoutgala/</a>, for his great work on CSS. For me these are the most clean and simply to use CSS layouts.</p>
<p>For this site a have used a modified version of a CSS layout that I have found on the above page.</p>
<h3>Provider Model</h3>
<p>For more informations about ASP.NET provider model I suggest to read these MSDN articles:</p>
<ul>
<li><a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnaspnet/html/asp02182004.asp">"Provider Model Design Pattern and Specification"</a></li>
<li><a href="http://msdn.microsoft.com/library/default.asp?url=/library/en-us/dnaspp/html/ASPNETProvMod_Intro.asp">"ASP.NET 2.0 Provider Model: Introduction to the Provider Model"</a></li>
</ul>
<h3>RSS</h3>
<p>Eucalypto has an integrated RSS library, written by Brian Kuhn. Thanks for his work.</p>
<p>More info at <a href="http://blog.oppositionallydefiant.com/PermaLink,guid,11b11e4e-f48f-4add-a03f-b43c2a670429.aspx">"RSS 2.0 Class Library and Syndication Provider"</a>.</p>
<p>For informations about RSS format and specifications you can see: <a href="http://blogs.law.harvard.edu/tech/rss">http://blogs.law.harvard.edu/tech/rss</a>.</p>
<h3>XHTML</h3>
<p>All the content written by the users are saved as XHTML.
For example all the wiki content and forum messages are written using XHTML.
I have chosed this format for many reasons:</p>
<ul>
<li>It is the native format for the web pages and is supported by many platforms/browsers</li>
<li>It is a standard and well known format</li>
<li>Can be easily parsed and modified by humans and from code (using any xml parser)</li>
<li>Can be easily converter to other formats</li>
<li>Can be easily used inside email</li>
</ul>
<h3>NUnit</h3>
<p><cite>"NUnit is a unit-testing framework for all .Net languages."</cite></p>
<ul>
<li><a href="http://www.nunit.org/">http://www.nunit.org/</a> - Official NUnit web site</li>
</ul>
<p>I have created a test project for Eucalypto (Eucalypto.Test) with some test case. See <code>Eucalytpo.nunit</code> for the NUnit configuration.</p>
<h3><a id="References">References</a></h3>
<p>Here are the required assemblies that you need to reference:</p>
<ul>
<li><code>Eucalypto.dll</code> - Main Eucalypto assembly</li>
<li><code>NHibernate.dll</code> - NHibernate main assembly</li>
<li><code>Castle.DynamicProxy.dll</code> - Dynamic proxy generator used by NHibernate</li>
<li><code>Iesi.Collections.dll</code> - Advanced collections used by NHibernate</li>
<li><code>NHibernate.Tool.hbm2net.dll</code> - Schema generator for NHibernate</li>
<li><code>log4net.dll</code> - Used for logging</li>
<li>[<code>System.Data.SQLite.DLL</code>] - Optional, required only if you use SQLite.</li>
<li>[<code>nunit.framework.dll</code>] - Optional, required only for Eucalypto.Test NUnit project.</li>
</ul>
<h2>Future works</h2>
<ul>
<li>Extend unit tests</li>
<li>Stress/performance improvements</li>
<li>Create a set of web server controls (or skinned controls) for the Eucalypto providers for easy reuse</li>
<li>Improved search support</li>
<li>HTML Text editor for forum and articles (FCKeditor?)</li>
<li>Issue tracking system</li>
<li>Photo album</li>
<li>Blog</li>
</ul>
<h2>History</h2>
<h3>14 Feb 2007 - Version 0.8.6.0</h3>
<ul>
<li>Fixed an error that prevent to insert null or empty description when generating the RSS item.</li>
<li>Now the Membership and Role providers implementation use a case insensitive search for user name and e-mail (like the MS provider).</li>
</ul>
<h3>28 Jan 2007 - Version 0.8.5.0</h3>
<p>First public release.</p>
<h2><a id="License">License</a></h2>
<p>
Eucalypto LICENSE (MIT style)<br />
<br />
Copyright (c) 2007 www.devage.com, Davide Icardi<br />
<br />
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:<br />
<br />
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.<br />
<br />
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM,
DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE,
ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.<br />
</p>
</body>
</html>
Submit an article or tip