|
Overview |
|
|
|
|
|
Overview |
|
|
|
|
Web parts represent a block of content or combination of content and functionality. They are the basic building blocks of portal engine page templates. Using existing web parts, users with the appropriate permissions (Design website from the Modules- > Content permission matrix) can build or modify the structure of pages directly from a browser by using the CMS Desk -> Content -> Edit -> Design interface. All web parts must be placed into web part zones.
From a developer's point of view, a web part is a user control (ASCX) that inherits from the CMSAbstractWebPart class. You can easily create your own web parts as described in the Developing web parts topic.
The Kentico CMS installation contains many built-in web parts, but sometimes it may be necessary to modify the behaviour, design or functionality of one of them. The Modifying web parts sub-chapter covers several ways how this can be done.
All web parts have the option of using an AJAX UpdatePanel. More information can be found in the AJAX support topic.
Also of interest may be Widgets, which provide functionality similar to web parts, but allow further personalization by users.
Web part management
Web parts can be managed in Site Manager -> Development -> Web parts. Here you can see all web parts organized into categories in a tree structure. Each web part has the following properties on the General tab:
| • | Display name - name of the web part displayed to the users in the administration interface |
| • | Code name - name of the web part used in website code |
| • | Category - here you can choose the category of the web part catalog where the web part will be placed |
| • | Type - type of the web part; the following web part types are available: |
| • | Standard - typical web parts displaying some content |
| • | Data source - do not display any content, only provide data to be displayed by a connected web part |
| • | Filter - can be connected to a data source and enables users to limit the data provided by it |
| • | Placeholder - used for the General -> Layout -> Page placeholder web part; specifies the area where the content of sub-pages should be displayed |
| • | Invisible - are not displayed on the page at all and usually perform some type of background task |
| • | Basic - basic web parts without partial caching and AJAX UpdatePanel support |
| • | File name - contains a relative path to the user control that implements the web part; the path starts from the CMSWebParts folder; it's recommended that you organize the web parts on the disk in the same way as in the categories; example: Search/cmscompletesearchdialog.ascx |
| • | Description - text describing the web part, it will be displayed in the web part catalog |
| • | Thumbnail - image used in the web part catalog |
On the Properties tab, you can define the web part properties and how they appear in the Web part properties configuration dialog.
Each web part has the following default properties that are not displayed on this tab. These properties are created automatically when the web part is defined. However, if you define some of these properties via this tab, you can modify its default behaviour and attributes of the property (e.g. for it not to be displayed, etc.).
Default
| • | Web part control ID - serves as an identifier for the web part. This ID must be unique within the context of each page template. The value of this property may only contain alphanumeric characters and the underscore character ( _ ). |
| • | Web part title - title of the web part displayed on the Design tab of CMS Desk. If empty, the value of the Web part control ID property is used for this purpose. |
| • | Disable view state - indicates if view state should be disabled for the web part. |
| • | Disable macros - if checked, macros contained in the values of the web part's properties will no longer be resolved. |
Visibility
| • | Visible - indicates if the web part should be displayed |
| • | Hide on subpages - indicates if the web part should be hidden on sub-pages |
| • | Show for document types - the list of document type code names separated with a semicolon (;) for which the web part should be displayed (if they are selected as the current document) |
| • | Display to roles - the list of roles the web part should be displayed to |
Web part container
| • | Web part container - container (box) displayed around the web part; this value contains the name of the container defined in Site Manager -> Development -> Web part containers |
| • | Container title - container title displayed if you specify the container; displayed only if the {%ContainerTitle%} macro is used in the code of the container |
| • | Container CSS class - CSS class used for the web part container; applied only if the {%ContainerCSSClass%} macro is used as a value of the Class attribute in the code of the container |
| • | Container custom content - custom content of the web part container; applied only if the {%ContainerCustomContent%} macro is used in the code of the container |
HTML Envelope
| • | Content before - HTML content displayed before the web part; you can use it to display a header or add some encapsulating code, such as <div> or <table> elements for the required layout |
| • | Content after - HTML content displayed after the web part; you can use it to display a footer or close the tags contained in the ContentBefore value, such as </div> or </table> elements |
AJAX
| • | Use update panel - indicates if an AJAX UpdatePanel container is used for the web part |
Time zones
| • | Time zone - time zone used for the web part content |
| • | Custom time zone - optional custom time zone that can be used specifically only for this web part |
Partial caching
| • | Partial cache minutes - sets the number of minutes for which the output HTML code of the web part should remain cached. This process is similar to full‑page caching, but only for the code of the web part specifically. If left empty or set to 0, partial caching will be not be used for the web part. |
| • | Partial cache dependencies - contains a list of cache keys on which the partial cache of the web part depends. When the specified cache items change, the partial cache of the web part is deleted. Each line may only contain a single item. If the Use default cache dependencies box is checked, the default dependencies will be used, which include all possible object changes that could affect the specific web part. |
The structure of a web part, its content before/after sections and a Web part container is the following:
The containers, unlike the ContentBefore and ContentAfter sections, are re-usable and they can contain dynamically inserted values of web part properties.
|
Storing files related to web parts
If your web part consists of several files (such as ASCX controls, images, js scripts, etc.), you should place these files in a subfolder under the folder where your main web part ASCX file is placed. If the code name of the web part is MyWebPart, the subfolder name must be MyWebPart_Files. It will ensure that the additional files are exported/imported correctly when you move your website or when you distribute the web part to other developers. |
Web part documentation
You can add your documentation to the web part on the Documentation tab. If you wish to document particular properties, you need to fill in the Field description on the Properties tab.
You can generate complete web part documentation and print it by going to <website URL>/CMSPages/Dialogs/documentation.aspx?generate=full in your browser. If you want to print it, it's recommended that you use FireFox for correct formatting and page breaking.
Page url: http://devnet.kentico.com/docs/5_5r2/devguide/index.html?web_part_development_overview.htm
