Developer Guide

C2MS Request Routing

July 12, 2013 By smoore

The C2MS system is designed to answer for all URLs on a website that do not have a physical on-disk file. This is typically accomplished by setting up an apache configuration mod-rewrite rule as follows:

   RewriteEngine on
   <Location />
      Options +FollowSymLinks -Indexes

      RewriteEngine on
      # if a directory or a file exists, use it directly
      RewriteCond %{REQUEST_FILENAME} !-f
      RewriteCond %{REQUEST_FILENAME} !-d

      # All calls to YII PHP will be direct access without rewrite rules
      # otherwise URL's will be forwarded to the c2ms content controller 
      # in Yii via the CmsPageController
      RewriteRule ^(.*)$ /index.php?r=/c2msfoundation/c2msSiteFront/render&__cms_url=%{REQUEST_URI} [L,QSA]

   </Location>

RewriteEngine on

Options +FollowSymLinks -Indexes

RewriteEngine on

# if a directory or a file exists, use it directly

RewriteCond %{REQUEST_FILENAME} !-f

RewriteCond %{REQUEST_FILENAME} !-d

# All calls to YII PHP will be direct access without rewrite rules

# otherwise URL's will be forwarded to the c2ms content controller

# in Yii via the CmsPageController

RewriteRule ^(.*)$ /index.php?r=/c2msfoundation/c2msSiteFront/render&__cms_url=%{REQUEST_URI} [L,QSA]

</Location>

This rule routes traffic to the c2msfoundation module’s C2msSIteFrontController’s actionRender method. The actionRender method determines how to handle the URL using the following rules:

If the request URL matches a physical file on disk, serve via Apache.
The request URL is checked against the cbmApplicationUrl table and if found handled by an application mount.
The request URL is checked against the cbmUrl table and if found handled by the block type renderer associated with the block view joined to cbmUrl.
Active theme checked for error 404 view and if found rendered.
C2MS default 404 view.

Filed Under: Developer Guide

Application mount points

July 12, 2013 By smoore

The C2ms system is designed to handle all of a web site’s URLs and internally respond to requests with the appropriate content and promotion level. This is accomplished via block type renderers and application mount points. Block type renderers are appropriate for content that is thought of as an item like an event, a product or a content page. However, often developers may wish to program a system that controls the entire display – like a document library search. In those cases you may not wish to provide a placeable widget with a block type but instead answer at one or more specific URLs. To accommodate this C2MS provides application mount points.

Application mount points are simple to create, as they require only a simple database entry into the cbmapplicationurl table. For example, to register the documentlibrary module’s LibraryController’s actionIndex method at the /library url we would use the following database command:

INSERT INTO livedata.cbmapplicationurl ( urlprefix, module, controller, action)
VALUES ( '/library', 'documentlibrary', 'library', 'index' );

1 2	INSERT INTO livedata.cbmapplicationurl ( urlprefix, module, controller, action) VALUES ( '/library', 'documentlibrary', 'library', 'index' );

Developers should never program their modules to expect an application to use a given URL for the mount point – as a C2ms user may choose to refactor the URL structure of a site – and the C2ms system will provide an interface to control mount point URLs in the near future. Instead, application mount points should be looked up using the helper class Cbmapplicationurl. For example, to lookup the URL we registered (/library) earlier, we would use:

$strMyUrl = Cbmapplicationurl::applicationUrl( 'documentlibrary', 'library', 'index' );

1	$strMyUrl = Cbmapplicationurl::applicationUrl( 'documentlibrary', 'library', 'index' );

Filed Under: Developer Guide

Overview of C2MS Blocks, BlockViews and BlockTypes

July 12, 2013 By smoore

The C2MS system is designed as an enterprise content management system that can manage both internal content as well as linked content. In order to deal with the many different types of content available as well as the varying promotion requirements typically found with each C2MS provides a block infrastructure. Blocks are best thought of as individual nuggets of content. A block can represent any type of content – an event, an image, a product or even a collection of other blocks like a slideshow of images. Developers must make the C2MS system aware of these content types by registering a new block type. Every block type will receive an entry in the cbmBlockType table, as well as optionally be associated with RenderType and PublishType classes (e.g. RenderSample, PublishSample). The Render class is responsible for loading the content and displaying it when placed within a user view. The Publish class is responsible for moving the block content between promotion stages.

