API examples in Kentico CMS 6.0

I am sure that every developer would agree that implementing some custom functionality is easier if you can look at any example of the code which runs a similar action or gives you an idea of how to move forward. That's why we will come in version 6.0 with API examples - we would like to give you an example of how things in Kentico CMS can be coded easily and correctly.

What do we expect developers want from API examples?
1) They want to see the API example code.
2) They want to run the API example and look at the result.
3) They want to modify the API example code and look how the result changed.
4) They want to copy part of the API example and paste it into their custom method.

To meet the requirements mentioned above, we have created the Kentico CMS API examples user interface.


API examples installation
To install Kentico CMS API examples, you will need to ensure that the API examples checkbox is checked in the Custom installation mode of the Kentico CMS Web Installer:



API examples of modules will thus be installed; specifically the API examples source code located in <your web project folder>/CMSAPIExamples and the API examples user interface.


API examples user interface
It will be a pretty new user interface enabling global administrator to run all API examples. It will be accessible from Site manager -> Support tab ->  API examples:



On the left, there is a list of modules (not completed yet). Once you click the given module its API examples will be displayed. There are three panels for each module:

1) Creating and managing
Here are buttons which run the API examples for creating (green buttons), getting and updating (blue buttons) objects included in the selected module.

2) Clean up
Here are buttons which run the API examples for deleting module objects and their dependencies.

3) Code
Syntax-highlighted code of the API example can be displayed here. To do so, you need to click the View code icon, which is next to each API example button. 


Data used by the API examples
All API examples work with their own objects. However, all API examples actions directly affect the database. Typically, the Create action creates the object with the name in format MyNewXXX, e.g. MyNewUser, the Get and Update action gets and updates the MyNewXXX object and the Get and bulk update action gets and bulk updates objects which starts with MyNewXXX.  It means your module data in Kentico CMS shouldn't be influenced by running the API examples. Anyway, it's recommended to run API examples on a dedicated testing Kentico CMS installation.

If the module API example needs to use one of the general objects (site, role, user or document), the following ones are used:
For site - current site
For role - role CMS Desk Administrator
For user - current user
For document - root document from the current site


Running an API example
Because of the dependencies among the module objects, it is recommended to follow the order of the API examples to avoid running an example which expects another object to be created first. The order of the cleanup examples is usually reversed.

E.g.: If you click the Create module button, a module with the name MyNewModule is created. Then if you click the Add module to site button, the MyNewModule module is assigned to the current site. If something goes wrong while running an API example, you can check the error in the event log.

Additionally, you can click the Run all icon to run all Creating and managing API examples of the selected module at once. On the other hand, to remove all created objects of the selected module you can click the Cleanup all icon.




Viewing and modifying API example code
There are several ways to display the code of all API examples:

1) From the API examples user interface
After clicking the View code icon, which is placed next to each API example, the code is displayed in the Code area. It's read-only.

2) From Visual Studio 
For each module there is one file where all its API examples are placed: <web project folder>/CMSAPIExamples/Code/<module folder>/Default.aspx. For each API example there is one method, e.g.: the CreatePermission method for the Create permission action. You can modify that method, compile the page and run the example from the API examples user interface again to see how the behavior changed.



3) From documentation
Each module now has Module internals and API documentation chapter where you can find not only the code of all its API examples but also the module database diagram with related tables and description of all its API classes. See Internals and API chapter of Modules as an example.

This is an early preview of the API examples and the description of what you can expect from them. I believe that API examples and improved modules developer documentation will shorten the time you will spend learning Kentico CMS API and speed up your custom development for Kentico CMS.

Feel free to put your thoughts and opinions bellow the post, we would really appreciate them. Thank you.