Download Using the Kentico CMS API

Using the Kentico CMS API
Thom Robbins ([email protected]
Bryan Soltis ([email protected])
Agenda
•
•
•
•
•
Overview (Architecture/Objects) (Thom)
CMS Context (Bryan)
Document Management (Thom)
Global Events (Thom)
Modules (Bryan)
Looking at Kentico CMS
Logical three tier architecture…
Presentation layer
Architecture breakdown
Live site pages +
admin UI pages
Web project pages
UI components
Web parts + User
controls
Module web parts
+ Module user
controls
Controls libraries
CMSControls
Module controls
Business layer
Data layer
(+metadata)
Helpers
Enumerations
Infos & Providers
Data engine
Metadata infos
SettingsProvider
GeneralConnection
(Class, Query,
SettingsKey)
Abstract info
Third party code
Module Infos &
Providers
Interfaces
Module definitions
Best Practice Tip
• Kentico CMS web site project provides examples of all sorts of code!
OO Basics - Object Creation Examples
// Create UserInfo
CMS.SiteProvider.UserInfo user = new CMS.SiteProvider.UserInfo();
// Set properties
user.UserName = "Alice";
user.FirstName = "Alice";
user.LastName = "Cooper";
user.FullName = "Alice Cooper";
user.Email = "[email protected]";
user.IsEditor = true;
user.IsGlobalAdministrator = true;
user.PreferredCultureCode = "en-us";
user.Enabled = true;
// Create new user
CMS.SiteProvider.UserInfoProvider.SetUserInfo(user);
// Prepare the TreeProvider (it must be initialized with user information when editing
document structure)
UserInfo ui = UserInfoProvider.GetUserInfo("administrator");
CMS.TreeEngine.TreeProvider tree = new CMS.TreeEngine.TreeProvider(ui);
// Get the document (current culture)
CMS.TreeEngine.TreeNode node =
tree.SelectSingleNode(CMS.CMSHelper.CMSContext.CurrentSiteName,
"/News/TestingWorkflow",
CMS.CMSHelper.CMSContext.CurrentUser.PreferredCultureCode, false, null, false);
if (node != null)
{
// Always delete the document with DocumentHelper, it handles all the
dependencies
CMS.WorkflowEngine.DocumentHelper.DeleteDocument(node, tree, true,
true,true);
}
Example - Creating
new user
Example – Delete
Document
API Everywhere!
• Class View is your Friend
Some Examples…
CMS.SettingsProvider
CMS.GlobalHelper
Library Specific
.SettingsHelper
.DataHelper
CMS.Controls.CM
SControlsHelper
.SQLHelperClass
.ContextHelper
CMS.WorkflowEn
gine.DocumentHe
lper
.TranslationHelp
er
.AJAXHelper
CMS.Blogs.BlogHe
lper
Best practice Tip:
Class view is customizable to allow
personalized organization and viewing
Helpers and general libraries
SettingsProvider
GlobalHelper
Library specific
App_Code
(metadata helpers)
(general helpers)
(module helpers)
(helper functions)
SettingsHelper
(web.config)
/Context
(HTTP context related data)
ControlsHelper
Functions.cs
SettingsKeyHelper
/Data
(web site settings)
(advanced data manipulation and
validation)
CMSControlsHelper
InstallerFunctions.cs
/Globalization
DocumentHelper
BlogFunctions.cs
WebFarmSyncHelperClass
EcommerceFunctions.cs
SqlHelperClass
(low level DB connection, used
only from SettingsProvider)
(resource strings and cultures)
DataHelper
/Markup
(basic data manipulation)
(macros, HTML, XML, text, script)
TranslationHelper
(conversion of IDs based on
code names or GUIDs)
(images and media manipulation
and information)
/Media
Etc.
Etc.
Best Practice Tip
• For general code locate the appropriate helper and use it
• If the helper contains similar methods override and extend
• Implement new behavior in helpers
CMS Context
• CMS.CMSHelper.CMSContext class provides static
methods to access common information
Method
CurrentAliasPath
CurrentDocument
CurrentPageInfo
CurrentSite
CurrentSiteName
CurrentUser
ViewMode
ResolveCurrentPath
Need a code snippet?
Document Management – How documents are stored
• Documents stored in SQL joined tables
– CMS_Tree – Table with basic document data shared between different
language versions. Contains one record for all culture version of the
document
– CMS_Document – Table with document data of specified language
version of the document. Contains one record representing one
language version of the document
– Coupled table – table that contains custom document type fields
CMS_Tree
CMS_Document
Coupled table
CMS_Document
Coupled table
CMS_Document
Coupled table
Best Practice Tip:
Every document is stored in up to three (3) tables. Use the
API to access documents
Document Management – Versioning Internals
• Document versions and its history are stored in separate
tables
– CMS_VersionHistory – Table containing the document versions. Each
version of the document is represented by one record that contains
the complete document data in XML.
– CMS_AttachmentHistory – Table containing the attachment version
records. Each attachment version is bound to one or more document
versions. Every record contains binary data of the attachment.
– CMS_VersionAttachment – Table containing the bindings of the
attachment versions to the document versions.
CMS_VersionAttachment
CMS_AttachmentHistory
Version of attachments
CMS_VersionAttachment
CMS_AttachmentHistory
Version of attachments
CMS_VersionHistory
Document Management Techniques
CMS.TreeEngine.TreeNode
• Not aware of
versioning/workflow/attachments
• Only works with published records
CMS.WorkflowEngine.DocumentHelper
• Versioning/workflow/attachment aware
• Use for all document deletes
Best Practice Tip:
CMS.WorkflowEngine.DocumentHelper is recommended to access
document information
CMS.CMSHelper.TreeHelper allows
access to documents directly
Best Practice Tip:
TreeHelper.GetDocuments checks the view mode and then
calls either TreeProvider or DocumentHelper
Global Events
• Provide a way to execute custom events within the CMS
system
• Managed as a separate projects
• Web Config Key
Best Practice Tip:
Developer documentation contains step by step instructions for
implementing Global Events
Global Event Classes
CustomDataHandler.cs
CustomExceptionHandler.cs
CustomSecurityHandler.cs
• The events are applied to all data items that are stored to the database. It
includes documents, user information or any other settings
• Receives DataClass
• Event applied to all exceptions that occur
• Receives System.exception
• Allows the integration of external databases and modify the authentication
and authorization process
CustomTreeNodeHandler.cs
• Execute custom actions when a document is created, updated or deleted
CustomWorkflowHandler.cs
• Event applied to workflow documents (same as CustomTreeNodeHandler)
• Same as CustomtreeNodeHandler
Best Practice Tip:
For Document events always use either the CustomTreeNodeHandler (no workflow) or
CustomWorkFlowHandler (workflow) not the CustomDataHandler
Modules
• Extend the CMS system to include your custom code
Additional Information
• Best samples are in your project!
• Get your poster
• Documentation http://devnet.kentico.com/Documentation.aspx
• Code Snippet Library http://devnet.kentico.com/Blogs/Thomas-Robbins.aspx
• Marketplace http://devnet.kentico.com/Marketplace.aspx