Each block in the C2MS system is represented by an entry in the table “cbmBlock”. The cbmBlock table contains only enough information to refer to a block – not the block’s data itself. It is expected that every block will either use it’s own internal data representation (a file on disk, other database entry, etc.) or extend one of the pre-built C2MS block types for data storage. A GUID key, block_id, uniquely identifies every single block in the system. Blocks may also specify that they are dependent on other blocks to function (e.g. a slideshow may be dependent on images within that slideshow) by creating reference entries in the cbmBlockDependency table. The c2msfoundation module provides many helpers and model classes to work with blocks. It is HIGHLY recommended that the only access to block tables be via these provided helpers instead of direct DAO calls to the cbmBlock tables.

Some blocks represent “super-views” — blocks designed primarily to place other blocks into sections. To accommodate this C2MS features a BlockView. A BlockView is made up of one or more sections, each of which can contain a block. The C2MS provided “page” block type uses block views to allow users to place content blocks into template sections. The cbmBlockView table allows a block to be placed into a cbmSection by creating a cbmblockviewSection record.

Block views have one other major function – they serve to join content to a URL represented in the table cbmUrl. It is important to use a BlockView to provide access to your content and not go directly to the block in order to allow for more than one view of data without having to duplicate that data. Let’s, for example, take the hypothetical block type “product” and assume we want to display this as a web page. If we wrote a renderer for product (RenderProduct) that displayed the product in a fixed fashion we would have to duplicate the product’s data in order to provide a “condensed” and “full” view of the product. By using BlockViews we create two block views — both pointing at the same block_id — but each specifying a different template (e.g. product-brief, product-full).

Filed Under: Developer Guide

C2MS Dashboard Panels

July 12, 2013 By smoore

Developers can add items to the C2MS dashboard or admin sidebar by creating an instance of a class that implements the C2msDashboardComponent and/or C2msSidebarComponent interface in the [your module]/config/c2ms-dashboard.php file. Items that implement the C2msSidebarComponent interface will display in the admin sidebar drawer for logged in users. Items that implement the C2msDashboardComponent will display on the primary C2MS dashboard dialog, and items that implement both will show in both places.

Several easy-to-use classes have been provided to add standard dashboard items:

C2msDashboardButton – A standard action button for display on the dashboard and on the admin sidebar.
C2msDashboardHtml – An open HTML area rendered immediately upon dashboard display.
C2msDashboardAjaxHtml – An open HTML area rendered via asynchronously after the dashboard is loaded.
C2msSidebarPanel – A simple wrapper to display a Yii CWidget on the admin sidebar for a specific module/right code when the drawer is opened on a page rendered by the specified controller/block type.
C2msDashboardCategory – A category to group components inside of for display on the admin sidebar or dashboard dialog.

An example [your module]/config/c2ms-dashboard.php configuration file:

<?php
/**
 * Returns an array of C2msDashboardComponent(s) for use when the administrative 
 * dashboard builds it's icon panel.
 */
return array(
   new C2msDashboardButton(
                            // module.right.code
                            'dynamicform.dynamicformAdmin.admin',

                            // Target Url
                            "/index.php?r=dynamicform/dynamicformAdmin",

                            // Title Text
                            "Contact Form Builder",

                            // Dashboard Sort Order
                            C2msDashboard::SORT_NORMAL,

                            // Dashboard Icon
                            Yii::app()->getModule('dynamicform')->getResourceUrl( 'dashboardicon.png' ),

                            // Category
                            C2msDashboardCategory::PredefinedCategory('content-publishable')
                          ),

   new C2msDashboardAjaxHtml(
                            // module.right.code
                            'dynamicform.report.admin',

                            // Ajax Source URL
                            Yii::app()->createUrl('/dynamicform/report/dashboard'),

                            // Dashboard Sort Order
                            C2msDashboard::SORT_NORMAL,

                            // Category
                            C2msDashboardCategory::PredefinedCategory('reports')
                          ),
);

<?php

