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:

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.

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.