/**

* Returns an array of C2msDashboardComponent(s) for use when the administrative

* dashboard builds it's icon panel.

return array(

new C2msDashboardButton(

// module.right.code

'dynamicform.dynamicformAdmin.admin',

// Target Url

"/index.php?r=dynamicform/dynamicformAdmin",

// Title Text

"Contact Form Builder",

// Dashboard Sort Order

C2msDashboard::SORT_NORMAL,

// Dashboard Icon

Yii::app()->getModule('dynamicform')->getResourceUrl( 'dashboardicon.png' ),

// Category

C2msDashboardCategory::PredefinedCategory('content-publishable')

new C2msDashboardAjaxHtml(

// module.right.code

'dynamicform.report.admin',

// Ajax Source URL

Yii::app()->createUrl('/dynamicform/report/dashboard'),

// Dashboard Sort Order

C2msDashboard::SORT_NORMAL,

// Category

C2msDashboardCategory::PredefinedCategory('reports')

);

All c2ms-dashboard configuration’s must return a single array that contains the items for display on the C2MS dashboards (both the admin sidebar as well as the main dashboard). In the above example, a C2msDashboardButton and an C2msDashboardAjaxHtml item are created for display. Refer to the class details below for more information on each component.

C2msDashboardButton

This standard action button displays on both the dashboard and admin sidebars. While creating a dashboard button you can specify all required options in the constructor as follows:

$moduleRightCode – A string (or array) of module right code(s) that may view this button, or null to display for all right codes.
$targetUrl – The URL that the user should be directed to when clicking on the button. It is recommended to use the Yii::app()->createUrl method with the module/controller/action syntax when specifying this option.
$titleText – The text to show with the button. Space is limited, so please choose appropriately.
$sortPriority – The sort for where to show this, with higher values showing later. It is recommended to use on the of the following enumerations:
- C2msDashboard::SORT_HIGHEST
- C2msDashboard::SORT_HIGH
- C2msDashboard::SORT_NORMAL
- C2msDashboard::SORT_LOW
- C2msDashboard::SORT_LOWEST

$iconUrl – The URL of the icon to show with this link (icons do not show in all views). You may use your module’s resources folder to store the icon and retrieve it with a call to your module’s getResourceUrl method. Please make sure to not use the “this” reference in this call, since this class will be instantiated outside of the scope of your module. For example:

Example c2ms-dashboard.php file:

Yii::app()->getModule('YOUR-MODULE-NAME')->getResourceUrl( 'dashboardicon.png' )

1

Yii::app()->getModule('YOUR-MODULE-NAME')->getResourceUrl( 'dashboardicon.png' )
$category – The C2msDashboardCategory to show this button in. Refer to the C2msDashboardCategory documentation for more information.

C2msDashboardHtml

The dashboard HTML shows only on the main dashboard dialog, and displays unprocessed HTML. For any HTML that includes calculated values you should use AjaxHtml instead.

$moduleRightCode – A string (or array) of module right code(s) that may view this component, or null to display for all right codes.
$html – The HTML content you wish to display. Please note, this will be processed for all users regardless of rights access – so if you are calling a dynamic function you must accomodate for that. It is recommended that dynamic content use the AjaxHtml method instead.
$sortPriority – The sort for where to show this, with higher values showing later. It is recommended to use on the of the following enumerations:
- C2msDashboard::SORT_HIGHEST
- C2msDashboard::SORT_HIGH
- C2msDashboard::SORT_NORMAL
- C2msDashboard::SORT_LOW
- C2msDashboard::SORT_LOWEST

$category – The C2msDashboardCategory to show this button in. Refer to the C2msDashboardCategory documentation for more information.

C2msDashboardAjaxHtml

The dashboard HTML shows only on the main dashboard dialog, and displays unprocessed HTML asynchronously after the dashboard loads. This module is appropriate for slow loading content, and will only be called if the user has the correct module right access.

$moduleRightCode – A string (or array) of module right code(s) that may view this component, or null to display for all right codes.
$sourceUrl – The URL that the user should be used to GET the content to show on the dashboard. It is recommended to use the Yii::app()->createUrl method with the module/controller/action syntax when specifying this option. This URL will be invoked by the framework automatically .
$sortPriority – The sort for where to show this, with higher values showing later. It is recommended to use on the of the following enumerations:
- C2msDashboard::SORT_HIGHEST
- C2msDashboard::SORT_HIGH
- C2msDashboard::SORT_NORMAL
- C2msDashboard::SORT_LOW
- C2msDashboard::SORT_LOWEST

$category – The C2msDashboardCategory to show this button in. Refer to the C2msDashboardCategory documentation for more information.

C2msSidebarPanel

Typically C2msSidebarPanels are used to provide context aware edit controls on the admin sidebar for a specific content generator (either a block renderer or a specific module’s controller’s action). The sidebar panel class is a proxy class to allow a Yii CWidget to satisfy the C2msSidebarComponent interface, while also providing automatic permission limiting by module right code as well as filtering by the current page’s block type code or controller.

$moduleRightCode – A string (or array) of module right code(s) that may view this component, or null to display for all right codes.
$blockTypeCode – The block type, or module/controller/action for which this sidebar panel should display. The current page’s block type (e.g. page, event, your-custom-type) will be checked against this value, or in the cases where the content is generated by an application mount point the /module/controller/action path will be compared to this value. Only when an exact match is obtained will this sidebar panel be rendered.
$subjectClassName – The CWidget class to invoke to generate the sidebar panel content (e.g. the widget you are going to write).
$sortPriority – The sort for where to show this, with higher values showing later. It is recommended to use on the of the following enumerations:
- C2msDashboard::SORT_HIGHEST
- C2msDashboard::SORT_HIGH
- C2msDashboard::SORT_NORMAL
- C2msDashboard::SORT_LOW
- C2msDashboard::SORT_LOWEST

C2msDashboardCategory

The admin sidebar and dashboard dialog are split into logical groups by Dashboard Categories. You may choose to pick between several common pre-defined categories or create your own. Most users will want to place content in a pre-defined category. The predefined categories available include:

‘content-publishable’: Primary category ‘Content Creation’, sub-category ‘Publishable Content’. Designed for user created content that must be promoted via the C2ms Promotion system.
‘content-direct’: Primary category ‘Content Creation’, sub-category ‘Direct to Web Content’. Designed for user created content that is NOT promoted via the C2ms Promotion system.
‘promotion’: Primary category ‘Publishing and Promotion’, no sub-category. C2ms Promotion system component.
‘reports’: Primary category ‘Reports’, no sub-category. Designed for runnable reports.
‘linkedtools’: Primary category ‘Linked Tools’, no sub-category. Designed for offsite links or external tools.
‘administration’: Primary category ‘Administration’, no sub-category. Designed for administrative tasks like user management or system settings.
‘developertools’: Primary category ‘Developer Tools’, no sub-category. Reserved for developer tools not intended for typical CMS content users.

To use one of the pre-defined categories C2msDashboardCategory includes a static factory method “PredefinedCategory” to instantiate a category of that type, e.g.

C2msDashboardCategory::PredefinedCategory('content-direct')

1	C2msDashboardCategory::PredefinedCategory('content-direct')

If you wish to create a new custom category, you should use the following constructor options to the C2msDashboardCategory class:

$categoryText – The textual label of this category
$subCategoryText – The textual label of this subcategory, or null if only a primary category.
$sortPriority – The sort for where to show this, with higher values showing later. It is recommended to use on the of the following enumerations:
- C2msDashboard::SORT_HIGHEST
- C2msDashboard::SORT_HIGH
- C2msDashboard::SORT_NORMAL
- C2msDashboard::SORT_LOW
- C2msDashboard::SORT_LOWEST
$sidebarIcon – The full URL path to an icon file to use in the sidebar, or null to use a generic icon.

Filed Under: Developer Guide Tagged With: category, Dashboard, panel, sidebar

C2MS Request Routing

Application mount points

Overview of C2MS Blocks, BlockViews and BlockTypes

C2MS Dashboard Panels

C2msDashboardButton

C2msDashboardHtml

C2msDashboardAjaxHtml

C2msSidebarPanel

C2msDashboardCategory

Recent Posts

Tags