About the system
Bitrix Site Manager is the core on which you can build any complex web projects. With Bitrix Site Manager, you do not need any special programming or web design knowledge and skills.
Bitrix Site Manager installs to the root directory of a remote server. An administrator can manage sites via the web interface. To function properly, the server configuration should meet the following minimum requirements:
- Apache web server version 1.3 or higher;
- PHP version 5.0.0 or higher;
- MySQL version 4.1.11 or higher / Oracle 10g or MSSQL 2000 or higher;
- 10 Mb of free disk space (for the Update System).
Note the following.
- The MSSQL edition requires that the ODBC support is installed and properly configured.
- Before installing the Oracle version:
- ensure that the Oracle 9 (or higher) client is installed;
- ensure the OCI8 library (php_oci8.dll) exists;
- create a new user.
Bitrix Site Manager has a modular structure. Each module controls its own elements and parameters which, in aggregate, form the site framework: the structure and content, forums, advertising, subscriptions and mailing lists, user management, statistics etc.
|Name of folder in the section:
||Bitrix Site Manager
||Manages banners on site and advertiser contracts.
||Web Store Site
||Turnkey e-Store solution that includes visually attractive templates and functionality to make your online sales and overall business more efficient.
||Turnkey community solution with social networking elements like User Profiles, Activity stream, Forums, Blogs, Groups and Instant Messenger.
||Corporate Service Site
||Turnkey solution which allows you to deploy a modern website with convenient navigation that features information about your company and the services it provides.
||Municipal InfoPortal Site
||Turnkey solution that contains a well-developed template for supporting an information portal with various types of news feeds, headlines, announcements, blogs, forums, photo galleries, surveys, banners and other elements needed necessary for municipalities or local media outlets.
||Personal Site Site
||Turnkey solution to create a Personal Website or a Blog to share your thoughts, photos or music with your firends, relatives or colleagues.
||Bitrix Cloud Service
||Provides backup storage, CDN and cloud storage features.
||A module to create manage and run business processes.
||Business Processes Designer
||A module to design, create and edit business processes.
||Allows creation and management of blogs.
||Enables personal, group and company calendars to keep track of all the events in your company and coordinate schedules with colleagues.
||The Commercial Catalog module is used to create shopping catalogs for goods and services with prices, and price adjustments (discounts); it also features data import and export.
||This module supports cloud storage of files (Google Storage, Amazon S3, Windows Azure Storage, and OpenStack).
||The Web Cluster module allows the distributed hosting of a single site on multiple servers.
||Compresses transferred HTML data for better performance.
||This module lets you manage several web resources simultaneously and allows you to synchronize data flows between the websites.
||Provides CRM services.
||The Currencies module provides easy management of currencies and currency rates on the site.
||The DAV module supports calendar and contact sharing with external services and applications.
||Enables company personnel to co-operate with external partners.
||This module manages site content, structure, menus and user access permissions.
||This module manages web forms and allows storing and filtering of resulting data.
||Allows creation and management of forums.
||Highload Information Blocks
||This module is used to handle arbitrary data in high load conditions.
||The Information Blocks module manages and stores information of various kinds, e.g. news, vacancies, and product lists.
||The Idea Management service capitalizes on the creative potential of all the employees of the company (site visitors).
||Provides support for instant messaging and notification services.
||This module includes intranet functionality such as company structure, absences chart, employee changes, etc.
||Connector module for AD/LDAP simplifies integration of Bitrix products into the existing IT-infrastructure of a modern company.
||This module allows you to create an unlimited number of online training courses or tests for your employees (website visitors).
||This module helps you manage record-based data right in the front-end of your website. Suppliers' directories, product catalogs, expenses, etc.
||The Mail module is designed to receive e-mail messages, filter, and perform other specified actions.
||The Kernel module enables the general functioning of the system, integration among the modules, and supports the creation and management of an unlimited number of sites (limited by license).
||Meetings and Briefings
||Module for planning and managing meetings and meeting agenda points.
||A mobile application for use with the portal.
||Module to monitor site performance parameters.
||This module is used to create photo galleries with bulk image upload.
||Push and Pull
||This module supports push notifications for the IM and conversations to mobile clients.
||A module to create and generate reports for objects (e.g. tasks, leads, deals, orders, products).
||Provides e-commerce functionality.
||Provides scalability features and scalability management capabilities.
||Search module enables site indexing and search.
||The module combines technical and organizational measures that help you combat malicious programs and unauthorized access attempts.
||Search Engine Optimization
||Offers various SEO tools for your site.
||Adds the social network feature (personal pages, blogs, user profiles, friends, ban list, built-in instant messenger, etc.) to your site.
||Social Website Integration
||Integration with popular social networks.
||This module helps you analyze online and offline advertising campaigns, estimate expenses per advertising channel, calculate ROI, analyze the website structure and content, obtain extensive information on visitors, etc.
||The Newsletter module is used for creating mailing lists and sending newsletters.
||The HelpDesk module helps you organize and manage your technical support services.
||Task management module.
||Working Time Management
||A module to track and control working time of users.
||The Localization module lets you localize the user interface of the system for any number of languages.
||Polls and Surveys
||This module adds visitor poll and survey functionality to the site.
||Adds VoxImplant cloud platform support to the Web Messenger module.
||This module allows organization of document libraries for general use, collaboration, and personal storage.
||Provides functions to implement and use web services and SOAP.
||Provides Wiki features for your website.
||The Workflow module is designed for staged processing of static and dynamic data placed on your website, including webpages.
||External data import
||Provides tools for importing data from external sources.
||The XMPP server module allows users of the intranet to send and receive IM messages and indicate online status via a Jabber client.
- the functionality of this module is limited in the Bitrix24 intranet, and incorporated for expanded CRM functionality.
The number of modules in the system depends on the product edition purchased.
The comparison table (at the Bitrix Inc. web site) clearly shows the functional peculiarities of different Bitrix Site Manager editions.
In general, system modules function as independent units. However, in some cases modules can contribute to each other. For example:
- The Commercial Catalog module extends the Information Blocks module by adding multiple conditional prices, introducing mark-ups and discounts etc.
- The Workflow module empowers the system with teamwork functions which can be useful for handling elements of the Information Blocks and Site Explorer modules.
After installation, you can view the list of available modules in the Control Panel: Settings -> System Settings -> Modules.
This table shows the description of each module, the number of installed version, the date of the last update, and the current status:
- Installed - the module is installed; its functions are available and can be used;
- Not installed - the module is not installed; its functions are not available.
To free disk space, you can uninstall unused modules. This does not delete the module package; you can always install the module again if required. The Install and Remove buttons beside each module adds the respective module to or removes it from the system.
If a module is installed, it adds the corresponding section and item to the left menu of the Control Panel.
Some modules may add their items dynamically:
Examples of dynamic load:
- the Information Blocks module loads the list of information block types;
- the Web forms module loads the list of forms;
- the Site Explorer module loads the folder tree.
User permissions can be assigned in such a way that some system function or area will become unavailable to a user. You can control user permissions to the system modules on the settings page of each module:
Basic notions and terms
The figure below illustrates the system infrastructure.
Before you continue learning, you are strongly recommended to become familiar with the basic terms, notions and system elements.
System instance is a Bitrix Site manager installation including the source code, a single copy of the database tables, and the documentation.
Site is a piece of information pertaining to a system instance. Each site is assigned a unique identifier which is used to identify and classify system objects (information blocks, web forms, forums, site templates, e-mail templates etc.) by sites. By identifying and classifying the objects, the system is able to manipulate and display them using the previously defined design, interface language, according to a domain name or folder. The report table (Settings -> System settings -> Sites -> List of sites) show all sites in the system.
Site template defines the site design, its look and feel. A site can use an unlimited number of design templates. Using templates empowers designers to customize the web site appearance and allows to switch between designs depending on the desired conditions.
Unlimited sites: the unlimited site license entitles the owner to create as many sites as needed. These sites can run on a single system instance sharing a single database copy.
Unlimited license: the unlimited license entitles the owner to create the limitless number of web projects using a single license. In fact, this means that the number of system instances (in other words: installations) is unlimited. Each of such web projects is allowed to contain 2 sites. Licenses for extra sites for each web project are to be purchased separately. The unlimited license never permits reselling the system instances.
Public section is the information displayed to the site visitors (compare to Control Panel).
Control Panel (administration section) is a special site area containing the system administration interface. Site administrators use the Control Panel to manage the system modules, site structure and content; users, visitors etc.
API (SDK) - each system module exposes a set of high-level programming functions for handling data in the public section, and classes with low-level methods for more sophisticated operations. You can find the detailed information on the system API here.
Visual components can be used to add common functions to your pages. Each component is a logically complete code portion containing special variables by which a component can be controlled from the visual interface.
You can easily change parameters of the component, or even edit its source code. For example, the Newsfeed component allows to specify the number of news per page, define sort order etc.
Using visual components is the most preferred way to display information in the public section, as well as in the control panel.
Update System - with the unique SiteUpdate technology, you can:
- download and install system updates and new modules;
- download and install languages files and new languages;
- obtain and register licenses for extra sites.
The data is downloaded from the Bitrix web site via the Control Panel web interface. The update process modifies the system kernel files only (files in /bitrix/modules/
). The public section is never modified thus ensuring user information is safe and sound. During the update process, the update system:
- automatically acquires the license key;
- checks for new updates;
- displays the list of available updates and invites a user to choose the desired ones;
- after the download is complete, a user can install the downloaded updates.
All updates are compressed before transferring, thus increasing the download speed.
Multilanguage interface is one of the Bitrix Site Manager features. It is implemented by means of language files storing phrases translated into various languages. Language files are used by:
- the Control Panel interface;
- error messages;
- visual components;
- standard site template areas, etc.
The system connects the required language files according to the current language, which results in displaying messages and phrases in the language selected by a user. You can switch languages by clicking the control panel toolbar buttons.
User is a site visitor related to a certain user group (or groups). A user can access the site resources in compliance with the permissions granted to the respective user group. You can manage user groups and users in the Control Panel: Settings -> Manage users -> User list.
User group is a se t of site users who are granted the required permissions to access and manage the site resources. For example, the Moderator user group members can read and edit the forum messages.
You can manage user groups and users in the Control Panel: Settings -> Manage users -> User groups.
Registration is done by a site visitor to create a user account by providing the required information. The registration data (login and password) specified by the visitor at the registration time (or issued automatically, e.g. when using a simplified order placing method), can be used later to authorise in the system. Upon registration, the visitor is added to a user group, and obtains permissions to access the site resources according to permissions specified for the user group.
Authorisation – providing the registration data (login and password) by a user by entering them in a special form. Authorisation allows the user to access specific information and carry out actions that are approved for their user group.
You can find more information about the system basics on the Bitrix, Inc. web site.
The public section is the area for a content manager to exhibit information and other resources to the public.
The public section is, essentially, what a visitor sees when they browse for your website.
To manage the website information, an Administration Toolbar (also known as the Control Panel toolbar) exists which becomes available on top of the screen upon user authorization.
The administration toolbar commands (buttons) depend on the contents of a currently visible page and the current user permissions. The common visitors or users without any site management permissions do not see the toolbar. Usually, the content managers are not allowed to enjoy the full set of the management commands. However, giving administration privileges to users is up to the website administrator.
This lesson discusses the fully functional toolbar available to a user with administrator permissions.
Bitrix Site Manager has made a long way since it was first introduced, and the administration toolbar has evolved beyond recognition. At present, you may encounter the old, four tabbed version of the bar, and the new variant with the two tabs. The next lessons describes the both version.
Types of Information
The public section can display static or dynamic information.
Static information remains unchanged with time. For example, advertisements, history of a company, contact information etc. This type of information can be created and edited by users permitted to edit the site pages.
Dynamic information may eventually change. For example:
- the list of latest company news;
- catalogue of products and services;
- photo gallery;
- field containing a random photo;
- banners, etc.
Dynamic information is displayed using visual components that are placed and customised when editing a page in the visual HTML editor.
Also, dynamic information can be displayed by running a script in the page code.
The Amber Public Interface (since version 9.5)
The administration, or Control Panel toolbar has the two modes:
- Site: this mode is primarily for the content managers, or for performing tasks that can be done when in the public section only;
- Control Panel: this is the system administration area providing fully functional control over the entire web project.
The Control Panel functions are discussed in detail in the corresponding lessons.
The Control Panel Toolbar
The toolbar is always on top on the screen and visible to only the authorized users having sufficient permissions. Depending on a current user’s permissions, the toolbar may show or hide the respective commands which are allowed or disallowed for the user.
The toolbar can be pinned on top so it don’t scroll with the page contents by clicking the button
Among other commands, the toolbar has some special features:
- the update notifier which is shown when there are available system updates;
- the currently authorized user name which, when clicked, opens the user profile for editing.
The Menu Button
This button provides a shortcut to any desired Control Panel function.
The Site Tab
This tab renders the site content just as the visitors see it, plus providing the website content management functions.
|The Site tab commands
| ||New Page button ||Creates a new page using the new page wizard. |
|New Page menu||Opens a menu showing the new page templates. Select a template and follow the wizard instructions. |
|New Section button ||Creates a new section using the new section wizard. |
|New Section menu ||Shows a selection of the new section templates. Select a template and follow the wizard instructions. |
|Edit Page button ||Edits a currently open page in the visual editor dialog. |
|Edit Page menu ||Opens a menu containing commands to edit a page in simple or workflow mode; view the page edit log; edit the page properties and access permissions. |
|Edit Section button ||Opens a form to change the section properties. |
|Edit Section menu ||Opens a menu containing the section management commands. |
| ||Menu button ||Brings up the menu editor dialog box. The drop-down button allows to select a menu for editing, or create a new menu. |
| ||Structure button ||Opens the Structure dialog box in which you can add, edit, move or delete pages and section as well as their properties. |
| ||SEO button ||Brings up a selection of the search engine optimization tools. |
|Refresh Cache button ||Refreshes the cached data for a current page. |
|Refresh Cache menu ||Shows commands to refresh the cache of a current page or components in it; or disable caching for this page completely. |
| ||Components button ||Shows a menu in which you can select a component to edit its properties. This button is available when in edit mode only. |
| ||Site Template button ||Opens a form to edit the site styles or the site template styles. |
| ||Debug button ||Enables the display of the site engine statistics. Using the drop-down menu, you can select to show the database query statistics, the include area statistics or the compression statistics. |
| ||Statistics button ||Opens a menu to select the website statistics: the page views or the page clicks. |
| ||Translation button ||Shows the localization files used by a current page. This button is visible if the corresponding option is checked in the Localization module settings. |
| ||Reindex button ||This button is shows for pages containing one or more of any of the social networking components. When clicked, re-indexes the components’ data. |
|Site Wizard button ||Runs a wizard to configure the solution currently in use. |
|Site Wizard menu ||Shows a menu containing the wizards available for the current solution. Each solution is in possession of the own set of wizards. |
|Test a New Solution button ||Selects a new solution for installation. |
|Test a New Solution menu ||Shows a menu containing commands to install a solution; open another site or remove this button from the toolbar. |
| ||Edit Mode toggle ||Enables or disables the website context edit mode. When enabled, you can highlight any text block by hovering the mouse pointer over it and edit it by using the popup toolbars. |
The Control Panel Tab
This tab , when clicked, switches the website to the system administration area.
The Update Notifier
The update notifier (the link: )shows up automatically as soon as the system detects that there are new updates available which are checked for periodically as specified in the kernel module settings. Clicking this link will open the SiteUpdate form.
The Authorized User Name Indicator
The authorized user name is a link which, when clicked, opens the user profile for editing. The Logout link ends the authorized session.
The Toolbar In Minimized State
The toolbar, when collapsed, saves more visible screen space. The collapsed mode, however, retains some management functions. The Menu button can be used to access the Control Panel pages; the update notifier is operational; the Edit Mode toggle is available.
In edit mode, a user can configure parameters of the components existing in a current page or in the site template, and the data rendered by these components.
If not in edit mode yet, you can turn it on by clicking on the mode toggle:
Now, move the mouse pointer over the webpage surface. Whenever you hover the pointer over an area containing editable data or a configurable component, such area will be highlighted with a red frame and a context toolbar will appear. Consider an example of the Menu component, whose red frame and the toolbar became visible because a user hovers the mouse pointer over it:
If a component existing in the template or the page work area does not print any data on a current page (for example, the navigation chain may be set to not display on the main page), the component will give a positive indication of such behavior by rendering the icon .
The component menu may include typical buttons common to general information management commands, as well as the component specific items. For example, the Catalog component show the following toolbar:
The following table summarizes the common component toolbar areas.
The system is capable of canceling the most recent action performed by a user.
Whenever a user undertakes an action that could change the website content, a yellow undo bar will appear below the Control Panel toolbar:
The undo bar shows the description of an action a user has done, and a link allowing to undo such an action. If no undo is required, close the bar by clicking the close icon .
This chapter discusses on the most important parts of the system user interface providing full control over the website’s content and configuration.
An authorized user can access the administration area (Control Panel) by clicking the Control Panel tab.
The user interface of the Bitrix Site Manager administration toolbar is logically divided in special areas thereby providing access to system functions.
The Control Panel interface is built in such a way that the system functions that a user does not require at the moment can be hidden, while bringing the wanted functionality to the foreground. The user interface, being managed in such way, ensures that it remains legible and not overloaded.
The figure below highlight the main areas of the Control Panel user interface.
Interface layout - view movie (Flash)
The Control Panel interface is built in such a way that the system functions that a user does not require at the moment can be hidden, while bringing the wanted functionality to the foreground.
The user interface, being managed in such way, ensures that it remains legible and not overloaded.
Control panel toolbar
The Amber user interface (since version 9.5):
The administration control toolbar contains general commands a user may need to manage the site.
|Opens a dynamic menu for fast access to the Control Panel forms. |
| ||This tab, when clicked, closes the currently active Control Panel form and opens the website’s public section. |
|This tab opens the Conrol Panel’s administrations area. If a user has once switched to the public section from Control Panel previously during a current authorized session, clicking this tab will open the most recently accessed Control Panel form. |
|Shows the available disk space. This option can be enabled in the Kernel module settings. |
|Opens the profile editor for the currently logged in user.
The Logout link ends the authorized session.
| ||If checked, fixes the Control Panel toolbar on top of the screen so it does not scroll with the page contents. |
| ||Adds a current Control Panel form to the favorites list. The form retains all the filter values if any applied. |
|Opens the settings form for the module whose form is currently active. For example, if you are in any form of the Site Explorer module, this button opens the Site Explorer module settings form. |
| ||Opens the context help on a currently active Control Panel form. |
|Opens the update system main page. |
If you choose to use autocheck for updates in the Kernel module settings, this button becomes red and a popup notification message will show if there are updates available.
| ||Switches Control Panel to one of the installed languages. |
|Opens the list of the current user’s uncompleted tasks, if there are any. |
This button is only available if the Business Processes module is installed.
Function selector and content access area
This panel is used to choose an isolated set of functions or entities relevant to a specific
functional part of the system. Depending on whether a specific module is installed or not, the set
of selector functions may vary.
- The Content set offers tools which one may require to manage information blocks, site structure (files and folders), or set up and control the document workflow.
- The Services function set depends on the presence of modules in the system. The full set of functions allows to manage polls, web forms, advertisement, technical support system, forums and mail system. Custom user modules are also added to this function set.
- The e-Store function set contains the commercial catalogue and the web shop management tools. This function set is available if only these modules are installed in the system.
- The Web Analytics section is entirely dedicated to functions responsible for collecting, processing and displaying the site statistics. This section is only available if the Statistics module is installed.
- The Settings section contains tools which can be used to manage users, currencies, templates, obtain system updates, or adjust other parameters of the system and sites. This section also offers the Tools command set containing the database diagnostics, repair and back-up options.
Functions, content and structure access area
The menu of this panel depends on the function set selected in the function selector. For example, selecting the Content set displays the following menu:
By selecting items in the tree menu, you can directly access the corresponding functions. This causes the work area to offer user interface for using and manipulating these functions.
Main work area
The work area is the main interface part in which you perform most operations:
- view entities composing the site content (e.g. information block, banners etc.);
- add content;
- create or delete files and folders;
- customize menu etc.
The system offers two main types of user interface forms to fulfil these operations:
- report forms. Report forms are used to display (and view) elements in tables, or, is some special cases (statistics forms) - in the form of graphs and diagrams;
- editing forms. You use these forms to add or edit the content entities, as well as customise both system and per-module settings.
Report forms are opened whenever you select an item in the tree menu of the function, content and structure access area. Report forms display the essential information about entities included in the report. For example, if you select the Banners item in the Advertising section, the system returns with a thorough report about all existing banners:
The following sections describe interface parts common to all report forms.
A filter, in its core, is essentially a means to search and select data to be displayed in tables of the report forms. By providing search criteria in the filter, you can find and display only the required information (usually a selection of database records).
A typical filter looks as follows:
The Show filter button displays the filter and all its criteria. Clicking the Hide filter button minimises the filter leaving only the filter toolbar and (optionally) the default condition marked with bold typeface. The More filters button opens a pop-up menu in which you can choose individual search conditions to be included in the filter.
Filter fields having a question mark on the side (?) allow using complex logic in filter.
Using filters - view movie (Flash)
You will find context bars on both report and editing forms. If an active form allows any action to be performed on the displayed elements, the context bar can be found below the filter.
For example, the Bookstore: Information Blocks report form displays the following context bar:
By clicking the buttons of this command bar, you can:
- add a new information block;
- exports the list of information blocks to the Microsoft Excel format;
- customise the table columns, set the default sort order etc.
The system uses tables to group and display information. Despite the fact that there are many different types of tables in the system, all they have common fields.
Checkbox columns are used to select one or more elements for applying the desired action to them. Check the box in the table head to select all elements in the table.
You can perform operations on the selected elements by choosing the desired command in the action toolbar below table:
Please pay special attention to the Quick edit command. It allows to modify the most important, frequently used properties of the selected elements simultaneously, without leaving the current report form (i.e. without having to open an editing form).
For example, you can mark information blocks Reviews, Books, and Authors in the Bookstore: Information Blocks form:
After you click the Quick edit button, editable values of the selected elements will be displayed as input fields:
After you have completed editing, click the Save button to apply changes.
The Action menu column () contains buttons , each of which, being clicked, opens a context menu containing actions available to be performed on a table element. For example, elements of the Bookstore: Information Blocks form table offer the following actions:
Using lists - view movie (Flash)
The editing forms are used to modify elements comprising the site content, or edit
parameters of the system. For example, selecting the Edit command of the information block
action menu opens an information block editing form.
Since site elements (or module settings forms) may include a lot of editable properties, some
editing forms are implemented using the so-called property sheets. With their advent,
property sheets are widely used to enhance user interface, and it's no wonder because property
sheets allow to divide numerous properties in logical groups (pages) thus making user
interface easy to handle and comprehensive. Usually, properties are grouped in such a way that first
property pages in a sheet contain the most frequently used properties, while other pages hold all
The figure below illustrates a part of the information block property sheet form.
For short, the system help section uses the term tab as a synonym of a property page.
Integrating Bitrix products into the corporate information system usually requires distributing team members’ permissions to access the Bitrix Framework resources and management.
A common solution of this problem is creating user groups with different access permissions applied to them and further adding users to these groups. In this case, an administrator may face a need to transfer the existing corporate user groups to the Bitrix system to allow users to assess and manage the corporate site resources. This incurs doubling actions required to change access permissions or add a new user to both the corporate network and Bitrix: the administrator has to create or edit a user profile in the corporate system as well as in the Bitrix system.
The AD/LDAP module is developed especially for use with Bitrix products permits mapping corporate network user groups to those of the Bitrix system. This allows to manage user groups of the corporate information system in the centralized fashion.
The AD/LDAP module has been developed with respect to LDAP (Lightweight Directory Access Protocol) and AD (Active Directory) standards.
The AD/LDAP module is built on the concept of storing data as records containing a set of attributes; these records are stored in a hierarchical database. The following figure illustrates how the user group information is stored on the LDAP/AD server:
Using this structure to store user data enables the AD/LDAP module to assign corporate user groups to the site user groups.
The assignment rules are specified in a special Assignment Table in the site administrative section. The assignment allows user groups of the site and the corporate network to have different names. For example, a corporate network user group Techsupport can be mapped to a site user group Techsupport stuff. Having this assignment made, the administrator enables the corporate network techsupport members to provide consultancy on the site.
The corporate user groups are given permissions to access the corporate network resources. The site user groups have permissions to access the site resources. For example, the Techsupport group users can access the corporate mail server; while the Techsupport stuff group users can access the Helpdesk module of the site.
According to this example, a Techsupport corporate user will be automatically added to the site Techsupport stuff user group upon successful authorization on the site. After that, the system automatically creates the user account stored on the corporate server.
A user can assigned to one or more user groups. The system may contain user groups not mapped to those of the corporate network. The administrator has to add users to such groups manually. All changes made to the user profile within the corporate server will be automatically transferred to the CMS user profile at the time of subsequent authorization. In this case, only the user groups mapped to those of the corporate network are updated.
The AD/LDAP module allows to:
- integrate Bitrix Site Manager in the corporate network;
- map the corporate network user groups to the site user groups;
- automatically create a user profile as per the Assignment Table upon successful registration. (The system creates the profile using data requested from the corporate server database);
- centrally manage user profiles via the corporate server.
The AD/LDAP module supports NTLM authentication. You will need an IIS web server, or Apache with mod_ntlm or mod_auth_sspi installed to use this option.
How the module functions
A common AD/LDAP module operation is as follows.
- A user opens the site and authorises. This implies typing the login and password used to authorise in the corporate network.
- The system connects to the server specified in the AD/LDAP module settings and verifies whether a user with the supplied credentials exist in the corporate server database:
- if no user with the supplied credentials exists in the corporate network, the system searches for this user in the Bitrix Site Manager database. If the user still cannot be found, the system declines authorization;
- if the user is found, the system determines the corporate network user group for this user. After that, the system searches for the site user group using the Assignment Table.
- The system verifies whether the user profile exists:
- if the user profile is not found, the system attempts to obtain the user data from the corporate server and then creates a new profile;
- if the user profile exists (which means a user had previously been authorised), the system checks whether any change has been made to the user profile on the corporate server. If so, the Bitrix user profile becomes updated to reflect changes.
- The user is granted permission to access the site resources and becomes authorised. The user permissions are defines as per his user group settings.
: a site user who is a member of any group registered in the Assignment Table may be deleted from the corporate network user list. In this case, if a user attempts to authorise on the site, the authorisation attempt will fail. At the same time, the user profile is still stored in the Bitrix database.
To allow a user authorise on the site via the common interface, enable the internal authorisation check. To do so, set the value of Authorisation type to "internal check" and then update the user credentials (login and password).
Note that if an AD tree has N domains (e.g. OD1, OD2… each for an individual department) and these domains have groups with duplicate names, the Assignment Table will display all of the groups effectively showing duplicate names N times. To avoid confusion, change the Group identifier attribute in the AD/LDAP server settings to something you can change without affecting the whole set-up, for example DistinguishedName (DN). As a result, the distinguished names will be shown instead of the group names.
To edit the parameters of the AD/LDAP module, open the settings form: Settings > System Settings > Module Settings > AD/LDAP AD/LDAP connector.
- Enter the e-mail address to be used for all users who did not provide one (Default user email address (if not specified)).
- Check the Use NTLM authorization box if required.
Note: to use NTLM authentication, you will have to configure your web server for use with NTLM authentication and specify the NTLM authentication domains in the AD server parameters.
- If your configuration is set to use a non-standard variable to store the user login string, set the variable name in the PHP variable to contain NTLM user login (usually it is REMOTE_USER) parameter.
However, you should keep in mind that the other system modules is using the default variable REMOTE_USER.
Note: REMOTE_USER stores the value as login or domain\login. A user is authenticated on the web server directly without intermediate passwords or hash values.
- If your local network has multiple LDAP servers, select the authenticating server in the Default domain server field.
- The Create new users upon the first successful login option, when employed with the AD protocol, can be used to restrict website access to only the existing users. For example, you can create accounts for the required users and uncheck this option. As a result, only these users will be able to login. This option cannot be used with NTLM authentication.
Keep in mind that a computer running the Apache web server must be included in the Windows domain.
Note: Internet Explorer users may encounter irregular problems using the Control Panel toolbar buttons. To fix this issue, add the following line to the root .htaccess:
Adding users to departments on an AD server
When creating the company structure on an AD server, the following information has to be added: the department hierarchy; the heads of the departments; the users (employees) added to their respective departments. All this data is copied automatically when importing users to Bitrix Framework. As a quick and dirty way of creating data on the AD server, you can add all the AD users to a special shadow department.
The following two user properties are used to define the company structure:
- department: a symbolic name of a department to which the user belongs;
- manager: a DN (Distinguished Name) of the user’s supervisor.
The company hierarchy is created using the following rules.
- If a supervisor (manager) belongs to some other department, this implicitly defines the department disposition: the manager's department is higher than the user’s department. The user is then considered as a supervisor of his or her department.
- If the manager belongs to the same department, then the user is not the department’s supervisor. Notice that all the department’s subordinates should have the same manager.
- If no department is specified, but the manager is not empty, the user is implicitly added to the same department as the manager. This rule applies to the manager and his or her managers recursively.
- If the department is specified, but the manager is empty, then this department belongs to the root of the hierarchy, and the user is the department’s manager.
- If both the department and the manager are empty, the user is added to the default department specified in the module settings.
Registering a server
You will create an AD/LDAP server record in the administrative area (Control Panel) by specifying the required server data and user group mapping.
Each record regulates access to a folder tree root. If the corporate network user groups are stored on several servers or in several databases on a single server, you should create a separate record for each storage point.
- Open Active Directory / LDAP server settings (Settings > AD/LDAP).
- Click Add to open the new record creation form.
- The Server tab is used to specify information about the corporate server as well as the database connection settings. You have to ask your system administrator for the server data.
- Active: if this box is checked, this record is included in the user profile lookup when a user attempts to authorise.
- Name: the name of the record to be created as it will be shown in lists.
- Description: type here the server description.
- NTLM Authorization Domain: specifies the AD/LDAP server on which a user is authenticated. This field is also used for unattended NTLM authentication. The server is specified as domain\login.
- Server:port: the IP address and the port of a corporate server hosting the user group database. The port 389 is the technology standard to access an LDAP server.
- Administrative login: login for administrative access to the server.
- Administrative password: password for administrative access to the server.
- Test connection: click this button after you have specified all required information, to verify the connection.
This will try to establish a trial connection to the server. If the check succeeds, the server should return a list of available tree roots. If the check fails, the page will display the error description in red.
- Tree root (base DN): this field is used to select the catalogue tree root to be used for the user profile lookup when authorising.
- The Field Mapping group defines parameters of the user profiles stored on the server.
The controls of this group are initialised with the standard values for LDAP or AD servers.
- You can select the server type by clicking on the corresponding link in the section title.
- If the corporate server overrides standard settings, the values in this group should be altered to reflect the server settings.
To create more user field to attribute mapping entries, click the [add…] link. For an LDAP server, fill in at least the required fields (first and last names, e-mail address etc.) that will be continuously synchronized to AD. Other fields can be imported by employing the user import option on the Field Mapping tab.
When synchronizing, each of the mapped fields will be checked for changes and changed on the website end (that is, in Bitrix Site Manager). In practice it means that if a user has changed one or more of the mapped fields, they will be restored to the original values.
It is recommended that you create as many field mapping entries as possible when importing users for the first time, and delete redundant mappings once the import procedure is complete.
Company Departments and Structure
This group includes company structure import configuration options.
The User Group Mapping section is used to load the corporate user groups and the site user groups in the Assignment Table and specify group mapping.
- Check the Import Company Structure From AD box if the company structure needs to be updated from AD each time the website user data is synchronized to intranet network records.
- Use the Import Structure From AD Server to This Portal Department option if your company includes multiple offices each running a private intranet network server. Create a department for each office and select it in the server settings.
Otherwise, the company structure will be imported to the root of the department tree.
If a department on an AD record already exists in the tree on the website end, the latter will be used instead of those on AD.
- The Assign Users To Default Department If Undefined In Active Directory option, if checked, specifies to add orphan users to the website structure. Otherwise, such users are skipped.
- Specify the Default Department to which the orphan users will be added. The default department name is only used if the previous option is enabled.
Click Refresh Group List to add more user groups to the table. This will also verify parameters specifies in other sections.
After the list is refreshed, this section will display the Assignment Table:
The Synchronization tab includes options allowing an administrator to schedule unattended user database update.
- Group on the remote server. In the Group on the remote server column, select a corporate network user group.
- Local group. In the Local group, select a site user group that would match the selected corporate network user group. Thus, a single table row contains the corporate network user group and the matching site user group.
- Delete. To delete a row from the table, check the Delete box and click Apply.
- More. You can add more rows to the table by clicking More.
- If you need to skip one or more user groups, specify their names in the Exclude the following groups from import field. These groups will not be imported even if they are selected in Group on the remote server column.
To add users of a particular user group to multiple website user groups, select this group in Group on the remote server column as many times as required and map them to the destination local user groups.
If the same local user group is selected for multiple different remote user groups, only the users existing in all remote groups will be added to the local user group.
Click Save to save changes and go back to the list of servers.
Saving a record adds it to the list of servers on the page Active Directory/LDAP server settings.
- Check the Perform full synchronization box to enable the synchronization options.
- Enter the required synchronization period.
- If required, enter a custom LDAP attribute name. It will be used to log updates.
To edit or delete a record, select the appropriate item in the action menu of a required record (button ).
The system supports NTLM authorization by default by including the mod_auth_sspi module in the Apache web server installation. If you do not use Bitrix Environment, or NTLM authorization does not function correctly or at all, do the following.
- Ensure that mod_auth_sspi is installed.
a. If you’re using Bitrix Environment, this module is installed by default. Make sure the following lines exist in .htaccess:
AuthName "My Intranet"
If they are commented out, uncomment them. If you cannot find these directives at all, add them to .htaccess.
b. If you are not using Bitrix Environment, download the mod_auth_sspi module here and put it to the /apache/modules/ directory.
Add the following line to the httpd.conf file:
LoadModule sspi_auth_module modules/mod_auth_sspi.so
Add these lines to .htaccess:
AuthName "My Intranet"
- Use phpinfo to find the value of the
$_SERVER['REMOTE_USER'] variable. Set the “NTLM Authorization Domain” parameter to this value in the AD/LDAP server settings.
Another way to get the
REMOTE_USER value is to create a page containing a single line:
<? echo $_SERVER['REMOTE_USER']; ?>
and open it in a web browser.
- Check the AD/LDAP module settings: NTLM authorization should be enabled (the "Use NTLM authorization" parameter).
Finally, open Control Panel > Settings > AD/LDAP and make sure the AD/LDAP server parameters are correct.
Accessing Extranet without NTLM
To enable access to the /extranet/ folder without NTLM authorization:
- Add the following lines to .htaccess:
AuthName "My Intranet"
- Add the line to /extranet/.htaccess and /bitrix/.htaccess:
- Add the line to /bitrix/admin/.htaccess:
These directives will set all the public section folders and Control Panel pages to require authorization via NTLM, except for the /extranet/ folder.
Importing Users from LDAP Diectory
For massive user creation, use the Import Users form (Settings > Users > Import Users).
A detailed description of creating users from LDAP can be found in the Import from LDAP Directory lesson of this course.
A site is collection of files (pages) with information, sections and other files that are linked together.
A site section is a directory (folder) in the server file system containing files related to a given section (pages, images, include areas).
A distinctive feature of Bitrix Site Manager is the multisite support which allows to create more than one site using a single copy (license) of the product (the license terms stipulate that all sites must share a single installation of the system kernel and database). Each site can have its private domain name, design, interface language and content.
Technically, the following two multisiting configuration modes are available.
- Method 1. The first mode presumes the use of a single Apache web server. Each site resides in a separate subdirectory of the common directory, for example:
- Method 2. Each site runs on a separate Apache web server instance (or a separate virtual server). This method requires that you make special adjustments to both web server and the installed software.
You will find the detailed explanation of the configuration modes in the help section.
Managing sites in the control panel
You can manage your sites with the List of sites form:
Settings –> System settings –> Sites –> List of sites.
Each site running under control of the system is represented by a row in the report table.
To create a new site, open the site creation form by clicking Add site on the context bar. In the form, specify the required parameters of the new site.
You can open a form in which you can edit parameters of an existing site by selecting the Modify item in the action menu:
Configuring site display settings
The display of the site public section is defined by the following parameters:
- domain name;
- interface language;
- national and regional settings (date, time, currency etc.);
- information content.
All these parameters (apart from content and currency) are defined in the site editing (creation) form:
Settings –> System settings –> Sites –> List of sites.
The site domain name is specified in the Domain name field of the Parameters to identify a site in the public section group:
One or more domain names can be assigned to a single site.
Public section language. National and regional settings
Each site has an individual set of language and regional parameters which affects the display of information in the public section. The Parameters group of the site editing form provides interface to select the language in which text messages will be rendered in the public section, as well as:
- short date format;
- full date format (includes time);
- page encoding.
You will find the date format description and the code page names in the system help section.
Bitrix Site Manager allows to configure the currency format for each language individually. Hence, the format in which the currency values are rendered depends on the language selected for the site.
Currencies can be configured in the Currencies form:
Settings -> Currency -> Currencies.
To create a new currency, click Add new currency. To edit an existing currency, select Edit in the action menu of the required currency, or just double-click on it.
The Currency rates form enables you to manage rates of currencies:
Settings -> Currency -> Currency Rates.
The site appearance
The visual aspect of site pages is defined by the a site design template.
The site design template defines:
- page design;
- types of menus and their placement;
- location of the navigation chain;
- layout of advertising areas;
- layout of editable and include areas.
Using templates empowers web designers and administrators with a strong tool to alter the site design depending on requirements. You can:
- change the design for different site sections;
- apply a special festive design for the desired period of time;
- employ different design templates to different user groups;
- use different design templates depending on the URL parameters etc.
You can assign an unlimited number of templates to a site.
You can select templates and configure the conditions of their application in the Template section of the site editing form:
Note: you can leave the Condition field empty to make the corresponding template default.
The system has the built-in Site Explorer, a strong and comprehensive tool for managing site pages and sections. The Site Explorer is implemented as an enhanced file manager.
The file manager allows to supervise both logical and physical levels of the file structure.
- The item titled after the name of the site contains the hierarchical logical view of the site.
In the context of the logical view, only files and folders related to a given site are displayed.
The logical view shows section titles as folder names, and page titles as file names.
- The Files and Folders item shows the physical file structure including system files and directories.
Note: you will find more information on managing site structure in the corresponding chapter.
Switching between sites
The system implements switching between sites by displaying special links on the pages:
These links are generated by a special component which is the part of the site design template. The component enumerates all the sites created using this copy of Bitrix Site Manager, extracts paths to the root directories of the sites and displays links with the their names. Note that the link to the current site is not active, thus providing even more positive indication.
Managing site structure
The Button "Structure"
On the Control Panel toolbar, you can find the Structure button acting as a shortcut to the website file management functions without having to switch to Control Panel.
Click the drop-down arrow and select Site Explorer in the popup menu (or just click the button) to open the Site Explorer dialog box:
You can make the site explorer dialog box work as a kind of two-pane file manager by clicking the Sections button. After doing so, you can move files and folders with your mouse: just drag’n’drop them to whichever folder you need. As you can see, the Site Explorer’s auxiliary pane shows only the folders in this mode.
This convenient dialog box allows you to create, manage or delete files and folders anywhere without having to navigate to a particular section as you would do with Site explorer.
The Settings button allows to control some of the user interface options; namely, you can show or hide files in the main pane and the file information.
The Site Manager is used to manage site sections, pages and files in the site. The Site Explorer user interface is implemented as an enhanced file manager.
Site Explorer tools allow to:
- create and delete files and folders;
- upload files to the server;
- download files to a local machine;
- manage page and folder properties;
- create and edit pages;
- manage site section menus;
- customise user group access permission to pages and site sections;
- view file and folder access permissions at the operation system level.
You can open the Site Manager from the Control Panel (Content –> Site Explorer).
All menus in the site explorer are created dynamically as a user gets new folders opened:
At the top hierarchy level are sites that are running on the system. To view or edit the logical structure of a site, select the corresponding tree menu item.
In the logical view, all files and folders are displayed under their titles (not file names). For example, if the
/about/ folder has a title About us, it will be shown in the file manager as follows:
The Files and folders branch shows the system file structure. This view displays the real names of system files and folders:
The site manager contains the following controls:
- Context bar;
- Context menu;
- Action bar.
Context bar contains a set of common commands that you may need to manage the site structure and content:
Context menu allows to perform required actions on selected file or folder. You can open the context menu for any object by clicking either in the Action column, or right mouse button on the selected element.
A set of actions in the context menu depends on the selected element, its status and the current user access permissions.
Group action bar
This panel allows to perform group actions on elements chosen in the Checkbox column.
| ||-||applies the selected action to all elements in the list;|
| ||-||enables the quick-edit feature on the selected elements directly in the list (allows to rename files and folders);|
| ||-||deletes selected elements;|
| ||-||list of actions that can be performed on the selected elements:
Click Apply to perform the selected action.
- Access – opens a form in which you can configure access permissions of the selected elements;
- Copy – copies the selected elements to the specified folder;
- Move – moves the selected elements to the specified folder.
Creating a new section
In general, a site is an set of pages grouped in sections by subject. In the system context, sections are folders of the site structure. Sections can contain subsections, independent pages and files.
Names of sections are displayed in the navigation chain and the logical structure. You can create a new section from the site Control Panel, as well as directly from the site public section.
- To create a new section from the public section, click on the administration toolbar. By default, a new folder will be created in the site current section.
- To create a new section from the Control Panel, click on the Site Manager context bar. By default, the new folder will be created in the current folder.
A new folder (section) settings are specified in the new folder creation form:
Using this form you can:
- specify the name of a section to which this section refers. This name will be used as the navigation chain item to which the created section refers.
- add a link to the created section to the site menu;
- create the section index page.
The section index page is a file that is opened by default if no page is specified in the URL.
Creating a new page
You can create pages using the built-in system editor. The following three editing mode are possible:
- plain text editor;
- PHP editor;
- visual HTML editor.
A user can always switch to a different editing mode, whichever mode is currently active, by clicking the corresponding button on the context panel of the page editing form (having saved changes).
For example, if the PHP editor is active, the following buttons will be displayed in the context panel:
The site pages can contain both static and dynamic information.
- Static information remains unchanged with time. For example, advertisement, company roots, contact information etc. This type of information can be created and edited by users permitted to edit the site pages.
- At the same time, eventually changing information (dynamic information) can be also required. Dynamic information is displayed in the page body and can be edited using the system tools. The examples of the dynamic information are: latest company news; catalogue of products and services; photo gallery; random photo; banners, etc.
This information is usually published using the visual components that are placed and customised when editing a page in the visual HTML editor. Also, dynamic information can be displayed by adding a script to a page. You can add a script in the source code (or PHP) editing mode.
You can open the page editing form:
- by clicking on the administration toolbar in the public section;
- by clicking on the Context bar of the Site Manager in the Control Panel.
For users without any programming skills, it is more convenient to create pages in the visual HTML editor whose tools are similar to those of Microsoft Word. Besides that, the HTML editor shows the page just as it will look in the public section.
While editing a page in the HTML editor, you can also add a link to it to the menu of the section in which a page is created. To do so, open the Menu tab, specify the item name and select the type of the menu where this item is to be added.
Editing page and section properties
The use of page and section properties allows to:
- manage the display of information on the site in a flexible way;
- control page meta data (e.g. keywords) for search engine optimisation;
- control the navigation chain display;
Property type creation
Before you start assigning values to the page properties, you have to create the required property types. This can be done on the Site Explorer settings page (Settings -> System settings -> Module settings -> Site Explorer).
Property types can be specified for each site individually.
- the type (symbolic identifier) of a new property is specified in the Type field. The property type is used to address the property value in the source code;
- the Name field contains an arbitrary property name. The name is displayed in the page (or section) properties form.
Managing page properties
Page properties are specified when a page is created or edited in the HTML or text mode.
- for the text mode, page properties are specified in the Page properties form:
- when editing a page in the HTML mode, the Page properties tab is used:
Property values can be specified in the page code when a page is created or edited in the PHP mode.
Managing section properties
With the section properties, you can:
- specify the default property values for all pages of a section;
- create your own facilities to manage the display of information on pages.
For example, you can insert images that will be shown on section main pages. To achieve this, create a section property to store the name and path to images, and add code that will process values of this property to the site template.
You can open the section property settings form by clicking
(Folder properties) on the administration toolbar of the public section .
You can also open it from the Control Panel by clicking on the context bar or by selecting the corresponding item in the context menu of a folder.
Uploading files to a site
A special form exists that you can use to upload files to the system. You can open this form by clicking (Upload file) on the context bar of the Site Manager.
This form allows to upload as many files as needed.
Files are uploaded to a folder currently opened in the file manager.
Media Library is a media data manager providing a specialized storage for the media files (images, presentations (.ppt), audio and video files) which assists to categorize data and renders data access almost transparent. Media Library implements a multilevel media data collection the contents of which can further be used to create content (web pages, articles etc.) at your website.
supports the following features:
- multilevel structure of media data storage;
- unlimited number of media collections;
- media collection access control;
- single and batch file upload;
- user defined restrictions for possible file formats;
- using the Media Library contents in the website pages and information blocks;
- searchable properties for each item in a media collection.
The Media Library Settings
Before you can start using your Media Library, you have to configure it.
- Navigate to Settings > System Settings > Module Settings and select the Site Explorer module. Click the Media Library tab:
- Now set the parameters:
- Tick the Use Media Library checkbox:
- Set the desired size of image thumbnails;
- Add more file extensions you want to store in the library, if required. Other files will be rejected at the upload time;
- Set the maximum size of images the library can store;
- To use Media Library instead of the common file dialog for selecting files of types specified in this tab, tick the Use Media Library As… box. The exemplary uses of this feature are highlighted in Examples Of Usage.
The media library content types are collection specific and described in full detail in the lesson Using Collections.
Media Library (Content > Site Explorer > Media Library) is a multilevel structure. The Media Library collections are grouped by the content type:
Each collection is depicted as a bar showing the collection title:
The collection bar has a set of controls:
- Buttons and expand or collapse the collection items;
- Checkbox are used to select collections to which a certain action is going to be applied;
- The action menu contains the collection management commands:
A mouse click on a collection bar also expands the collection items:
The action bar in the bottom part of the collection pane contains only one action enabling you to remove all or the selected collections. To delete all the collection elements, checking the To All box and click Delete.
Creating A New Collection
Any Media Library collection can host any number of nested (child) collections.
To create a new collection:
- click New Collection to open the collection creation form:
- fill in the form fields. The only required field in the collection name; all other fields are optional. However, notice the Location option which you can use to specify the parent collection for the new one thus creating nested collections.
- Click Save. The new collection will become available on the Media Library page:
Editing The Collection Parameters
To change the collection parameters:
- click the action menu button of a required collection and select Edit from the menu:
- the collection properties dialog box will show up. Edit the collection parameters as needed:
- click Save.
Media Library Content Types
Media Library supports various content types. The preinstalled are the three default types: Images, Video, Audio. A user can create as many additional content types as required.
Creating A New Type
Follow the instructions below to create a custom content type.
- Click the Manage Types button on the Media Library toolbar. Don’t be surprised: this will open the Site Explorer module settings form:
- Click Add. The form will reveal more controls allowing to add a new content type:
- Fill in the form fields:
- Type in the Name name of the new type. This field is required;
- Specify the Symbolic Code which will be used by the system internally (or by the developers). This code can contain Latin characters and numbers only. This field is required;
- Specify the file extensions to be associated with this type. This field is required;
- Enter the description for the new type, if required.
- Click Save. The new type will be added to Media Library:
Changing The Content Type Parameters
Follow the instructions below to edit the content type parameters:
- Click the Manage Types button on the Media Library toolbar to open the Site Explorer module settings form:
- Edit the parameters as required;
- Click Save.
Note: Images, Video and Audio are the system, built-in content types whose parameters cannot be modified except the file extensions. The Images type is the basic type and cannot be deleted. The custom, user defined types can be fully edited.
Adding An Item To A Collection
The following steps are required to upload new content to Media Library:
- Click New Element on the Media Library context toolbar, or select Add Element in the action menu () of a required collection;
- In the item creation form, select the file you want to upload to Media Library:
The file can be uploaded from your local machine, or it can be selected in the file structure. To upload a local file, click Browse and select the file in the operating system file dialog. To find and add a file from the server file structure, click the Select Existing link.
- Fill in other form fields as appropriate;
- Click Save. The new item will be added to the selected collections.
Only the files matching the file extensions specified in the Media Library settings and the collection parameters can be added to the library. Whenever a user attempts to upload a file with an extension other than allowed by these settings, the system will issue a warning saying that the file cannot be added to the library. To add more possible file extensions, open the Site Explorer module settings page:
Multiple File Upload
The mass file upload feature takes advantage of Java and ActiveX controls which allows users to select and upload as many files as they want at a single click.
To upload multiple files to the library:
- Click Mass Upload on the context toolbar to navigate to a multiple file upload page:
Select the destination collection to which the files are to be added:
Note: you can add the uploaded files to other collections later, once the upload process is completed.
- In the tree in the left pane, select a folder containing the files you want to upload:
- Then, in the right pane, select the files you want to upload to the library:
- Click Send.
Parameters Of The Uploaded Items
Once the files have been uploaded to Media Library, the system will open the Parameters of new elements page:
Each item has a dedicated form in which you can edit the item parameters and link it to other collections:
Fill in the form fields for each item. Notice that the only required options are the item name and the collection to which an item is bound. As a service feature, each item has a Delete checkbox which, being ticked, specifies to delete the item when the Save button is clicked.
Click Save to apply the new parameter values.
Note: a file can be added (linked to) more than one collection without having to upload it many times. Open the file (a collection item) for editing and specify an additional collection.
Managing The Collection Items
The Item Context Bar
When a mouse pointer hovers over a collection item, the item context bar becomes visible:
- - opens the item in an appropriate viewer (full size image, audio or video player);
- - opens the item properties editor;
- -deletes the item.
Editing A Collection Item
To edit a collection item, move the mouse pointer over the item, and click the icon . This will open the item properties dialog box:
To change the underlying file, click Edit and upload a new file as described in Adding An Item To A Collection:
Once you are done with the changes, click Save.
Managing The Collection Access Permissions
To set or edit the collection access permissions:
- Click Access on the context toolbar, or select Access command in the action menu () of a required collection. The Sets Media Library collections permissions form will show up:
- In this form, select a collection whose access permissions you want to modify. You can set the same permissions to all the existing collections at once by selecting Common Access for All Collections from the list:
Note: by default, nested collections inherit the permissions specified for a parent collection.
- Set the access permission for each of the user groups:
The following access permissions are available:
- Access denied: any access to the collection for this user group is forbidden;
- View collections: the user group members can view the collection items;
- Create new collections: the users are allowed to create new collections in this collection;
- Edit elements: the users can create collections and modify the collection item properties;
- Edit elements and collections: the users can create collections; modify the collection item properties; modify the collection properties;
- Full access: the users are granted unrestricted access to Media Library.
- Click Save to apply new access permissions.
The Media Library items can be searched for by the values of the item properties.
For example, to find elements that have any relation to the subject of “journey”:
- Type “journey” in the Search field:
- Click Search;
- As a result, the system will find and display items whose name, description or keywords have the word “journey”:
The Hide link collapses the search results.
Note: deleting the items in the search results pane deletes them from all the Media Library collections.
Examples Of Usage
Using Media Library In The Visual HTML Editor
Adding An Image:
- Open a page for editing in the visual editor;
- Click the Image button on the editor toolbar::
The New Image dialog box will appear.
- On the image browse button, click the drop-down arrow and click Select a Media Library item in the menu:
- In the Media Library browser, select an image you want to insert:
Note: you can upload a new image to Media Library using this form by clicking Add Element.
- All other form fields are optional; fill them in as you consider appropriate:
- Click Save.
Once you have saved the changes in the visual editor, the photo will show at the web page.
Adding A Media File Player To A Web Page
- Open a page for editing in the visual editor;
- Add the Media Player component to the page (bitrix:player) (Content > Media > Media Player):
- Find the File Path component parameter:
- Click the browse button beside the field and select a media file in the Media Library browser:
- Save changes.
Using Media Library With Information Blocks
As an illustration, consider the example of creating a book catalog element:
Bitrix Site Manager stipulates that you control access permissions at the user group level. This means that each site visitor (or user) is a member of one or more user groups each having its own access permissions.
The concept of access permissions enables you to:
- control access to the site resources (pages, sections, forums ets.);
- set up for the site content editing teamwork;
- allow third parties to perform unassisted actions (e.g. publish advertisement);
- create mailing lists for dispatch to user group members.
Upon registration, a user obtains the personal credentials (login and password), and becomes a member of one or more user groups.
If you enable the self-registration option, users are added to a default user group that is selected in the Kernel module settings. The administrator can change the user registration later.
Users can register themselves in the standard registration form that you can place anywhere on the site:
If a user is a member of more than user group, the maximum of permissions of user groups takes effect.
that a user is a member of the following two user groups:
Members of the Site editors user group are permitted to edit site pages;
however, they cannot access the partner section.
Members of the Partners user group can view pages of the public section, as well as view the partner section.
A user who is a member on these two user groups gets the following permissions:
- edit all the site pages, except for those of the partner section;
- view pages of the partner section.
A user has to authorise in the system (using the authorisation form) to gain access to the site according to permissions of their user group:
Upon authorisation, the user will see the administration toolbar containing the site management commands, at the top of the screen:
The set of available commands depends on permissions of the user group whose member the user is. For example, the administration toolbar will not be shown to users who can only view public section pages. The site administrator enjoys the full set of commands.
Bitrix Site Manager implements the two-tiered access permission distribution policy:
- Tier 1: access to files and sections;
- Tier 2: access to the system modules and operations on modules.
These access levels are independent and are managed using the appropriate system tools.
User group profiles are configured in the User List form:
Settings -> Manage users -> User list
To add a new user manually, click Add user on the context bar.
Note: if the user self-registration option is enabled in the Kernel module settings, a user profile is created automatically each time a user registers in the system.
You can edit the user profile parameters by double-clicking on the respective table row, or by selecting the Edit menu item in the context menu.
Note: The system administrator profile is created at the installation time. This profile can be modified in future but cannot be deleted.
The user profile editing form looks like follows:
You will find the detailed description of the form in the help section.
User group profiles are configured in the User List form:
You can manage user groups in the User Groups form:
Settings -> Manage users -> User groups
- To add a new user group, click Add group on the context bar.
- You can edit the user group settings by double-clicking on the respective table row, or by selecting the Edit menu item in the context menu.
: The system always has two mandatory user groups
- all unregistered users are members of the Everyone
group by default; they can access all pages of the public section (except private sections);
- the Administrators user group's members enjoy full access to the system resources and management, including changing permissions of other users.
Parameters of these groups can be edited in any way (for Everyone
, access settings can be altered); however, they cannot be deleted.
You can add users to a group in the user group editing form:
or in the user profile editing form (the Groups tab).
Note: in the Active period fields, you can specify the period of time during which a user is a member of a respective group. When the active period expires, the user is removed from the group; however, the user profile remains.
Don’t change the parameters you see on the Security tab unless you clearly understand what you are doing. It is even more crucial and may entail undesirable consequences if your website is up and running because it defines a security policy for a current user group.
The most widely used fields are Session maximum life time and Maximum number of computers to store authorization simultaneously.
To obtain the best Session maximum life time value, seek the balance between the necessity of longest uninterrupted sessions of authorized users and system performance. Don’t make session lifetime too long. The size of the PHP session folder will grow rapidly which will make session start-up rather sluggish. It is generally not advised to use values more than one hour.
Maximum number of computers to store authorization simultaneously field is used when your content managers have to work from multiple workstations. In this case, you can either decrease the session lifetime value, or increase the number of machines in this field. From a security standpoint, the former approach is better.
Use the Access tab to define access permissions to the system modules. Assume you have to deny the content manager access to the blog and forum management functions because these are going to be controlled by independent administrators. To do so, disable the management access for the content managers user group while keeping the permission to read and create blogs – just like for other common users.
Example: creating the content managers user group
The following example will show how to set up a user group in a correct way.
- Create a user group.
- Open the Site Explorer module settings page. Set the Edit files and folders permission for this user group;
- Give the Read permission to the /bitrix/admin/ folder (otherwise, the users will not be able to view the Control Panel pages);
- When configuring the information blocks you need to be managed by the content managers, assign the Write permission for this user group. Otherwise, the information blocks will be unavailable to the members of this user group.
- Finally, add users to the group you have created.
To add a series of users to the system, use the Import users form.
Note! When uploading users to the system, you can retain their previous user group binding, or specify a user group to which the users will be added. However, you cannot add an individual import user to a certain group.
Open Settings > Manage users > User import. The following form will show:
Select the required data source and click Next.
Further actions on importing users are described in this chapter according to the data source selected.
Importing from a CSV File
Important! If the system uses the UTF-8 encoding, a CSV file must be created in this encoding as well.
Preparing a CSV File
A valid CSV file must exist before you import users from it. The file must have the following format:
Each line in the file represents a table row. A header can include any records in a single line. The header describes the data that follows it. The values in each line (the header and the data) are separated by a delimiter.
Example of user data header
The data in fields must match the format prescribed by the header. The field must exist no matter whether it is empty or not; essentially it means that, if there is no data for a field, the separator must exist (e.g. “;;”).
For example: if the file header has the following format:
and there is no data for some fields, say 2, 4 and 5, the data row must still be like the following:
Consider the following aspects when formatting a CSV file:
- Any delimiter character is allowed: comma (,), semicolon (;), space or tab. No spaces can exist between the values. If a delimiter is a space, make sure no double spaces have been added between the values.
- If a comma is the part of a value (for example, if the object properties are comma-separated), enclose the value in quotes ("yellow,red,green").
- If double quotes are the part of a value, enclose the value in double quotes. For example: "John" in a CSV file must look as ""John"".
- Empty rows in a CSV file are not allowed.
- The headers, string values, and logins are case insensitive.
- Passwords are case sensitive.
- Boolean values can be presented as: Y - true; N - false.
- Any excessive data existing after the last identified field are ignored. For example, if a file header specifies 10 values while the row contains 12 values, the last two values will be ignored.
- Empty data fields are processed as empty strings.
- The time and date format must be set in the format of the site language. For example: MM/DD/YYYY HH:MI:SS for English.
Exporting Users from Bitrix Framework
To export users, do the following.
- Open Settings > Manage users > User list.
- Click Excel to download data.
- After downloading, edit the file to conform the CSV format requirements:
- delete the export summary information at the end of the file;
- if required, change the field names in the file header with the correct ones (see the Data types table below);
- check if the fields are filled correctly (see the Data types table below).
The table contains all the data types that may encounter in a CSV file.
||Required ||Comments |
||No. Default is True. ||Active. |
|LOGIN ||string ||No. Auto generated by default. ||Specifies a user login, min. 3 characters. |
|PASSWORD ||string ||No. Auto generated by default. ||Specifies a user password, min. 6 characters. |
|NAME||string ||Yes ||User’s first name. |
|LAST_NAME ||string ||Yes ||User’s last name. |
|SECOND_NAME ||string ||No ||User’s second name. |
|EMAIL ||string ||No. Default value is the administrator’s e-mail. ||The E-mail address. |
|DATE_REGISTER ||date||No. Default is the current date. ||The date a user was registered. |
|LID ||string ||No ||The ID of a default site for notifications. |
|ADMIN_NOTES ||string ||No ||Administrator’s notes. |
|EXTERNAL_AUTH_ID||string ||No ||The external authorization source ID. |
|XML_ID ||string ||No ||The user ID for external connection (e.g. ID in an external database). |
|Personal data ||Type ||Required ||Comments |
|PERSONAL_GENDER ||string ||No ||Gender: M – male; F – female. |
|PERSONAL_BIRTHDAY ||date ||No ||Date of birth. |
|PERSONAL_CITY ||string ||No||Address: city. |
|PERSONAL_STATE ||string ||No||Address: region, state etc. |
|PERSONAL_ZIP ||string ||No||Address: ZIP code. |
|PERSONAL_WWW ||string ||No||Personal web site URL. |
|PERSONAL_PROFESSION||string ||No||Profession. |
|PERSONAL_NOTES ||string ||No||Arbitrary notes. |
|PERSONAL_ICQ ||string ||No||ICQ account number. |
|PERSONAL_PHONE ||string ||No||Home phone. |
|PERSONAL_PHOTO ||string ||No||The path to a photo relative to a folder specified in the import parameters. |
|PERSONAL_FAX ||string ||No||Fax number. |
|PERSONAL_MOBILE ||string ||No||Mobile phone number. |
|PERSONAL_PAGER ||string ||No||Pager. |
|PERSONAL_STREET ||string ||No||Address: street. |
|PERSONAL_MAILBOX ||string ||No||Address: P/O box. |
|Work data ||Type ||Required ||Comments |
|WORK_COMPANY ||string ||No||Company name. |
|WORK_DEPARTMENT ||string ||No||Department. |
|WORK_POSITION ||string ||No||Position. |
|WORK_WWW||string ||No||Company web site URL. |
|WORK_PHONE||string ||No||Work phone. |
|WORK_FAX||string ||No||Work fax number. |
|WORK_PAGER||string ||No||Pager. |
|WORK_STREET||string ||No||Company address: street. |
|WORK_MAILBOX||string ||No||Company address: P/O box. |
|WORK_CITY ||string ||No||Company address: city. |
|WORK_STATE ||string ||No||Company address: region, state etc. |
|WORK_ZIP ||string ||No||Company address: ZIP code. |
|WORK_PROFILE ||string ||No||Company profile. |
|WORK_LOGO ||string ||No||The path to a company logo image relative to a folder specified in the import parameters. |
|WORK_NOTES||string ||No||Arbitrary notes. |
|UF_*||string ||No||User field. |
|IBLOCK_SECTION_NAME_* ||string ||No||Information block binding. |
The UF_* values are user properties created by the administrator. The properties must be created before importing users.
The IBLOCK_SECTION_NAME_* values indicate the information block binding. 5 nesting levels are possible.
Important! The name (NAME) and the last name (LAST_NAME) are the only required fields to import users from a CSV file.
Example of a CSV file:
To make sure you will not encounter any errors during import, check that the file data meet the specification described at the beginning of this chapter. You can check this by opening a CSV file in MS Excel:
- Check the headers.
- Ensure the length of all passwords is at least 6 symbols.
- Ensure the length of all logins is at least 3 symbols.
Note! The system will always successfully import CSV files created in MS Excel. If you created a CSV file in some other application, open and check it in MS Excel.
After you have verified the CSV file, you can import it.
The Import Procedure
In the Import users form, select CSV file as a data source and click Next.
Fill in the fields in the next tab (Import Settings):
Click Next. The next step imports users. Upon completion, a message indicating the number of imported users will be shown.
Viewing Imported Data
To view the imported data, open Settings > Manage users > User list showing all the users registered in the system.
If the import procedure failed for some reason, delete all the records that have succeeded to import, correct the CSV file and perform the above actions again.
Import from LDAP Directory
For massive user creation, use the Import Users form (Settings > Users > Import Users).
To import users from Active Directory/LDAP:
The advanced access management approach implemented in Bitrix Site Manager enables users and system administrators to configure user access permissions to any level of sophistication. The system operates on the basis of the two entities: an access level and an operation. The access level being the property of a module or a user group includes one or more permitted operations (e.g. file creation permission, user management permission etc.).
Access level — is a set of operations that a user can perform. The access levels and the underlying operations are assigned by the system administrator. The access levels are inheritable, which means that if no explicit access permission exists for a section or page, the access parameters of a parent section take effect.
A good example of a user oriented operation is Make partial correction to files containing PHP code. An administrator can enable this operation for a certain user or a user group so they can edit the component parameters or edit files containing the inclusions of PHP code.
Currently, the access levels can be specified for the modules: Kernel, Commercial Catalog, Site Explorer, Proactive Protection and SEO. Other modules will be enhanced to support access levels in the nearest future.
To manage the access levels, browse to Settings > Users > Access Levels:
This page shows the existing access levels. Note that there are special system access levels which cannot be modified or deleted. However, you can always create a copy of any system access level and edit the copy as required.
To create a new access level, click Add acess level on the context toolbar. Obviously, the access level property form will show up:
Once you have devised a proper name and description for the new access level, select the module in which the access level will be available. Then, choose the object whose access is to be controlled by this access level. If you select Module, the level will be applicable to the selected module. If you select File/Folder, the level will control access to the files and/or folders with respect to the selected module.
The options on the Operations tab depend on the selected module and the control object. For example, the following figure shows options available for the previously selected settings (on the image above):
Once the access level is saved, it will become visible in the module settings and in the user group’s Access tab:
Permissions to access functions of the system modules can be configured:
Assigning permissions to access modules allows to define the scope of actions that a user is allowed to perform on the functions and content of a module.
Additional access permission configuration is done in the editing forms of modules that allow this (see Access to Content).
the site administrator decides to entrust member of the Site editors
group with editing pages of certain sections. To permit site editors create and edit sections and pages, assign the To accessible folders only
permission to the Site editors
This will allow to define files and folders that the site editors can access. You will find an example of this configuration in the Controlling Access to Files and Folders lesson.
Besides that, the Advertising and banners and Helpdesk modules introduce roles to bring more flexibility. A role implies restricted predefined set of actions available to a user group.
For example, the Advertising and banners module users can have the following roles:
- Advertiser can access the module control panel, view their own contracts and manage their banners;
- Banner manager can manage banners of the certain contracts (contract parameters cannot be configured);
- Advertising administrator - implies full access to the advertising, including contracts as well as access levels of other users.
You will find a detailed descriptions of roles in the help section, in chapters devoted to respective modules.
Access to content
Certain modules provide additional customization of access to their content.
The Information Blocks Module
Note! User groups' access levels to information blocks are configured for each information block individually.
Access levels are set in the information block editing form (the Access tab).
For example, assume we want to allow members of the Site editors group to create and edit new entries of the Company news information block. To do so, assign the Edit permission to the Site editors group in the information block settings form:
The Web Forms Module
In this module, you can control access to web form results at the result status level.
: statuses are available only in the extended editing mode:
For each status, you can define user groups allowed to handle web form results in this status:
Controlling access to files and folders
You can assign the file and folder access permissions in the Site Explorer:
Content ->Site Explorer.
You can view the access permission of a certain user group by selecting it in the drop-down menu Show access permissions for on the context toolbar:
Do the following to change permissions of a user group to access files and/or folders:
User groups can have the following access permissions:
- Deny: members of a user group is not permitted and is not able to access a given file or folder;
- Read: members of a user group view a given file or folder in the public section;
- Write: users can edit files and save changes;
- Full access: users can edit files and folders; they can control access permissions of other user groups to these elements;
- Inherit: files and folders will be assigned the same permission as the parent folders.
: To set the access permission for a current directory (e.g. root folder), click the Folder properties
button on the context toolbar.
Nested files and folders can inherit access permissions from the parent folder.
, let us give members of the Partners
user group a permission to manage the Company
folder). All other files and sections are to be made available only for reading. To do so:
- Assign the Read permission to the Partners user group for the root folder.
- Assign the Inherit permission for all nested files and folders except the /about/ folder.
- Assign the Write permission for the /about/ folder to the Partners user group.
Finally, set the permissions for all the child elements of the /about/ folder to Inherit.
As a result, members of the Site editors
user group are permitted to view all files in
the public section, and create and edit subfolders and files in the Company
Using the workflow module
The Workflow module implements stepwise processing of
both static and dynamic site pages. This module empowers you with the teamwork
The consequent work is organised using the document statuses each indicating a certain stage in the document
processing, and user access
permissions to documents in these statuses.
Statuses are managed on the Document statuses page (the Workflow module (Content -> Workflow -> Statuses):
Number of possible statuses is unlimited.
Note! A status of ID =1 is final in the workflow
chain. It is reserved and cannot be deleted, but the status name can be
changed (the Published status in the picture). When a
documents reaches this status, all changes performed can now be applied to
it (i.e. the document is published).
Permissions of a user groups to access documents in certain statuses are
configured in the status editing form.
Using workflow with static pages
The use of workflow to organise the stepwise processing of pages can be illustrated with the
For example, you may want to allow some users to create and save documents in the Ready for
publishing status only, while other users will be able to check and send the documents (if
they are not ready) for revision (i.e. by assigning the Draft status to
them), or publish the documents on the site (i.e. Published).
To entitle user to work with the site pages in the workflow mode you have to do the following.
Using workflow with information blocks
You can allow some users to create and save news in the Ready for
publishing status only, while other users can check and publish these news (if
they are ready) on the site (i.e. by assigning the Published status to
The following operations are to be performed to entitle a user to work with the information block elements in the workflow
- Assign the Workflow permission for the required information block
to a group to which a user refers.
- Configure the user group permissions for document statuses in the Workflow
More uses for user groups
Controlling user interface objects
Bitrix Site Manager allow to apply additional conditions to control the display of site elements and the access to them, for different user groups.
For example, you can check a user group to which the current user refers and select a required design template for display. You can set the condition on the site settings page:
Also, a current user's group can be checked to select a condition
for the menu item display. This type of condition can be specified in the extended
menu editing mode:
Managing interface languages
One of the features of the Control Panel is support for multilingual
user interface. In other words, it can display its text parts in different languages installed in the system.
This also allows to print system messages (e.g. error messages), display forms and tables in different languages.
Note: The display language of the context help section also depends on language selected in the Control Panel. Currently, the system is shipped with the help sections in Russian and English languages. You can update (or install new) help files via the Update System.
The Control Panel languages are also used to define language in which messages of the visual components are displayed, as well as the system messages in the public section of a site. To put this another way, the language selected in the Control Panel forms define the main language of a site.
The multilanguage interface is built upon the use of special language files. Each system module supports a set of language files stored in folders; the folder names are the language abbreviations. Files in these folders contain messages and strings translated in the corresponding language.
The system is equipped with a full set of messages for English language. You can select the desired language installed in the system using the Control Panel toolbar buttons.
The number of language installed in the system does not correlate in any way with the number of sites running on the system.
Managing interface languages
You can manage interface languages on the Languages form.
Settings -> System settings -> Interface languages:
The table entries define the languages in which the system messages can be displayed: notifications, error messages, titles of tables and controls etc.
To add a new interface language, click the Add language button on the context toolbar. You can edit parameters of a certain language by selecting Modify in the action menu, or by double-clicking the table row containing the required language.
Each system language has the following parameters:
- symbol language identifier;
- encoding in which messages are to be displayed;
- date and time display format.
The system language identifier is used to identify and download the appropriate language files. It must have the same name as the language identifier expected by the Update System.
For example, the server expects the identifier la for Spanish (Latin American) language files. Hence, you will have to create the language with the identifier la before downloading Spanish (Latin American) language files.
You will find a complete list of language identifiers in the help section
Note that the language encoding (charset) defines the encoding in which information is stored in the system modules. For example, you need to use the
charset for Russian text.
Remark: in some cases, the
UTF-8 encoding may be used. However, this stipulates that all the system languages are also stored in
Assume you want to add the Spanish (Latin American) language to the system. You will have to perform the following operations.
- Click Add language on the context toolbar to create a new language record.
- After you click Save, the new record appears in the report table on the Languages form.
- The Control Panel language toolbar now has a button which being clicked will switch the user interface to the Spanish (Latin American) language.
- The last step is downloading language files for the created language. You will find an example of this operation in the next lesson (Installing and updating language files).
Installing and updating language files
Bitrix Site Manager can show the user interface controls and messages in any language which is achieved by using downloadable message files containing text in a corresponding language. To download new or update existing language files, open the System Update page (Settings > Update):
Click the Updates tab:
Here you can:
- update your language files to new versions for the languages that are already installed in your system (Recommended Updates);
- install support for new languages (Optional Updates). Note that the system downloads these files automatically when you add user interface languages.
Select the required updates and click Install Updates.
Downloading Language Files: Example
Assume you have a Spanish (Latin American variant) user interface installed and want to update the language message files.
- Open the update system form (Settings > Update).
- Click the Updates tab and select the existing updates for the Spanish (Latin American) language:
- Finally, click Install Updates. The new files will be downloaded and installed.
To implement the multilanguage interface, all the text messages (labels, captions etc.) of the Control Panel are stored in the language files in the form of text strings. The language files are located in the language folders (titled by the language name abbreviation) in the folders of the system modules.
For example, the language messages are used to render table headings:
There are two ways to translate the language files into any language:
- by editing the files manually;
- by using the Localization module.
The Localization module offers a neat and comprehensive message translation interface and also has the following features:
- view the count of untranslated messages in language files;
- translate text messages.
To view how many messages are untranslated, open the Interface localization form.
Settings -> Localization:
You will find the number of untranslated messages for each language shown in red. To translate messages, open a file whose messages you want to translate, and type the translation in the corresponding text input fields:
Note: the form will display messages for languages that can be displayed using a single charset.
You can quickly start translating the missing messages directly from a page on which these messages are used (both in the public section and Control Panel). To activate the quick translation mode, use the button (it is visible if the corresponding option is checked in the Localization module settings)
or add the parameter show_lang_files=Y to the page address:
This will display a list of language files whose entries are used to render the text on a current page.
File names are shown as links, which can be clicked to open the language file for editing. In the end of the list you will find a search field. You can use it to find a required message (exact match).
: find the message "Search", displayed in the site search form:
Type "Search" in the message search field:
As a result, a list of files containing the sought phrase will be displayed.
Note that a special link appears beside each file. You can click it to open the message file and scroll right to the sought message.
Note. To aid massive localization projects, a special script has been developed that can collect all the language files altogether. The collected files can be published in the Update system for download by other users.
The Information Blocks module is designed to manage blocks of a heterogeneous formation. You can implement product catalogues, news
sections, dictionaries etc. using information blocks.
This section contains detailed description of entities of the module as well as examples of creation and configuration of information blocks.
The Information blocks is the module aimed to manage and catalogue different types
(blocks) of homogeneous information. Some examples of information blocks are:
- product catalog;
- photo galleries;
- job lists and other information.
Information blocks offer a convenient way to store the frequently updated information. This
method of publishing the information saves time and efforts. You can easily add new information
to the site, and also export and import information.
The concept of information blocks is built upon the following objects which can be regarded as
the information repository tiers:
- types of information blocks (define the structure of information blocks);
- information block (contains information in its sections and elements);
- information block sections (can be thought of as file system folders);
- information block elements (contain information).
The Information blocks module implements the following hierarchical model of information
Types of information blocks
The types of information blocks (e.g. Catalog, Dictionary, Vacancies, News etc.) are used for grouping the information blocks. Information blocks of the same type usually have similar subject and the identical structure.
For example, the information blocks Company News, New Products and Partner News can be derived from a single type - News (see figure above).
The following parameters are defined at the level of information block type:
- layout of the information block structure: defines whether information blocks of this type
can contain sections and subsections;
- names of sections and subsections of information blocks;
- option of exporting the information block contents to RSS;
- optional custom element editing form.
The types of information blocks can be created and edited on the Information block types
Content -> Information blocks -> Information block types.
The names of information block types currently existing in the system are added to the Control Panel menu:
Information blocks contain pieces of uniform information. For example, a catalog Phones can contain descriptions of mobile phones, whereas a Photo Gallery information block can contain images. Depending on the information block type set-up, information blocks can have sections and subsections (i.e. tree structure).
The information block parameters allow to:
- assign user access permissions for an information block;
- select site(s) where the information block contents can be displayed;
- define the addresses of a public pages that are used to display elements and/or sections of the information block;
- create custom properties for describing the information block elements. For example, elements of the Phones information block can the following properties : Year, Stand-by Time, Weight, Standard etc. Users will have to provide values of the custom properties when creating elements of this information block by filling in the appropriate fields;
- configure RSS export parameters (if the RSS export was enable in the information block type settings).
You can view the list of information blocks by clicking the name of the information block type in the Control Panel menu:
You can manage information block of the selected type on the Information blocks form:
Information block sections
Sections are containers used to group elements within an information block. Using sections allows to build the hierarchical structure of information repository. Names of
information block sections (e.g. Group, Section, View etc.) can be defined in the settings of a corresponding information block.
Each information block has its own set of sections and subsections. You can view the list of information block sections:
Information block elements
Elements of information blocks are the containers for the user supplied information stored in information blocks (news, products, dictionary entries etc.).
You can view the list of elements of an information block:
- by opening the element context menu (figure on the left), or by clicking the number of information block elements (see figure on the right);
- by opening the section context menu (figure on the left), or by clicking the number
of elements in a section (see figure on the right);
- from the Control Panel menu.
Examples of structured information
The concept of information blocks enables you to build information storages of different structure. You will find examples of various approaches to creating information storages in the trial version.
Single tier architecture
In this version, information blocks do not contain sections or subsections. For example, the Articles information block immediately contains elements which are the descriptions of articles:
: the system does not limit the number of hierarchy levels. What is more, elements may not belong to any of existing groups (sections). In this case, they are attached to the top level:
Customizing the Information block forms
Customizing The Form Fields And Behavior
To make adding a large number of information block elements easier, you can configure the form the website users will open for creating elements by, for example, assigning default values to the fields or preconfiguring the field value types. To customize the element creation form for a certain information block type, open the information block properties form (Content > Information Blocks > Information Block Types > [information block name]) and click the Fields tab.
Remember: you will use the Field tab controls to set the default field values.
This form shows the following three columns.
You can use the text fields in the Default Value column to give hints for the content managers. For example, you can type in the following brief instructions in the Preview Text and Detailed Description fields: Short news headline here and Full news text, respectively.
Generally, the websites use different size variants of the same image for an information block element: for example, a preview image and a detailed photo. Adding multiple elements with images of different size versions is a tedious task consuming much time and effort. However, with the Information Block module features, you can easily do without having to resize images manually: just upload a large size image, and specify the image processing parameters.
As an example, the following settings configure an information block in such a manner that adding a large scale image will result in the two image sizes, each with specified quality and size.
- Check the Auto-create preview image from detail image box;
- Check the Auto-resize large images box. The uploaded images will be rescaled to not exceed the dimensions set in the next two fields;
- In the fields Maximum width and Maximum height, specify the thumbnail size. The resizing algorithm processes an image with respect to its proportions. Setting the maximum dimensions guarantees that the thumbnail does not mess up the page layout;
- Check the Ignore scaling error box to print the image “as-is” if it fails to be processed correctly.
Note: The system can process the most common Web image formats: jpg, gif, png. Images in other format will not be processed; the system will either leave an image untouched, or return an error, which is defined by the Ignore scaling error option.
The following options can be used to control the image quality, which might require more server processing power.
- Check the Preserve quality when scaling box;
- Set the required quality (0-100). Note that values close to 100 will increase file size, sometimes significantly.
The same scaling parameters apply to the Detailed image field group.
For both preview and detailed texts, in the Description Type fields, set the type of the text editor a user will use to enter the text. Plain text is commonly the best option for the previews, while the detailed description usually requires rich text formatting, so use HTML here. This will also enable you to import HTML descriptions from CSV files.
Customizing The Element Creation Form
An element creation form can be adjusted to match user preferences of the website content manager. After having been configured, the form appears in a customized layout in Control Panel as well as in the public section.
You can move any form field between the form tabs thus providing the best user experience for each information block depending on the content an information block contains.
To customize the form, do the following.
- Open any information block element for editing. Click Settings on the context toolbar:
- The Customize form appearance dialog box will show up;
- Customize the form as required by adding or removing the fields to/from the appropriate tabs.
Once you have done adding and removing fields, click Save. The following screenshot pictures an example of the customized element editor form:
Whenever you want to revert the form layout to default, click the button at the top right.
To simplify data export and import and exchange of information between
different systems, information blocks include tools for data export and import
RSS and CSV
Export to RSS
By using RSS export, administrators can exchange data (e.g. news, catalogs etc.) with other systems. RSS export is only available for information blocks whose type has the option Export to RSS enabled.
Content -> Information blocks -> Information block types -> <select your information block type>:
You can specify the path to a folder where the system will store the exported files, in the settings of the Information blocks module.
Settings -> System settings -> Module settings -> Information blocks.
Note: the RSS export path is always relative to the site root!
For example, you can export data in the RSS format from any information block using the settings of the composite visual component.
Do the following to enable the RSS data export:
create the page (for example, /content/news/index.php ) using the visual HTML editor. Add the News composite component to the page and configure the component by specifying the required information block, RSS settings and other parameters:
Note: you must ensure that the selected information block is enabled to export data to RSS (the option Export to
RSS should be enabled).
- The created page looks like here:
- Now, if all the preparations are correct, opening the rss page will emit the list of elements in the RSS format.
You can find an example of such page in the demo site of the trial version (/content/news/index.php
The system provides a simple visual component RSS news (import) to publish information obtained via the RSS channel.
To receive news, configure the component properly by specifying the source site address; path to an RSS file; query string (supplied by the administrator of the news source site); other parameters are optional. Save the page.
Export to CSV
You can easily export data from an information block to a CSV file in the Catalog export form:
Content -> Information blocks -> Export
The process of exporting data requires undertaking the following steps.
Step 1. Selecting an information block
Here you have to select an information block whose contents is to be exported:
Step 2. Setting export parameters
At this step, the following export parameters are to be defined:
- format of the output file;
- fields that are to be present in the file;
- path and name of the file.
After you have finished configuring the export settings, click Start to actually
export the data.
Step 3. Result
After the export is completed, the system displays results of the export operation.
You can download the file containing the exported data by clicking the corresponding link.
Import from CSV
Bitrix Site Manager allows you to easily import data from any CSV file to a certain information block of your choice. The whole operation is performed in the Catalog import form:
Content -> Information blocks -> Import).
Step 1. Selecting a data file
Choose a file (it can reside on a server or a local computer) whose data will be loaded in a specified information block.
Step 2. Choose data format
Now, specify the format in which data is stored in the specified file.
Step 3. Assigning fields
A CSV file from which information is added to an information block contain data in fields (named or nameless). When importing the data, the system places values from the CSV file fields to the fields of the selected information block. Hence, you have to instruct the system about the correspondence between the CSV file fields and the information block fields. You can do this at this step.
After you have finished configuring the import settings, click Load data to start importing.
Step 4. Result
After the import is completed, the system displays results of the import operation.
Exporting Data to XML
The advanced XML export techniques implemented in Bitrix Site Manager allows to transfer information block properties and images in addition to simple text information. This feature is available in all the editions.
To export data of any information block to XML format, open the Export to XML form (Content > Information Blocks > Export > XML).
Here, select the data to be exported, and set the export parameters.
- Destination File: specifies the file to which the XML data will be written. Click the Open button to bring up the file dialog to select the destination file in the site structure;
- Information Block: select the information block whose contents is to be exported;
- Step Duration: export might take a long time if the selected information block holds huge amount of data. In such case, export may fail if your server imposes restriction on the script execution time. Setting the step duration to a value other than zero instructs the export engine to run in small steps. The default value of 30 seconds usually works best. If you set the step time to zero, all the information will be exported at one step.
Click Export. The export procedure will start showing the operation progress. Once the operation is completed, the system will inform you of the status:
Importing Data from XML
In this lesson we are going to discuss the procedure of importing external data to the information block structure. Open the XML Import page (Content > Information Blocks > Import > XML).
Click the Open button and select an XML file in the server file structure, or upload a file from your computer. Then, select the type of a new information block which will be created during the import procedure. Make sure you have selected at least one of your sites: the new information block will be bound to such sites.
: Generally, when you import data, the system creates a new information block of the selected type. However, if such information block already exists, the XML import engine acts differently. It will update the existing elements using the XML data and create new elements if they are missing in the existing information block. For those elements that exist in the information block but are missing from an XML file, the system will act according to your choice:
- perform no operation at all;
- deactivate such elements;
- delete such elements.
As with exporting large information blocks, the process might take long if a selected XML file is huge. In such case, import may fail if your server imposes restriction on the script execution time. Setting the step duration to a value other than zero instructs the import engine to run in small steps. The default value of 30 seconds usually works best. If you set the step time to zero, all the information will be imported at one step.
If the information block element has an image in the description field, and the Auto-create preview image from detail image option is checked, the system will create a thumbnail image using the specified maximum dimensions.
Having specified all the parameters, click Import. The import procedure will start showing the operation progress. Once the operation is completed, the system will inform you of the status:
Creating and publishing news
Creating a news section
To learn how to create a section in which we can add and publish news, we shall examine an
example of creating the Company News site section. To achieve the goal, we are going to do the following:
- create the News information block type;
- create the Company News information block;
- design and set up the Discounts and offers information block section;
- add elements (news) to the information block.
- First, we have to create a new information block type to which the Company News information block will relate. For example, create the type News (click Content -> Information blocks -> Information block types, click Add new type on the context toolbar).
Since we plan to create sections in the Company News information block, enable the Use tree view to classify section elements option.
- Next, create the new information block of the News type, and name it Company news (Content -> News, click Add information block on the context toolbar).
- Now create the Discounts and offers section in the Company news information block (Content -> News -> Company News, click Add subsection on the context toolbar).
Following the operations performed, the following structure will be added to the Content part of the Control Panel menu will have:
- Now we can start enriching the created information block section with the required information.
- Open the list of information blocks of the News type (Content -> News);
Click the action menu icon of the Company news information block. In the action menu, select the News item. This will open a form containing the information block elements.
- In the information block element form, click Add element on the context toolbar.
- Fill the form fields with the news contents, and provide other information.
Since we want to add the news to the Discounts and offers section, open the Groups tab and select the section name in the list.
However, if you want to add an element not binding it to a particular group, choose Upper level in the list.
With Bitrix Site Manager, you can easily publish news in the public section of your site by using the visual components.
You can use the components version 1.0. In this case you will find these components in the News drop menu of the Information
Blocks group in the Components sidebar of the visual editor.
- All news: displays elements (news) of all information blocks of a certain type (e.g. News).
- List of news: displays elements (news) of a certain information block.
- News details: displays the details of a certain element of an information block.
- Newsfeed: displays a series of news, which are in essence elements of one or more information blocks of one type.
- RSS news (import): allows to import news in the RSS format from another site.
- RSS news (export): exports news from the site to the RSS format.
There are also components version 2.0. A composite component News helps to create a news section on the site. Simple components version 2.0 (List of news, News details, Articles and news feed, etc.) have additional features.
You can add visual components to your pages in the visual HTML editor. Let us create a list of news on the main page, and give visitors an opportunity to view details about each news.
- Open the main page (/index.php) for editing in the visual HTML editor.
- Select the Content section on the Components sidebar. Open the News drop menu. Find the List of news component and drag-and-drop it to the page.
- Configure the visual component:
- specify the information block whose elements will be displayed in the newsfeed;
- specify the detail page URL. By default, the data from information block settings will be used. We set here /content/news/index.php?news=#ELEMENT_ID#. The page /content/news/index.php will be created later.
- set other parameters if required.
- Save the page.
- Now, create a page /content/news/index.php. This will be a news section.
- Create a new page in the visual editor.
- Add the News composite component to the page:
As a result, the main page will contain the list of news:
If a visitor clicks any news in the newsfeed, a page with the news details will open:
Creating a product catalog
Creating the catalog
The Information Blocks module enables web developers to create product catalogs as complex as required. Consider an example of creating the Books catalog. Our task requires the following actions to be performed:
- create the Bookstoreinformation block type;
- create the Books information block;
- create the information block sections with the names the same as the book subjects;
- add books to the catalog.
- First, we create a new information block type: Bookstore (click Content -> Information blocks -> Information block types, click Add new type on the context toolbar). Enable the Use tree view to classify section elements option in the type properties.
- Next, create the new information block of the Bookstore type, and give it a name of Books(Content -> Bookstore, click Add information block on the context toolbar).
- Create sections in the information block: Adventure Fiction, Business & Investing, Children's Books etc. Following the operations performed, the structure will look as follows:
- Add elements to the created sections of the Books information block.
Publishing the catalog
Now we can start publishing our book catalog in the public section. You can use the visual components version 1.0 to publish information in the public section. You will find these components in the Catalog drop menu of the Information
Blocks group in the Components sidebar of the visual editor.
- Element filter form: displays the filter form containing the specified fields. By
using the filter fields, visitors can find elements (e.g. products) that satisfy their
- Element Top sections: displays the specified number of elements of a certain
information block section.
- Elements of all sections: displays the specified number of elements (products) of an
information block of the specified type (e.g. Product catalog).
- Sections with total number of elements: displays the list of all sections and
elements of the specified information block.
- Section elements in a table: displays elements of a section or subsection of an
information block in the table form.
- Section elements in a list: displays a list of elements of a section or subsection of
an information block.
- Catalog element details: can be used to display the detailed information on the
specified element of a certain information block.
- List of the compared catalog elements: allows a visitor to add information block
elements (e.g. products) to the element comparison list. The elements for collation may be
selected from different pages. Then, a visitor can click a button or a link to go to the
element comparison page.
- Comparison table: inserts a comparison table containing all elements to be compared,
as well as their properties. This table offers an easy way to compare the desired products.
- List of linked elements: displays a list of elements of any information block which
are associated in any way with elements currently being shown on a page. For example, you
can display a list of compatible accessories for a mobile phone.
You can also use visual components version 2.0 to publish the information in the public section. Besides the components listed above, there is a composite component that implements a full catalog section. We shall use it to publish the created information block.
The following instructions describe how to create a full catalog section. Visitors can view a full list of products of each section and the full description on each book.
First, we create a page and add the Catalog composite component to the page. Configure it by specifying the information block type, the information block whose elements will be displayed and other parameters.
Composite components enable us to create only one page physically to have a range of pages logically. A composite component with proper settings creates a full site section (in our example a full catalog section). On the demonstration site the Catalog composite component has the following parameters:
Here are specified parameters of a page where visitors can view elements of a particular catalog section, an element details view page and other parameters.
After saving the page, we will have a full book catalog in public section.
Following the operations performed, we will have the book catalog containing pages:
- table with the section elements;
Creating a photo gallery
This chapter discusses how to create a photo gallery for your website using the features provided by the Information Block module.
Note: you can use the module “Photo Gallery 2.0” to create the gallery for your website if your system edition provides such a module.
Creating the photo gallery
The process of creation of a photo gallery is similar to creating a product catalog described in
the previous chapter. Perform the following steps to create a photo gallery.
- Create a new information block type: Photo.
- Create an information block Photo Gallery and configure it.
- If required, create sections in the information block.
- Add images to the Photo Gallery information block (or to its sections).
Publishing the photo gallery
You can publish the photo gallery using the appropriate visual components. You use either components version 1.0 or components version 2.0. Components version 2.0 have wider functionality. Composite component Photo gallery enables you to make a full photo gallery section by making only one page physically. You will find this component in the Photogallery drop menu of the Content group in the Components 2.0 sidebar of the visual editor.
Let us create a photo gallery section using the composite component.
Create a new page.
Drag and drop the Photo gallery composite component to your page. Configure it by specifying the information block type, the information block whose images will be displayed and other parameters.
Specify the parameters of the component.
In the properties section, we specify the parameters of the pages that are to display a list of photos, detail view settings, top settings and other parameters.
As a result, the following pages will be created.
A Wiki — is a website area (or a dedicated website) whose structure and content is created and maintained by the website users using the website tools and functions.
Wiki is an ideal instrument for the creation of knowledge bases, to prepare requirements specification or other documents requiring simultaneous efforts of many people (which makes it, in essence, a perfect tool for teamworking).
Each wiki page features the commenting tools and the versioning control system. The former function enables users to discuss the content of a wiki page in-place. The latter provides means to track, control or undo changes the users make to the wiki page.
Wiki Module Features
The Wiki module empowers users with the following functions:
- Edit wiki pages in teamwork mode in the visual HTML editor, or using the standard Wiki markup;
- Automated tables of contents;
- Add images to the Wiki pages;
- Create tags and categories for the Wiki pages;
- Search for any information by category;
- Add comments to the Wiki pages (requires the Forum module);
- Keep the Wiki page change log (requires the Business Processes module);
- Compare page versions (requires the Business Processes module);
- Restore the Wiki page state to an earlier version (requires the Business Processes module);
- Use the standard search form to search Wiki pages (requires the Search module).
Wiki may operate as a separate entity of a website, or as a part of your social network (certain search function limitations apply, however).
Creating A Wiki Section
Introducing Wiki to the website is nothing different than adding other Bitrix Site Manager feature: just add the Wiki (bitrix:wiki) component to a website page.
Note. A dedicated information block type and an information block for storing the Wiki data must be created by the website administrator prior to adding the Wiki component.
Wiki makes use of the following terminology.
- An internal link is a hyperlink that is a reference or navigation element in a document to another section of the same document or to another document that may be on or part of the same website. Such links are commonly shown in blue color.
- A red link signifies a link to a page that does not exist in Wiki.
- An external link is a hyperlink to web pages outside this Wiki.
- Wiki markup (wikitext language) aids to quickly outline structural elements and hyperlinks in a wiki page.
- A category unifies semantically analogous wiki pages. Each page can be bound to multiple categories. Nested categories are possible.
- Tags are used to mark wiki pages for quick navigation.
- Version is a saved entry in the wiki page history.
- Current version is the most recent version of a wiki page visible to the users.
The Wiki Page Layout
A common wiki page has the following functional and visual areas.
- The context toolbar functions:
- History shows the available versions of a wiki page. This button is unavailable if the Business Processes module is not installed;
- Create: creates a new wiki page;
- Edit: opens a current page for editing;
- Delete: deletes a current wiki page. Note that this will delete the wiki page history as well. All the links to this page in other wiki pages will become unavailable (which means they will be visible as red links).
- Internal and/or External links.
- Red links to non-existing pages.
- Contents list: this block is added automatically if a wiki page has headings.
- Headings of various levels.
- Categories to which a wiki page relates.
- Tags added by a wiki page author. Tags cannot exist in social network wikis.
- Commentaries left by other users.
Creating A Wiki Page
If a user opens a new, virgin Wiki website, he or she will see nothing but a welcome page:
To create a first wiki page, click Create on the toolbar. This will create a new page and open it in the simplified visual editor.
The simplified visual editor has some special Wiki oriented commands unavailable elsewhere in the system.
Once you have finished typing the wiki page text, click Publish.
Creating A Red-Linked Wiki Page
To create a new wiki page to which a red link refers, just click this link.
Note. If you create a new page of a certain title by clicking the Create button, and there are wiki pages containing the red links to such a title, these links will be resolved automatically.
Editing Wiki Pages. Version History
Editing A Wiki Page
To edit a wiki page, just click the Edit button. The current page will be opened for editing in the simplified visual editor.
Note. Changing the wiki page title affects the wiki page URL. Consequently, all the existing working hyperlinks to such a page in other wiki pages will become red links.
You can track the history of changes of any wiki page and compare different page versions if you have the Business Processes module installed in your system.
To view the current page versions, click the History button.
To compare any two previous versions of a wiki page, select them and click Compare Selected Versions. The page comparison shows in red the text missing in an older version, and in green the text added to a newer version of the page.
To revert the wiki page text to a version currently being viewed, click the link Restore To Current.
Categories And Tags
Categories were introduced as one of the ways to classify the wiki pages. A category can have multiple nested child categories.
Categories can be created in the wiki page editor by clicking Specify Category. The wiki engine shows the wiki page categories after the wiki page text body. The Categories link itself is always visible even if a page is not attributed to any category. This link opens a list of available categories.
Each category has a corresponding wiki page. If no such page exists, it is shown as a red link, just like other non-existing wiki pages. To create a wiki page for such category, click the red link and then click the create it now link in the page text (rather than the Create button on the context toolbar).
To specify a parent category for a current one, click Specify category in the category page editor.
Unlinking A Category
Unlike many can think when they first see the categories editor, the categories page specify the parent categories of a certain category rather than children entities.
If the category hierarchy is incorrect or just needs adjustment, you have to unlink the categories and then define new dependencies.
To remove a parent category binding, open the categories page for editing and delete the text
Tags are used to search wiki pages using the conventional search functions.
Note: Tags are unavailable in the social network wikis.
You can add tags to a wiki page in the page editor. For reference purposes, the tag selector shows the count of existing wiki pages that are marked with a certain tag.
The Commercial Catalog module is an add-on to the Information Blocks module that
enables developers to create product catalogs, manage prices, discounts and mark-ups.
This chapter describes the module functions in deep detail, and gives examples explaining how to
configure and use the module.
Principal features and traits
The Commercial Catalog module functions on top of the Information Blocks module and
provides the following features:
- use information block functions and resources to create commercial catalogs of products,
services and digital content;
- manage prices, discounts and mark-ups;
- sell products, services and digital content in the web shop;
- sell access permissions to resources;
- export and import information about goods, orders, sales in the Froogle,
Yandex and CSV formats (the latter can be easily
configured at the export time);
- save export and import profiles for later use.
Important! A commercial catalog is created by applying special settings to a Product Catalog. Product catalogs are essentially information blocks, that is why the Information
Blocks module is required for the Commercial Catalog module to function.
The following notions are used with the commercial catalog.
- Price types. Examples of price types are wholesale, retail and exclusive prices. The system is able to display only those price types for which a certain user group has permission.
You can manage price types in the Price types form:
e-Store -> Commercial Catalog -> Price types:
- Mark-ups: the sum added to the base price paid for a product. The mark-up value is specified as percentage of the base price.
You can manage mark-ups in the Price adjustment form:
e-Store -> Commercial Catalog -> Price adjustment
: the system has a special base
price type from which other price types can be derived. For example:
Retail price = Base price + Mark-up
It is common to permit the site administrator only
to view base prices.
- Discounts and coupons: deduction made from the normal cost or purchase price. Can be defined as relative (percent) or absolute values.
Note: a coupon is a sort of discount. A distinctive feature of a coupon is the unique code assigned to it, unlike a discount which do not have any specific code. To use a coupon, a customer has to enter the coupon code.
You can manage discounts in the Discounts and coupons form
e-Store -> Commercial Catalog -> Discounts:
There is a special page for coupons:
Note: Currencies in which prices and price adjustments are nominated, can be
managed in the Currency module (Settings -> Currency).
To make an information block act as a commercial catalog, you have to enable the option Is commercial catalog of the required blocks in the Commercial Catalog module settings
Settings -> System settings -> Module settings -> select Commercial Catalog in the drop-down list:
If you plan to use your information block(s) for selling digital content, enable the Content selling options for these blocks.
Once an information block is converted to a commercial catalog, its elements become products. This adds a special area titled Commercial Catalog to an information block element editing form:
Here you can configure and set:
- different price types;
- conditions that will cause different price types to be applied depending on the quantity;
- quantity and weight of a product unit;
- discounts and mark-ups.
Catalog used to sell content also offer the Groups tab:
Here you can select a user group to which a visitor, who purchased the subscription for the paid
content, will be added. If the subscription is time limited, you can specify the required duration
in the Active period field. When the period expires, the subscriber will be removed from the
Example of converting an information block into a commercial catalog
In the following example, we shall set up the Phones information block that we have created in the previous chapter to function as a commercial catalog.
To make the Books information block act as a commercial catalog, enable the option Is commercial catalog in the Commercial Catalog module settings (Settings -> System settings -> Module settings -> select Commercial Catalog in the drop-down list):
First, we have to define prices at which we are going to sell products (phones).
- Create the retail price type and make it available to all visitors of the site:
- Create the wholesale price type. Make this price type viewable by administrators and members of the Partners user group:
Now that we have created our price types, we can view them in the Price types
Mark-ups are used to calculate the final price by adding the predefined sum to the base price:
Price = Base price + Mark-up
However, an important thing to mention is that mark-ups here can be positive as well as negative
values. In the latter case, a mark-up acts as a discount.
Create the following mark-ups.
- Without discount. Give it a value of 0%:
- Dealer discount. Set the value to -18,5%:
The mark-ups created will be added to the Price adjustment report:
Discount can be applied to a single product as well as to all products of the catalog or a catalog section.
As an example, create a month discount of 10% for Children's books (Desktop -> e-Store -> Commercial catalog -> Discounts).
Open the Restrictions tab and define the section to which the discount can be applied:
Also create a 10% coupon for Fantasy books:
Click the Restrictions tab. Generate the coupon code, and define products to which the discount can be applied:
The new discounts will be added to the Discounts report:
Setting product properties
Now we have to configure parameters of products of the Books catalog (Content -> Bookstore -> Books -> Element).
For each element, set the following parameters (scroll to the Commercial catalog area).
Publishing the catalog
For publishing the catalog, we can use the composite component Catalog. This component enables the user to display products and prices in the special way in the public section using a wide variety of component's settings.
Add the Catalog component to the page:
In the Properties section you can set all the component's parameters:
- Information type and inf. block for publishing.
- List settings where you define number of elements per page, sorting parameters, etc.
- Top and detail view settings.
- A group of settings Prices include:
- Price type: you can choose which price type to publish (base, wholeprice, retail, etc.)
- Show quantity range prices: if this option checked all the set prices will be displayed in the public section
- Show price for quantity: you can define a quantity of products price for which will be displayed
- Other parameters: URLs templates, Page address management, Cache settings, etc.
: if a discount is set for a definite product it will be shown in the public section.
Save the page. Now you can view the catalog in the public section.
The content selling technology is built upon the access permission assignment which is the basic principle of Bitrix Site Manager. Each user group is granted a unique set of permissions allowing their members to obtain access to the specific piece of information. When visitors buy a specific information, they are added to a list of members allowed to access the purchased content.
Hence, the content selling process comes to selling the user group access permissions. Access permissions may be sold for a definite period of time (subscription) as well as without time restriction.
Generally, the content selling process involves the following actions:
- creating a user group allowed to access the required information resources;
- enabling the user group access permissions to be sold;
- creating and customizing a commercial catalogue to be used for content selling;
- setting up the e-store;
- publishing the content to be sold;
- receiving and processing orders.
As an example, we are going to sell subscription for articles. The starting point will be creating the Subscribers user group. You can do this in the User Groups form (Settings -> Manage users -> User groups).
Click the Access tab, where you can assign permissions of the created user group to access the administration part of the system modules. Since members of the Subscribers group should have access to information of the public section only, leave the default setting.
Create an information block whose content we are going to sell:
Please note that here we define the site section in which the article view pages will be stored: /e-store/paid/.
Add elements to the created information block (Paid Articles):
Create another information block whose elements will act as products. We shall use this information block to sell content.
To make elements of this information block act as "sellable" products, enable the corresponding options (Is commercial catalog and Content selling) in the Catalogs tab of the Commercial catalog module settings.
Finally, on the Permission Selling tab, mark the user group whose members should have access to the paid content. In our case, we are going to sell permissions of the Subscribers group:
Next, add a new element to the information block "Selling subscription to access paid articles". Give it a name "1 month subscription":
On the Prices (ext.) tab, set the discount in such a way that it would apply for subscriptions over 6 months:
A new section (Subscription parameters) will appear on the Parameters tab:
Here you can set the following parameters.
- Payment type:
- One-time – means that a customer can buy the product only once. No further actions will be performed on the product.
- Recurrent – instructs the system that, when the specified period expires, a customer is to be billed again to renew the product usage.
- Trial – implies purchasing a trial version of the product (e.g. trial access). When the specified period expires, a customer will be billed to buy a full version of the product.
- Payment duration – Period of time on expiry of which the system will bill a customer again. This field should be filled for the payment types recurring and trial.
- Time unit of payment duration – The time unit used to define the payment duration (month, day, hour etc.).
- Trial for (only for trials) – If you have chosen a trial as the payment type, specify the full version here. When the trial period expires, a customer will be asked to purchase the specified product (full version).
- Silent renewal – For use with the recurring payment type. If this option is active, the order total amount will be calculated when renewing (subscription), but an order will not be created in the system. This option may be useful if small regular charges are to be drawn off the user internal account.
Additionally, if the catalog elements are used to sell content, the Commercial catalog section will also contain the Groups tab:
This tab defines a user group to which a user who purchased the paid content, would be added. If the subscription is time-limited, the Active period field can contain the required subscription duration. When the specified period expires, a customer will be deleted from the group.
Next, create pages that will display elements of the Paid Articles information block. Create a new folder: paid in /e-store/, and a new page index.php in it using the visual HTML editor. Add the component List of news to that page.
This component displays short descriptions of information block elements as links to detail.php regardless of permissions of a current user. If a user has enough rights to access the article contents, the link would bring them to detail.php; otherwise the authorisation form will be displayed.
Add the News detail component (Content –> News) to detail.php. Enable the option User groups allowed to view detailed description (Properties -> Additional settings).
Save both pages in the section specified in the information block preferences. In this example, the section is /e-store/paid/. A good idea is to add a link to index.php to the left menu.
Now configure permissions of the Subscribers user group. We shall restrict access to the details view page (detail.php) – make this page accessible by the group members, while other users will not be able to view this page. To change the permissions, open this section in Site Explorer (Content -> Site Explorer -> e-Store -> paid). The work area will show the contents of /e-store/paid/:
Open the file access inspector for detail.php by selecting Access in the menu action:
The paid access configuration is now completed. Let us take a look at the results ensued from our manipulations. This is how index.php would look like:
If we are a member of the Subscribers user group, we can view the whole, unabridged article:
Data export and import
You can use the Commercial Catalog module functions to export and import the contents of
information blocks configured to act as catalogs.
The system comes with the following export profiles preconfigured:
- CSV (new).
The following import formats are available:
- CommerceML MySql Fast;
- CSV (new).
Import/Export CSV(new) - this format is available for the Commercial Catalog module
version is 4.0.5 or higher. It allows export and import quantity-based prices, and also removes
restrictions on the number of merged tables containing product descriptions. What is more, this
new format allows specifying currencies for exchanging prices.
Frequently used export and import parameters can be saved as profiles. You can always call
the previously saved profile to perform the operation again.
You can add links to frequently used export and import profiles to the Control Panel menu, for faster access...
...or remove it from the menu.
Modern business stepped over beyond offices and stores a long time ago. We can even assert
that it has gone out of the window, and it is not to be considered an overestimation; for million of
users, who are your potential customers, spend their time on searching products and services in the
Internet by studying proposals in browser windows. Expand your business, offer your products and
services - you can do it is very easily with Bitrix Site Manager!
Bitrix Site Manager will help you create your web shop to sell products and services right
on the site. The e-Store module includes the following sections:
- shopping cart to which visitors can add products and services;
- ordering procedure;
- customer personal section where customers can review the ordered products and
services, and manage their profile;
- administration section (Control Panel) for setting parameters and managing customers'
In this chapter you will learn the fundamentals of an e-store that can be created using Bitrix
Site Manager. We shall place high emphasis on the web shop administration, configurable settings and
preferences; and will touch upon using a web shop in the public section.
Essential Steps To Perform To Configure Your e-Store
To make your web shop actually working, you will have to provide it with some data it requires.
- Configure the payer types;
- Create the product property groups;
- Add the product properties;
- Add locations;
- Optional: create location groups (unifying locations in groups facilitates configuring and using delivery services);
- Add the delivery services;
- Configure the payment systems;
- Configure the order statuses which will indicate order processing stages. The statuses are useful for the customers as well as the web store managers because they can easily tell what’s going on with an order;
- Optional: create discounts;
- Optional: create tax rates;
- Optional: configure affiliates.
Each of these operations are discussed in detail in the forthcoming lessons.
The module settings
Having installed the module (or the system), open the module settings page (Settings -> System settings -> Module settings -> e-Store).
The following fields require that you provide valid and correct values in them.
Other settings, as well as using affiliates, are described further.
The web shop settings
Configuring payer types
The system allows to create and use many different payer types. In the public section, a customer
is asked to choose their payer type at the first step of the ordering procedure:
Every payer type has its own properties to be provided when checking out, and its own payment system handlers. According to the type, a customer has to fill the corresponding set of fields at the ordering time. Payer types depend on the site. Customers can choose from different payer types on different sites.
Open the payer types page (e-Store –> Settings –> Payer types) and configure our payer types. The system comes with the two types preconfigured: private and legal entity.
Add a new type: small business.
After you click Save, the new type will be available in the list:
For each payer type, the table shows the number of properties that were created and assigned to
An order property is the input field (or control) that a customer has to fill (or select) when placing an order.
Configuring property groups
First of all, before you start creating properties, you need to elaborate on groups in which the properties will join. Grouping is used for displaying forms in the public section to enhance the visual aspect and user experience. For example, the Location group was created for the Legal entity payer type. This group contains 4 properties that a customer has to fill in:
To create a property group, open e-Store –> e-Store Settings –> Order properties –> Property groups.
Click New group on the context toolbar and create a new group (type Delivery address in the group name text field) for the Small business payer type:
Now we can create properties for this group. For example, create the Location property. Properties can be created here: e-Store –> e-Store Settings –> Order properties –> Properties.
Click New property and choose Small business in the menu - this will create a property bound to that payer type. The property creation form will open.
Fill in the form fields as shown below:
Consider the following remarks when creating a property.
- The field Name specifies the name of the field as it will be displayed to a customer.
- In the field Type, select the type of the control:
- The Required field specifies that a customer must provide a value in the field..
Note that fields whose option Use as... are required regardless of setting of this field.
- The Sorting index field specifies the "weight" of the property. You can use this field to set the order in which the fields will be displayed in the public section.
- If the option Include in profile is marked, the property will be added to a customer's profile.
A user profile
is a set of properties that, once provided, are saved and can be used in subsequent orders. It means that a customer will not have to fill in the same fields again and again on every order. Instead, a customer can choose one of the stored profiles:
Customers can edit their profiles in the personal section.
- In the Property group list, choose one of the property groups that exist for a current payer type. (Clicking on Property groups >> opens a page with all existing property groups).
- Use as location: specifies that the value of the property is the base for the calculation of delivery price. This option is enabled for LOCATION properties only.
You must create at least one property whose Use as location option is marked. Otherwise, a delivery service processor will not be able to run. We shall return to delivery services later.
- Use as tax location means, if marked, that the value of the property is the base for the tax rate calculation. This option is enabled for LOCATION properties only.
You must create at least one property whose Use as tax location option is marked. Otherwise, calculations will not include taxes. We shall return to this point later.
The other options include the following.
Configuring locations and delivery services
Bitrix Site Manager allows you to configure any aspect of product delivery:
- specify time and cost of delivery;
- stipulate the product weight and price allowable for a given delivery service;
- reorder delivery services by specifying the display weight, etc.
One of the most significant aspects that affect a delivery service is defining proper locations to which a given delivery service can convey goods. Let us study this matter thoroughly.
A location is geographical unit that stipulates delivery conditions. A location is a part of the full delivery address.
The Locations form (e-Store -> e-Store settings -> Locations -> Locations) displays a list of locations displayed to a customer from which they can select the appropriate delivery location. Later, the selected location will be used to: display available delivery services; calculate the cost of delivery; and form the final delivery address.
A common location is a pair Country / City. Additionally, you should provide a location without city for each country. This may be essential if a customer cannot find the appropriate pair Country / City.
Add a new location. The location editing form includes two sections:
It is quite obvious that creating many locations is a tedious task. The system provides a mechanism that you can use to load locations from a special file. Importing can be done in the Import locations section of the Locations form:
Click Browse to select a file with locations on your computer. You can have existing locations deleted automatically by checking the Clear locations before loading option.
Deleting existing locations erases all locations even if they appear in addresses of existing orders!
A location file should have the following structure:
The first row specifies the language (e.g. en for English), in which the names will be displayed in the Control Panel.
Other rows contain data to be imported. First, specify the country (a row starts with "S"). Then, specify all cities of this country (rows start with "T"), and so on.
Names should be specified for all languages existing in the system. Names in other languages will be ignored.
If an imported country already exists, it will be rejected. However, cities are always imported, even if they are present in the system. You cannot import abbreviated variants of names.
Upon importing, the table will display new locations:
Hence, locations are used to configure delivery services in the Control Panel; and when ordering in the public section.
Configuring location groups
Joining locations in groups can facilitate configuring delivery services. You can create a location group and bind all delivery services that can convey to those locations, to that group.
When a new location appears, or tariffs of any existing location change, it would be sufficient to add or remove a given location to/from a group. You can avoid editing all the altered delivery services.
Create a new location group and add some USA locations to it:
After you have saved the location group, you can proceed with customizing delivery services.
Configuring delivery services
Open the delivery services form (e-Store -> e-Store settings -> Delivery).
Every delivery service can depend on the allowable weight and price; and always depends on the location.
You have to ensure that your delivery services cover all possible options. For example, if you specify that a given delivery service handle orders only over $500, make sure that there are other delivery services for those locations that can handle orders below $500.
Also ensure that your delivery services can dispatch orders to all possible locations.
Delivery services depend on the site on which an order is made.
Consider an example of creating a delivery service:
The service By mail to Florida:
Note! Each payer type needs at least one property with the option Use as location enabled. Otherwise, a delivery service processor will not be able to run. This option can be enabled only for properties of the Location type.
The location selected by a customer will be used to choose an appropriate delivery service. Then, the system matches the order price and weight against those of each chosen delivery service, and selects the most proper one. If there are more than one service, a customer will be offered to choose the desired one.
The system selects and displays the most suitable delivery service:
Configuring the payment systems
A payment system is the means by which a customer can pay for their order: on-line payments, wire transfers etc. The system allow to create and use as many payment systems as you want. For example, the system comes preconfigured to use the following payment systems (e-Store -> e-Store Settings -> Payment systems):
Let us add a new payment system. Click New payment system and select the site to which the system will be added:
In other words, payment system is a subject of a current site. Depending on the site, customers will enjoy different payment systems.
The following figure illustrates the possible payment system parameters:
The first tab contains general parameters of the payment system. Other tabs reflect payer types defined for a given site. Each tab specify the payment system parameters for each payer type, individually. For example, the following picture shows parameters for the payer type Private 1:
These tabs has the following options.
- Applied to this payer type: if marked, the payment system can be used with a given payer type.
- Name: specifies the name of the payment system as it will be displayed to a customer.
- Handler: select here the script that the system will call to handle the payment system.
- Open in a new window: specifies that any result obtained from the script (e.g. printable invoice) will be displayed in a new window.
- Handler properties. This section is available if only the selected payment system handler provides custom properties that you can configure. You can show or hide the property section by clicking the link Show handler properties or Hide handler properties.
Payment system handlers
Different payment systems has different interaction protocols and interfaces. Sometimes, the interfaces can differ dramatically. For example, Payflow Pro requires a special SDK to be installed on a server; while generic banking payment system needs printing a hard-copy receipt. Therefore, payment system integration is performed via special PHP scripts - payment system handlers.
The handlers are created for each payment system and called immediately upon checking-out, or when a customer has chosen to repeat payment in their personal section. The handlers can display a printable receipt, or send data to a remote payment processor etc.
A common scenario of usage of the handlers are as follows.
- Copy all required handler files from /bitrix/modules/sale/payment/ to /bitrix/php_interface/include/sale_payment/.
Note that the custom handler storage folder /bitrix/php_interface/include/sale_payment/
is not mandatory. You can use any other directory, but you will have to specify it in the module settings:
- Edit files in /bitrix/php_interface/include/sale_payment/ so that they meet your requirements. Typical modifications could be: changing test usernames and passwords; adding a receipt stamp image; altering the receipt design etc.
- Add your custom handlers for other payment systems if needed.
- An offline payment system handler can display a receipt ready to be printed out.
This handler is a script that displays a document whose order parameters are properly inserted and formatted.
You can find an example of such handler in /bitrix/modules/sale/payment/bill/payment.php.
- A typical online payment system handler displays a form that sends data obtained from a customer to a payment collector. Examples of such systems are Assist, Authorize.Net, Payflow, WorldPay.
The design and fields of the HTML form completely depend on the payment system. Usually, you will find the detailed description of required fields in the payment system documentation.
You will find an example of an online handler in /bitrix/modules/sale/payment/paypal/payment.php.
As a rule, online payment collectors offer one of the following integration interface models (sometimes both):
- order parameters are sent to the collector site where a customer fills additional forms (e.g. provides credit card details) and performs the payment;
- a customer provides all the required parameters by filling in the payment form on the site; the handler builds a request to the payment collector; finally, the collector returns with the payment result.
The first option is the simplest in the view of integration. It is sufficient to create an HTML form that will send data to the payment collector, having provided the required fields. A good example of this approach can be found in /bitrix/modules/sale/payment/assist/payment.php.
The second variant can seem more sophisticated, but it is far more flexible. You can take a look at the implementation in /bitrix/modules/sale/payment/authorizenet/.
After a customer has placed an order, it can be viewed it in the Control Panel (e-Store -> Orders):
Depending on the user group permissions, a currently authorised user can perform different operations on the orders. For example, the e-Store administrators have full access to order processing. User group permissions can be configured to enable managers to view the order details, change the status, print receipts etc.
The order access permissions can be configured in the e-Store module settings (Permissions for orders tab), for each site individually.
The user access permissions can be customised on the Access tab.
The following access levels can be assigned to user groups:
- The Read only allows members of a given user group to view all information (client profiles, affiliates, orders, settings etc.) but not edit.
- Setting the permission to Manage orders enables users to edit the order parameters and client profiles. Any other information and settings are read-only.
The accessible subset of order parameters is defined by the order status.
- Full access means that all information and settings of all areas of the e-store are allowed to be modified. You are recommended to give this permission to the site administrator only.
The order statuses
The order statuses indicate stages of an order during processing. They serve as indicators that inform clients and managers about the current state of an order. You can create as many statuses as you need to reflect the order processing flow. For example: Accepted, Processing etc.
The status management form can be accessed here: e-Store -> e-Store settings -> Statuses:
The following two statuses are preset and cannot be deleted:
- N - initial status (the default name is Accepted), indicates that the order has been received by the e-store;
- F - final status (the default name is Delivered), indicates that the order items has been paid and delivered to the customer.
The following figure shows the order editing form:
Consider the following when editing the status parameters.
- Code is a unique abbreviation of a status, in the form of a single letter.
- The Sorting index field specifies the status weight, which defines the position of a given status in the list.
- The status Name and Description must be provided for each language in the system.
- The Access permissions section contains user groups for which the Manage orders access level is set in the module settings. This allows to fine-tune the order processing options for these user groups.
In the example, the e-store managers is allowed to manage orders. These two groups are displayed in the status editing form. You can allow or disallow them to toggle the order flags (cancelled; delivered; paid).
User groups with these permissions can change the flags on the order details page, which can be accessed by selecting the View order details command from the action menu of a required order in the Orders form:
Assume that an order has the Accepted status. Traits of the active status (the one in which an order is) define the permissions that are currently applied to an order.
In the example, all possible options of the Accepted status are enabled for the e-Store Administrators user group. For example, this allows an administrator to cancel an order by clicking Change flag:
This opens a new field in which the administrator can describe reasons of cancellation.
Click Change to actually toggle the flag state. Finally, click To view mode to revert the form back to the original mode.
Similarly, you can change the payment state in the Payment section:
Or the Delivery allowed flag in the Delivery service section:
| ||Bitrix Site Manager enables developers to use custom order view forms. A custom form can be created nearly in the same way as an information block element editing form. When a form is ready, specify its address in the Custom order view form field of the e-Store module settings.|
Printing order documents
You can prepare documents (bills etc.) for printing by selecting the corresponding command in the action menu:
Clicking this item (Print) displays a from that displays information about the order and the purchased products (date, site, status etc.)
The Print documents
form contains fields that have the following meaning.
- General order information: ID; the order date, site and status.
- Order items. The Include options allows to choose items to be printed. Some document templates are able to print only the required order items, for example: Invoice. If the selected template can print only the entire order, it will render all items regardless of the selection.
Note that the Quantity field can be modified. You can use this to print documents just for a part of the purchased items. For example, a customer ordered two phones, but you want to print the document only for one. Type the required quantity in this field, choose the required template and click Print - the system will create a document for the specified volume.
- The type of document to be printed. You can print multiple documents for an order. To do so, select the required templates while holding the Ctrl key down.
To begin printing, click Print. The printout documents are opened in new windows. Some document templates allow to edit text information in them. If so, click Tab to highlight editable fields.
Files with the preset templates can be found in /bitrix/modules/sale/reports/.
If you want to modify any of the preset templates, copy the required template to /bitrix/admin/reports/ and edit it. Do not edit standard templates directly.
You can create discounts that can be applied to orders depending on the order price. Discounts can be active during the certain period of time, or permanent.
Discounts can be managed here: e-Store -> e-Store settings -> Discounts:
This table displays key information on a discount. To create a new discount, click Add a new discount on the context toolbar. The discount editing form will open:
- Each site has individual discounts. Therefore, select the site to which you want to add the discount.
- Apply to orders with price: here you can specify the price range of an order (without the cost of delivery) to which the discount can be applied. You can specify only one boundary. In other words, a range of $1500 to 0 means that a discount will be applied to orders whose price is $1500 or higher.
- Active period: as with the previous field, you can specify only one date. If both fields are empty, the discount is eternal.
- Discount value: can be a percent value (select % in the drop-down list), or it can be specified in the currency of the order price range (select empty item in the drop-down list).
- Only the discounts whose option Active is marked can be applied to orders.
- The Sorting index field specifies the position of a given discount in the list. But what is more important, the system uses this value if more than one discount can be applied to an order: a discount with the lesser sorting index comes into play.
In the public section, the discount is activated during the ordering procedure. The discount amount is displayed in the order contents form:
In this example, our discount has been applied because a customer's order exceeds $500.
The system is able to calculate and apply taxes during the order calculation. The taxation procedure respects the following rules:
- individual taxes exist for each site. You can define as many taxes as required;
- tax rates can depend on the payer type and location. Tax rates are always defined in percentage terms. Tax rates can be included in price;
- tax exemption rules can be defined. This is done via applying tax exemption conditions to the user groups whose members you want to exempt from taxation.
Taxes can be configured in the tax management section (e-Store -> e-Store settings -> Taxes -> Taxes). This form displays all taxes that are currently defined in the system. Remember that each tax is the subject of the current site: for example, only the taxes that are defined for a Demo site will be available on that site. For example, you may need to create VAT (Value Added Tax) for a Demo site. The tax editing form will contain the following information:
The following information is essential and you must provide it as accurate as possible:
- select the site for which the tax is intended;
- type the name of the tax;
- specify the tax mnemonic name. This field is generally used by developers;
- give the tax a description.
Setting tax rates
Tax rates are defined in the tax rates management section (e-Store -> e-Store settings -> Taxes -> Tax rates). Here you can specify rate values depending on the customer's location and payer type (optional).
The tax rate editing form:
The form has the following fields.
To a given order, the system applies all taxes that meet the following conditions:
- the tax is bound to a site on which an order is currently being performed;
- the location selected by a customer matches the location specified in the tax settings;
|Note! Every payer type should have a property with the option Use as tax location enabled. Otherwise, tax rates will not be resolved.|| |
- the payer type assigned to the tax rate matches the payer type selected by a customer when making an order, or the tax rate is not bound to a specific payer type;
- the tax rate is active.
If you need to create a tax rate for the entire country that has multiple locations, a good idea is to create a location group that would include all locations of this country. Then, select this location group when creating or editing a tax rate.
If more than one tax rate can be applied to a given order, the following rules apply.
- Tax rates are applied consecutively in the order as declared in the Tax priority field, starting with the least.
- A tax rate is applied to a value to which other taxes with lesser priority has already been added (the compound interest appears).
- If more than one tax rate with the same priority exists, these tax rates are summed up and applied atomically.
Consider the following example. Assume a customer buys a product for $25, and there is a discount of 2% for orders over $20. Let the following tax rates apply to this order:
- Tax 1: rate 18.5%, priority 100;
- Tax 2: rate 2.7%, priority 100 (the same as Tax 1);
- Tax 3: rate 3%, priority 200.
In that case, the final discounted price would be $24.5 (25 - 25 * 2 / 100).
Tax 1 amounts to $4,53 (24.5 * 18.5 / 100).
Tax 2 amounts to $0.66 (24.5 * 2.7 / 100). After the Tax 1 and Tax 2 have been applied, the order price would be $29.69 (24.5 + 4.53 + 0.66).
Tax 3 amounts to $0.89 (29.69 * 3 / 100).
Having the discount and all taxes applied, the order price is $30.58 (29.69 + 0.89). And now the cost of delivery can be added.
In the public section, the taxation information is shown during the ordering process:
You can use this function if some of your customers can be tax exempt.
Create a special user group, for example: Tax exempt. Do not give that group any special permissions; just leave them as is.
Then, open the tax exemption form (e-Store -> e-Store settings -> Taxes -> Tax exemption). This page displays all user groups defined in the system. Click the action menu button of the tax exempt user group, and select Modify tax exemption. In the tax exemption editing form, select taxes that will not be levied on members of that group.
Internal customer accounts
Internal customer accounts. Transactions.
The internal customer accounts can make selling content, products or mp3 files even more comfortable. The core idea of user accounts is that a customer can top up their balance by any possible method, and then use their budget to pay for content or products.
The Internal user accounts form displays all available accounts and shows the balance of each account.
You can create a new account here (e-Store -> Customer accounts -> Accounts) by clicking Create a new account. This opens an account editing form:
- User: only the registered uses can have internal customer accounts. Click and select a user from the list.
- Account amount: Type the initial amount, and select the account currency.
- Notes: leave any notes here, if required.
- Reasons to change the amount: Type here the reason why the amount has been changed.
To edit an existing account, select Edit account parameters in the action menu:
This will open the account editing form which is slightly different now:
A new option is available for existing accounts: Unlock account. This option controls the account status, so administrators can quickly enable or disable customer accounts.
Customer accounts can be modified manually or automatically (e.g. upon payment). Any change of account amount is a transaction
A transaction is the process that takes place when the amount of an account changes: withdrawal or replenishment of money. The system records all transactions; you can view them here (e-Store -> Customer accounts -> Transactions):
Administrators can perform transactions manually by clicking Add transaction on the context toolbar, which opens the transaction editing form:
Using credit cards
To provide the maximum operability of the order handling process, the system is able to receive payments via credit cards. It is clear that credit card operations must as secure as possible. The system uses the most robust encryption mechanisms to prevent any misuse or malicious use of credit card information of your customers. You can find the credit card security options in the e-Store module settings:
- Security of the credit card operations are ensured by using a unique password, and choosing the required algorithm for the credit card number encryption.
If you fail to provide the path to the encryption password file, the system warns you by showing the corresponding banner (in red). The best way to keep this file safe is to store it outside of the site root directory, but make it available for reading by the PHP interpreter at the same time. For example: d:/projects/siteman/bitrix/modules/sale/install/data.php. In this file, you have to define a special variable $pwdString whose value would be the credit card number encryption password.
Important! A strong password must contain letters and digits and have over 20 symbols.
The system comes with the sample password file (the password is initially empty). This file can be found in /bitrix/modules/sale/install/data.php.
$pwdString = "";// Provide password here (at least
// 20 letters and digits is recommended)
- Choose the encryption algorithm. RC4 does not require any additional modules. AES and 3DES requires the Mcrypt PHP module to be installed.
Encryption algorithms are mutually incompatible. You will not be able to change algorithm after the real credit card numbers appear in the database.
You can add credit card data here: e-Store -> Customers accounts -> Credit cards. Clicking Add new credit card opens a credit card information form:
- User: a credit card is bound to a registered user. Choose one of the registered users by clicking .
- Payment system: choose the payment system that will be used to process payments performed with a given credit card.
- Credit card type and Currency: choose the credit card type and the currency in which payments can be performed.
The credit card number is verified using the algorithm specified by the card developer (Visa, MasterCard etc.) The credit card number is not a set of random digits; an attempt to save a record with an incorrect number throws a warning message:
- Currency of amounts: if you provide the maximum and/or minimum amounts that can be withdrawn from the card, choose here the currency in which the amounts are specified.
Your site can be a point of sale not only for your products and services, but also any content. The subscription process is similar to product purchasing with the only difference that the Delivery step is omitted.
Upon completion, an order becomes added to the order list and can be viewed on the Orders page. After a customer has paid for an order, its status changes to paid (or it can be changed by an administrator) so the delivery (in the form of download etc.) becomes possible. Now, a new record appears in the Subscription renewal table (e-Store -> Renewal).
The access to content is purchased for a certain period. Upon expiration, the subscription can be renewed in different ways, depending on the settings of the purchased content. The settings discussed below refer to the product settings. To view them, click Content and select a product (in the demo site, you can open Content -> Content selling -> Paid content subscription).
- If the options Payment type is set to Recurrent, the options Payment duration and Time unit of payment duration are specified, and the option Renewal without ordering is not active:
In this case, when the subscription expires, a new order will be created automatically. The system will attempt to pay for the order (renewal) from the internal customer account (or the customer's credit card if it is registered). The system sends will notify a customer about the new order by the e-mail.
- However, if the option Renewal without ordering is active, the system will try to perform payment silently, without creating a new order. If payment fails to complete successfully, the subscription will not be renewed; a customer will have to visit the site and buy the subscription explicitly.
You can watch the customers' subscriptions on the Subscription renewal
page. To edit a subscription, double-click it or select Edit parameters
in the action menu. To add a new subscription manually, click Add
on the context toolbar.
Assume you have created a new subscription. After a customer has bought the subscription and it has been automatically renewed, the subscription renewal editing form will change as shown below.
Hourly subscription renewal
You can see that the customer's subscription has been cancelled. The option Renewal without ordering is not marked, therefore the system renewed the subscription automatically by withdrawing money from the internal account. When the account has ran out, the system cancelled the subscription automatically.
Bitrix Site Manager is equipped with anything you may require to build and manage an affiliate network.
An affiliate is a special kind of a commercial partner in the Internet that does not directly sell products but publishes a link to a merchant's product page on a web site. If a customer was driven by that link and purchased a product, the affiliate gains a commission indicated in the contract.
Bitrix Site Manager can also help you build multi tier affiliate networks. In practical terms: if an affiliate "A" attracts other affiliates ("B", "C", etc.) to sign up for the same program using their sign-up code, all future activities by the joining affiliates "B" and "C" will result in additional, lower commission for affiliates "A". Commercial relationships and their profit are regulated in the Tiers form.
All tasks related to affiliate management are concentrated in one section: e-Store -> Affiliates.
Configuring general affiliate policy
These properties can be customized in the e-Store module settings:
A user that has registered as an affiliate receives a special link that has to be published on their site. Visitors who click that link are considered attracted by the affiliate. The system inserts a special URL parameter into that link whose value is the affiliate code.
The affiliate plan stipulates commission that an affiliate will gain for attracted visitors and sales. The plans can be based upon the quantity of items sold or the amount of sales. You can set the partitioning in the module settings, the Range affiliates by field.
The selected mode affects the affiliate plan editing form. It means that you have to decide which mode to use before you start creating plans for your affiliates. You must not change the selection after you have created yet one plan; otherwise, your affiliates will be calculated incorrectly.
You can manage affiliates in the corresponding form (Affiliate tariff plans, e-Store -> Affiliates -> Plans). Click New plan to create a new affiliate plan. If the settings read to partition plans by the number of sales, the editing form will look like the following:
In this form:
- ID and Last modified appear only when editing an existing plan.
- Site: each site has its own set of affiliate plans.
- Active: check this option to allow affiliates to use this plan.
- Tariff (commission): the commission can be specified as percentage or in any currency defined in the system.
The Product groups tab allows to define product groups to which the plan will be applied. This operation is optional and is only required if you want to restrict the plan to certain products. Click Add to show fields to define a group:
If you have chosen to partition plans by the amount of sales, the plan editing form is slightly different:
As you can see, the field The plan is active for sales over (pcs.) changes to The plan is active for sales with amount over (in the site base currency).
The site base currency is defined in the e-Store module settings (the Permissions for orders
So, the complete and correct affiliate business solution should have plans that would entirely cover all possible options. For example:
You can manage your affiliates in the corresponding form (e-Store -> Affiliates -> Affiliates).
Clicking Add affiliate in this form opens a form in which you can specify parameters of a new affiliate:
Note the following when editing the affiliate parameters.
- Each site has a private set of affiliates.
- Only a registered user can become an affiliate. Therefore, you have to select an existing user by clicking the button
- Unless you create or edit a first-tier affiliate, choose the parent affiliate in the Registered via affiliate field.
- In the Plan field, choose one of the affiliate plans. This drop-down list contains all plans defined for the current site.
Note that, if you want to force the selected plan to be applied to an affiliate whatever the current sales conditions and other plans are, check the Fix plan option (fix the plan).
Consider the following example. Assume there are two plans: plan A (5% for 3 or more phones), and plan B (10% for 5 or more phones), and an affiliate with plan B attracts a sale of 10 phones. If the plan is not fixed, the affiliate would earn 5% (the plan which is most favourable to you). However, if you fix the plan B, the affiliate would earn 10%.
- Active: this option enables or disables an affiliate.
- The fields: Paid amount, Pending amount, Last calculation date are filled in automatically upon the affiliate calculation.
- The fields: Affiliate site and Affiliate description are optional.
Tiers build the multilevel affiliates. This allows affiliates earn on sales driven by their child affiliates.
|For example: affiliate C registers via affiliate B; and affiliate B in its turn - via affiliate A. Let the commission for the first tier be 10%, and for the second be 5%. If affiliate C earns $1000, affiliate B would earn $100 ($1000 * 10%). Affiliate A would earn $50 ($1000 * 5%).|
In other words, if Rick Astley drives Mike Cooper to the site, Rick will earn not only from his sales, but also from Mike's sales. The amount of Rick's earnings from Mike can be specified in the tier 1 tariff field. Mike's dependency on Rick is specified in Mike's settings:
Now let us create tiers: e-Store -> Affiliates -> Tiers. Click New tiers to open the editing form:
Note that Bitrix Site Manager implements affiliate earning based type of tiers. It means that a zero tier affiliate receives earnings from their child affiliates calculated as percentage of earnings of the latter. In the example above, Rick will earn 5% of Mike's revenue.
Currently, you can build only one tiers.
If you fail to fill in the form fields, or set them to zero, all affiliates will receive profit only from their own sales: multi-tier affiliates will not function.
A user registered as an affiliate is given a link to publish on their site. This link contains a variable (e.g. "partner
") specified in the e-Store module settings whose value uniquely identifies an affiliate, for example: www.testsite.ru/index.php?partner=1
. The system reads the URL and, if it contains partner
, adds a certain amount of money to a specified affiliate.
You can calculate the profit of all affiliates and perform payment in the Calculation form (e-Store -> Affiliates -> Calculation):
The usage of this form has some peculiar points.
The Currency module manages all currencies that your system use (or can use). The
module functions are the following:
- currency management;
- maintaining price display formats for each currency;
- currency rate storage (including downloading rates from the Internet).
module is required by the Commercial Catalog
The on-line store on your site may happen to sell foreign goods. As a rule, the price for
such items is calculated using the purchasing price. The latter is usually set in a foreign
currency. However, the legislation requires that calculations of all trading operations be
accomplished in the home state currency. The Currency module is used to simplify
operations with such items and their prices.
Prices can be specified and displayed in any of currencies available in the system. However,
payment documents (receipts etc.) will have all values specified in the base system currency at
the current rate.
The Currency module is designed to manage currencies and their exchange rates. This module
is required for proper functioning of the Commercial catalog and e-Store modules. You
can manage currencies in the Currency form:
Settings -> Currency -> Currencies
Note: there is always a base currency which is one of the existing currencies. Rates of other currencies are calculated relative to the base currency.
Each currency has the following parameters:
- symbol identifier (e.g. USD, EUR);
- face value (here: the value of a currency unit);
- default rate (used for conversion unless newer rates exist in the Currency rates form);
- currency name and format for each language in the system.
Currency exchange rates
The Currency Rates (Settings -> Currency -> Currency rates)
form is used for what it speaks: it manages the currency exchange rates. This form helps you easily
maintain list of exchange rates for all required dates; that is, you can keep a log of the currency
exchange rates. This information can help you later, for example, when reviewing orders for a specific period.
When converting currencies for a current date, the system takes the newest exchange rate. If the rate is not found, the default rate will be used (from the Currency form).
In the currency rate details form, you can obtain the exchange rate for the specified date (from the Central Bank of the Russian Federation) by clicking Query:
Examples of using currencies
Assume that you run a web shop and want to display prices in USD and euro.
First, create the required currencies (choose USD as a base currency):
After you have finished creating currencies, you can view them in the Currencies report:
Next, set rates of the currencies for the current day (relative to the base currency):
Now, prices in your shop can be displayed in any of the created currencies:
: the system provides a very useful visual component that you can add to your pages to display a table of currency rates:
The Web Forms module can be used for:
- storing comments or queries of site visitors;
- storing and searching site visitors' callback forms;
- processing of information in forms.
This chapter discloses the principles on which the module is built, and gives examples explaining how to create and publish a web form.
Main features and functions
With the Web Forms module, you can create an unlimited number of web forms, manage and publish them.
The main purpose of web forms is to provide site visitor feedback. For example, you can use web forms to:
- fill and store surveys and questionaires;
- receive queries from site visitors (e.g. requests for products, applications for meetings etc) and process any other data that requires using forms to input information.
The system stores information, obtained from visitors via web forms, in the database. You can specify an e-mail address to which a notification will be sent each time a web form is posted.
Assume that you have placed a job application form on your site:
Every time the form is completed, a new application is registered in the system:
and a notification is sent to à responsible person (e.g. personnel department manager) via the e-mail.
Note: e-mail dispatch parameters are configured in e-mail templates, which is only available in the advanced editing mode.
Administrator can configure a web form and its results in such a way that they will be accessible only by members of a certain user group. For example, site visitors can be permitted to modify their CV's.
Note: statuses are only available in the advanced editing mode.
The Web Forms module tightly integrates with the Web Analytics module which allows to analyse web form completion dynamics and obtain information on visitors who posted forms (each web form can have its own event types).
Managing web forms
The concept of web form management involves handling the following entities:
- Web forms: forms published on site pages;
- Question: an aggregate of the question text and fields intended to receive user input;
- Result: answers to web form questions;
- Fields: store information (processed on unprocessed) obtained from a web form (upon form completion);
- Statuses: Each form result can be assigned a definite status, for example: accepted, published, rejected etc. For each status, you can assign different access rights for user groups and for the result creator, individually.
The design of a web form editing page depends on the chosen editing mode. The system offers the following editing modes: simple and extended
You can choose the web form creation and editing mode on the module settings page (Settings -> System settings -> Module settings -> Web forms).
The simple mode is for common tasks such as creating a feedback form. This mode does not imply using fields and statuses.
Note: in the simple mode, status is assigned to web form results automatically and cannot be viewed by users. Status assignment is only required to allow switching between editing modes.
The extended mode, in addition to features of the simple mode, allows to configure statuses of results and create computed fields.
Creating and editing web forms
You can manage web forms in the Forms page (Services -> Web Forms -> Manage Forms):
To create a new form, click the Create button on the context toolbar. You can edit a web form by selecting Modify in the action menu or by double-clicking the appropriate table row.
Each web form is added to the Control Panel menu which allows to manage a required form and view its results:
Other entities (questions, statuses etc.) can be managed in the web form settings.
Creating web forms. The simple mode
In this lesson we shall create a Job Application web form in the simple mode.
- To begin with, switch to the simple editing mode. For that, enable the option Use simple editing mode in the module settings:
- Then, open the web form management page (Services -> Web Forms -> Manage Forms). Create a new web form by clicking Create on the context toolbar. This will open a web form editing page:
Here you can:
- enter the web form title;
- set titles of menu items as they will appear in the Control Panel menu, for each language in the system. By clicking these menu items, you can open the web form result page;
- choose sites on which the web form will be available;
- create form template using the visual editor;
- provide event identifiers for use by the Web Analytics module;
- assign access permissions for the web form and results.
Web form completion results can be sent via the e-mail. In the simple mode, you can generate a template which will be used to create and send reports. To do so, check the Send form results by e-mail box.
The template will be generated right after the web form is saved. By clicking the templates link, you can view the list of templates and edit them if required.
- Save the form. Now it is displayed in the Forms report table.
- The next step is to create questions for our web form. You can start creating questions by clicking the plus sign (+) in the Questions column.
For example, you might consider adding the following question to the Translator web form:
Creating web forms. The extended mode
Creating a web form in the extended editing mode requires the following actions to be performed:
- creating a web form;
- creating questions for the web form;
- creating and configuring web form result statuses;
- (optional) creating computed fields.
Creating and editing a web form
In addition to options that are provided in the web form editing page in the simple mode, the extended mode offers the following fields.
- Symbolic identifier of a web form:
Symbolic identifiers are used by developers to identify a web form in the program code of visual components that display web forms in the public section.
- The e-mail templates are created in the Advanced tab by clicking the create link:
Note: The create link is displayed only when editing an existing web form. Therefore, you have to save the web form by clicking Apply before generating a e-mail template.
By clicking View template you can view and edit the generated template in a new browser window.
Note: Each web form can have as many e-mail templates as required.
However, to enable sending reports using the created template, we have to bind it to the web form:
- save changes by clicking Apply. The created template will be indicated beside the E-mail templates field;
- select the required template(s) by checking the appropriate boxes. Click Apply (or Save) to save changes.
- Additional access permissions levels for the web form and results:
- edit own result according to its status;
- edit all results according to their statuses.
You can create questions in the same way as in the simple editing mode.
To create web form statuses, click the plus sign in the Statuses column in the web form report table:
Among other parameters of a status, you can:
- define that the status is to be set for all new results by default;
- assign user group access permissions to results in a certain status.
, create two statuses for results of the Translator
- Enqueued, which means that a job application form is received by the personnel department; this status is assigned to all results by default. While a web form is in this status, applicant can edit their CV.
- Accepted. Indicates that the CV was examined and enrolled to the personnel department database. After the form obtains this status, it cannot be edited by an applicant.
Members of the Personnel Department user group is granted a permission to move forms to the Accepted status.
Creating a web form template
You can create templates for your web forms for future usage. To facilitate creating templates, you can click the Form template tab where you can develop your own template or use the default one.
If you use the default template, your web form would display as usually:
Custom web form templates are created using the visual editor:
In this case, a web form based on the custom template would look as follows:
There are two methods to create templates.
Let us create a template and questions for a web form. We shall use the components from the Form elements panel.
The Additional elements menu contains fully-functional controls that you can use in your forms:
The component Form title displays a web form title specified in the component settings. The component Form description can be added to print the description for a web form. In order to notify a user about errors they can make while filling in the form, you can add the validator component Form errors that displays errors, if any. If you need to display some message to a user upon form completion, add the component Form response message. It will display the specified text to a user after clicking Submit (or similar button), e.g. "Your request has been sent".
The New form fields menu contains the following components.
All these components can be easily configured. Consider an example of web form field creation. Choose a field (component) that matches the nature of the intended question best, and add it to the page being edited. For example, use the Date component where you would expect a user to enter the date. Configure the component in the property inspector:
String identifier is generated automatically; it uniquely defines the form field. The identifier name is
new_field_randomnumber. You can type any other name here, but you must ensure that it is unique.
Redefine the new field name to birthdate.
Title (question text) specifies the text displayed beside the field:
- for Input field caption ;
- in the web form result table and filter;
- when displaying web form results or errors.
In our example, type Date of birth here.
Uses HTML – defines whether HTML are used in the title.
Required – if checked, a user must provide an answer (or any other required value) in this field. Enable this option for the Date of birth field.
Show in HTML result table – specifies that an HTML table of the web form results includes a column containing values of this field (in the public section).
Show in Excel result table – the same as with Show in HTML result table, but for Excel tables.
Field type – indicates the type name of a given field; read-only.
Answers – field values. The intention varies depending on the field type:
- default value and value length: for text, date, email, url, password, image, file;
- number of columns and rows: for textarea;
- options, the order and the default selection flag: for radio, checkbox, dropdown, multiselect.
Now, add the Input field caption component and set its properties (the identifier and style).
Identifier: here you have to select the identifier of the field for which the text label will be displayed. In our example – birthdate.
To define the label appearance, you can choose the required CSS style in the Style list.
Since we use the component (Field title) to render the text label, the common visual cue for mandatory fields (asterisk, *) will be added automatically without having to use the component "Required" sign .
Alternatively, you can enter the field title directly in the editor. For example, add the Date field and set its properties as follows:
The text Date of birth will be displayed in the public section, but the question “When were you born?” – in the question list:
As we want to make this field mandatory, add the component "Required" sign so that the asterisk will be rendered:
To enable users post or cancel the form, add the following buttons: Send , Apply , Cancel .
: if you have enabled the option Use CAPTCHA
when creating the form, remember to add at least one CAPTCHA
component to the form. Otherwise, this option will be reset when saving the form:
You can find the detailed information on using and configuring the components in the documentation.
Publishing a web form
You can publish web forms (that is, display them in the public section) by using visual components version 1.0 and components version 2.0.
For managing, components version 2.0 are more convenient. You will find these components in the Services group in the Components 2.0 sidebar of the visual editor:
| Web Form (bitrix:form) ||Composite component. Using this component, you can physically create only one page and in public section it will give you a page for web form completion, a page with a list of results, a page for results editing etc. |
| Web Form Completion (bitrix:form.result.new)||Simple component. Helps to create a page for web form completion |
| List of results (bitrix:form.result.list)||Simple component. Creates a page with a list of results. |
| Result editing (bitrix:form.result.edit)||Simple component. Creates a page for result editing|
| View result (bitrix:form.result.view)||Simple component. Creates a page with web form results. |
As an example, let us publish the Translator web form in the About section (folder /about/) of the company site. We shall give visitors a chance to edit their results. Also we shall create a page with a list of web form results.
For convenience, we shall save all pages related to the web form in the folder /about/job/translator/ (you have to create it beforehand).
- Create a new page in /about/job/translator/ in the visual editor.
- Set the page title to Translator;
- Add the component Web Form Completion to the page;
- In the component settings, choose a required web form, and specify paths to pages where the web form results can be viewed and modified.
For example, you can create a result_list.php page in the current folder (
/about/job/translator/) for viewing the completed web forms. Type result_list.php in the Result list page field. To edit a job application, we shall use the page result_edit.php from the same folder.
Note: you will have to create these pages later.
- Save the page and give it a name of index.php.
- Create a page to display the web form results. After a visitor have finished completing the form, they will be transferred to this page.
- Create a new page in /about/job/translator/.
- Set the page title: Your CV.
- Add the List of results component to the page.
- Configure the component by specifying the new result page (index.php), the result view page (result_view.php) and the result editing page (result_edit.php).
- Save the page.
- Next, create a page where the result details will be displayed (/about/job/translator/result_view.php) and place the component View result in it.
Set the page title to CV Details.
- Finally, create a page /about/job/translator/result_edit.php where a selected result can be edited. Add the component Result editing to the page.
Set the page title to Edit CV.
Here's what you get in the end.
- Web form completion (in other words, new result creation) page:
- Page with a list of web form completion results
- If you have created the web form in the simple mode, applicants can access their own CV's
- For the extended mode, applicants can access their own CV's in the Enqueued status
- Web form result view page
- Web form result editing page
Another way to get the same number of pages in public section is to use a composite component - Web Form.
It is a good idea to add links to the web form completion and result view pages to the pubic section menu so that visitors can post and edit their CV's .
Publishing a web form - view movie (Flash)
The level of security provided by the standard distribution package is sufficiently high. However, the implementation of a web project usually requires component customization and developing custom tools whose security is not always tested and thus cannot be trusted. The Proactive protection
module is an important part of the security subsystem and significantly strengthens web project security.
The chapter describes general operations required on an administrator’s side to configure the Proactive protection module.
A Proactive Protection is a complex of hardware and software solutions and organizational measures within the concept of security aimed to broaden the idea of web application threat immunity and possible reaction to threats.
The module offers the following protection features:
- one time password technology;
- session protection technology;
- proactive filter;
- system integrity control;
- phishing protection;
- web antivirus;
- data encryption.
Any Bitrix Framework based web site is always preconfigured for the use of the basic protection level. However, you can improve the site security significantly by selecting one of the Proactive Protection module presets:
Remember that all the security levels are inclusive, which effectively means that you have to set the parameters of the standard level prior to configuring the higher protection levels.
The Security Control Panel page (Settings > Proactive Protection > Security Panel) shows information on a current security level. For each level, there is a table of parameters and values. Security Control Panel shows recommendations on changing parameters to the recommended values, if necessary.
If an incorrect value has been specified for a parameter, the Recommendation field will show a useful hint about it.
Standard security level
Entirely all parameters of the standard security level should be configured properly so that a web site runs well protected.
Note: if you fail to configure the standard level properly, the basic protection level takes effect with respect to parameters of other protection levels.
Proactive Filter and Exceptions
The proactive filter (Web Application Firewall) protects the system from most known web attacks. The filter recognizes dangerous treats in the incoming requests and blocks intrusions. Proactive Filter is the most effective way to guard against possible security defects in the web project implementation. The filter analyzes entirely all data received from visitors in variables and cookies.
You can enable or disable the Proactive filter at Settings > Proactive Protection > Proactive Filter using the Enable Proactive Protection button (or Disable Proactive Protection).
If required, you can set the proactive filter exceptions; this will cause the proactive filter to not be applied to pages matching the wildcards on the Exceptions tab.
Note: the standard protection level implies that the proactive filter is enabled and no filter exception is defined.
The actions the system undertakes in response to the intrusion attempts are configured on the Active Reaction tab.
Select the required action to respond to attacks:
- Make Data Safe – dangerous data will be modified; for example: sel ect will replace select.
- Delete Dangerous Bits – dangerous data will be removed.
- Skip dangerous data – no action will be performed.
Add Attacker’s IP Address to Stop List – dangerous data will be altered and a visitor will be blocked for the period specified (Add to stop list for (min.) parameter).
To log the intrusion attempt events, enable the corresponding option.
Note that some harmless actions a visitor may perform can be suspicious and cause the filter to react.
Note. The proactive filter will not be applied to user groups whose operation set (in fact, permissions) includes the Bypass Proactive Filter option (see the description of access permission levels).
An Intrusion Log (Settings > Proactive Protection > Intrusion Log) registers any events relating to potential security threats. The log lifetime can be defined in the kernel module settings. The log includes the following information on an event:
- the event date and time;
- the event name;
- severity (SECURITY or WARNING);
- an event source;
- an event object;
- the source IP. The “stop list” adds the URL to the Web Analytics module stop list.
- the client User Agent;
- the URL of an offended page;
- an offended site;
- the user name (if an event originates from a registered user), or a visitor ID. This field exists if the Web Analytics module is installed;
- the event description.
The log registers the following events.
- The Web Analytics module: exceeding the activity limit.
- The Proactive protection module: SQL and PHP injection attempts, XSS attacks and phishing attempts with redirecting.
- The Kernel module: successful log in and log out; password change request; stored authorization errors; new user registration; user registration and deletion errors.
User activity control is build around the Web Analytics module mechanisms and requires this module to be installed. Activity Control allows to protect the system from profusely active visitors, obtrusive bots, some DDoS attacks, and to prevent password brute force attempts.
You can enable or disable the activity control here: Settings > Proactive Protection > Activity Control using the Enable Activity Control (or Disable Activity Control) option.
The visitor maximum activity is regulated by the Parameters tab settings.
If a user makes more requests than allowed within the time specified, they are automatically blocked for the specified period showing a special page to them. The edit template link allows to edit the template of the error page. Check the Add entry to event log option to register the limit exceeding in the intrusion log (Settings > Proactive Protection > Intrusion Log).
Note: the standard protection level implies that the activity control is enabled.
Special Security Settings for Administrators
The standard protection level implies that the Administrators user group has the highest security level, which is the default setting. If this security level is different from the highest for some reason, do the following.
Click Set to High on the Security panel. The Security tab of the group properties form will open.
Specify High level in the Predefined security settings field and save changes.
The CAPTCHA-Aware Registration Procedure
A requisite condition for the standard protection level is the use of CAPTCHA for user registration. This option can be enabled in the Main module settings on the Authorization tab:
You can alter the CAPTCHA look and feel is configured at Settings > System settings > CAPTCHA.
Error Report Mode
In order to protect the site at the standard protection level, there is another Kernel module parameter that is to be configured - Error report mode.
Open the Kernel module settings (Settings > System settings > Module settings > Main module).
Select either Errors only or None in the Error report mode field.
Note: selecting the Errors and warnings mode automatically switches the security level to basic.
Showing Database Request Errors
The standard protection level does not require showing database error messages to common users which means the $DBDebug variable is to be set to false. Here, when a database error occurs, only the administrator will see the full error description. However, setting this variable to true causes the error messages to be shown to all the site visitors.
You can change the $DBDebug variable value by editing the /bitrix/php_interface/dbconn.php file.
High security level
Remember that you have to set the parameters of the standard level prior to configuring the higher protection levels.
Note: if some of the high protection level parameters are incorrect, the standard protection level takes effect with respect to parameters of other protection levels, or basic if the standard level have been configured incorrectly.
Logging the Kernel Events
The Log Kernel Module Events parameter embraces a number of the kernel module options:
Enable all the events on this sheet for the site to be protected at the high security level. Even if one of the options is not checked, the Log Kernel Module Events parameter is considered to be taking a mismatching value which causes the site to be protected at the standard (or basic) security level.
Protection for the Site Control Panel
The site control panel is protected by denying access from all IP addresses except for those specified in the settings. You can enable or disable the protection at Settings > Proactive Protection > Control Panel Protection using Enable Protection (or Disable Protection).
Note. Before enabling the Control Panel protection, specify here the IP addresses or address range of clients allowed to access Control Panel.
Secure web projects must have the Control panel protection enabled.
To remove the IP address restrictions, create a special flag file and specify the file pathname in the Proactive Protection
module settings. The default name format is ipcheck_disable_cef<32_random_characters>
The Session Storage and Session ID Change
Most web attacks are purposed to steal the session data of an authorized user or, what is more valuable for attackers, of an administrator. The standard Bitrix Site Manager package controls the following session protection parameters, for each user group individually:
- Session lifetime (min.);
- Session Network Mask.
However, it is often impossible to restrict access because users may use dynamic IP addresses. The following two protection techniques of the Proactive protection module significantly add to the standard protection mechanisms:
- storing sessions in the Security module database;
- changing session ID’s after specified intervals.
In order to enable or disable storing the user session in the database, click the big button, the only control on the Settings > Proactive Protection > Session Protection page.
Storing session data in the module database prevents data from being stolen by running scripts on other virtual servers which eliminates virtual hosting configuration errors, bad temporary folder permission settings and other operating system related problems. It also reduces file system stress by offloading operations to the database server.
Note. Switching the session store mode causes all the logged-in users to lose authorization because this erases the user session data.
You can configure the session ID change mechanism on the Change ID's tab of the session protection settings form.
Do the following to activate the ID change:
- specify the Session ID Lifetime (in seconds), which is the interval between two consecutive session ID changes;
- click Enable ID Change.
Changing the identifier increases the server load but makes the authorized session hijacking ineffective.
Note. The high protection level requires that you enable both of these protection mechanisms.
Redirect Phishing Protection
You can enable or disable the phishing protection at Settings > Proactive Protection > Redirect protection by clicking the button Enable redirect protection against phishing attacks (or Disable redirect protection against phishing attacks).
The following picture illustrates the phishing protection parameters:
You can protect your redirects by:
- checking a page for the presence of the HTTP header;
- signing the site links with a digital signature. This option specifies to add a special parameter which uniquely identifies the site and the transition to the system links. However, administrators can add their own links they want to protect.
The redirect protection can react in either of the following ways:
- redirect to a link URL showing a warning message and making a seconds delay. The message text and the delay duration are entered in the fields below;
- redirect to a fully, admittedly safe address. This can be the index page, for example.
Note: the standard protection level requires active phishing protection.
Highest security level
Remember that you first have to configure the parameters of the standard and high levels prior to configuring the highest protection:
Note: if at least one parameter of the highest protection level takes an invalid value, the protection level whose parameters are completely configured takes effect with respect to parameters of other protection levels.
The concept of one-time passwords empowers the standard authorization scheme and significantly reinforces the web project security. The one-time password system requires a physical hardware token (device) (e.g., Aladdin eToken PASS) or special OTP software. These passwords are especially recommended for use by the site administrators since they significantly improve security of the “Administrators” user group.
Note. You have to enable the one-time password system for the site to be protected at the highest protection level.
You can enable (or disable) one-time passwords on the Settings > Proactive Protection > Two-step authentication form by clicking Enable one-time passwords (or Disable one-time passwords).
For the one-time password scheme, a corresponding tab is shown in the user profile form. The one-time password mechanism is configured for each user individually.
To enable users to authenticate using one-time passwords:
- Check Enable Compound Passwords.
- Enter the Secret key supplied with your OTP software.
- Initialize the device by entering two one-time passwords generated by the device consequently (for example: 111111 and 222222).
- Save changes.
Now a user can authorize using their login and a compound password - a combination of the standard password and a one-time device password (6 digits). The one-time password (see item 2 on figure) must be entered in the Password field after the standard password (item 1 on figure) without space.
The OTP authorization system was developed by the Initiative for Open Authentication OATH. The implementation is based on the HMAC algorithm and the SHA-1 hash function. To calculate the OTP value, the system takes the two parameters on input: the secret key (initial value for the generator) and the counter current value (the required cycles of generation). Upon initialization of the device, the initial value is stored in the device as well as on the site. The device counter increments each time a new OTP is generated, the server counter - upon each successful OTP authentication.
Hence, if a device button was pushed more than once (f.e. accidentally) but no successful OTP authentication took place, and the push count exceeds the Password Check Window Size value, the generator counter will become desynchronized making a user unable to authorize.
In this case, a device and a user must be resynchronized by resetting the server value to that stored in a device. This procedure requires that a system administrator (or a user owning sufficient permission) generates two consequent OTP values and enters them in the user parameters form.
To avoid desynchronization, you can increase the Password Check Window Size value to, say, 100 or 1000.
The File integrity control form (Settings > Proactive Protection > Integrity Control) serves to check the integrity of the system kernel, system area and public files.
Check the system integrity on a regular basis (at least weekly) for the site to be protected at the highest level. Perform the integrity control check before updating the system and collect the new file data afterwards.
Note. Some module updates may require the control script to be signed anew.
Running the Integrity Check
- Enter and remember your password. A strong password should have at least 10 characters containing letters and digits.
- Confirm the password in the corresponding field.
- Specify and remember a keyword. It must differ from the password.
- Click Next.
If you made no mistake with the password confirmation, the following message will appear:
Now you can collect the file information in order to check the system integrity.
Gathering the File Information
- Click the Actions tab and check the Collect File Information option:
- Click Next. The following form will open:
- Set the data collection parameters:
- Data Collection Area – select the system folders you want to process.
- File Extensions – specify extensions of files whose information is to be collected. Separate multiple extensions with comma, without space.
- Encryption Password – type here and remember the password which will be used to encrypt and decrypt the verification file.
- Step Duration – specify the duration of a single data collection step, in seconds.
- Click Next to start data collection. Upon completion, download the data file to your local computer for better security.
The verification data file is now ready, you can check the system integrity.
Checking the System Integrity
Every (except the first) time you start the system integrity check, the verification script is checked for unintentional or malicious changes.
- Enter the password that you have used to sign the verification script and click Next.
Ensure the verification script prints the keyword you have specified for signing.
Note: if the keyword differs from the one you have previously entered, the integrity control script is compromised which means it has been modified and cannot be trusted. In this case, you have to supersede the control script (for example, rollback to version 8.0.0).
- Click the Actions tab and activate the Check Files option.
- Click Next to open the verification data file selection form:
- Select one of the existing log files or upload the log file from your machine using Browse. The following form will open.
- In the appropriate filed, type in the decryption password you specified when creating the verification data file.
- Specify the duration of a single check step (less times give more server stress).
- Click Next to start checking the system integrity. On completion, the following report will be displayed:
Web antivirus is a special software to help prevent malicious actions that may be performed on a website. Such software detects known or potentially dangerous portions of HTML code and cuts these codes away thus blocking viruses.
Note: web antivirus should not be regarded as a replacement for the conventional antivirus software.
To enable or disable the web antivirus function, just click the button on the Web Antivirus form (Settings > Proactive Protection > Web Antivirus).
to detect viruses potentially injected before until the buffering occurs, add either of the following code:
auto_prepend_file = /www/bitrix/modules/security/tools/start.php
or to .htaccess:
php_value auto_prepend_file "/www/bitrix/modules/security/tools/start.php"
To select an action the system will undertake when a virus activity is detected, click the Parameters tab:
- Cut object from site code - deletes dangerous code;
- Record in log and notify administrator - this option specifies to only log the virus activity; no dangerous code will be removed. The website administrator will be notified of the virus event via the e-mail once in the time interval denoted in the Notification Interval field.
If, for some reason, you do not web antivirus to be applied to specific portions of the web page HTML code, specify such code on the Exceptions tab.
The Proactive Protection module has a private stop list (Settings > Proactive protection > Stop List). This feature is different from the Web analytics module stop list.
The Stop List page shows existing rules aimed to restrict access to your site (as a whole or individual areas) from IP addresses listed in the rules. If Active is green, the rule is valid; if red – the rule is expired.
The access restriction records can be created manually or automatically. The rule will be created automatically if:
- the Control Panel protection mechanism is enabled;
- the proactive filter responds to an intrusion attempt (if the Add Attacker’s IP Address to Stop List option is selected as the attack response action).
You may want to add restriction rule manually, for example, when analyzing the intrusion logs. To do so:
Now, if a user whose IP address matches the rule attempts to access your site, they will see a HTTP 403 error message, which effectively means that access is denied.
This chapter is devoted to creating, maintaining and managing blogs using Bitrix Site Manager.
A blog is an internet diary that enables users to publish short comments structured in (reverse) chronological order. Authors can express their ideas instantly for other people to read; tell on the current events etc.
A blog's author can not only add new entries to a journal but also receive comments from other visitors about the messages. Armed with this feature, the author can offer subjects to be discussed by other visitors; exchange opinions about thoughts etc.
Nowadays, blogs become more and more popular among people because they can freely exchange opinions and ideas, no matter where they live.
Bitrix Site Manager contains a dedicated Blogs module to enable people create and maintain their journals. With this module, you can create a feature-rich blogging section on your site:
- create an unlimited number of blogs;
- manage permissions of users to access blogs and perform various operations:
- create blogs;
- administrate and moderate blogs;
- read other blogs;
- add new messages;
- add comment to messages;
- customize icons and smileys for use in blog messages;
- pre-process smileys and tags in messages and comments;
- create message drafts;
- display and use journal calendars;
- export blogs to RSS;
- use Trackbacks;
- group (tag) messages by subject;
- create tree-view comments;
- add images to messages.
The fundamental principle of the blogging system is that a single user (i.e. a visitor that have a unique valid combination of a login and a password) can have only one blog.
|Blog owner is a user that maintains a blog (a blog creator).
|Nickname is a user name (often fictitious) that is displayed to all readers.
A user can define their nickname in the user profile.
|Avatar is an image (static or animated) that is associated with an author of
a blog or comment.
|User group: each blog can have its own set of users or user groups that are
given different permissions to access messages and comments of the blog.
|Friend is a user who is a member of one or more groups created by a blog's
author. A friend has certain permissions to access the blog (e.g. read messages
and/or add comments). The blog author's friends are displayed on the user profile
|Friend's page displays a selection of recent messages created by the blog
|Blog group is a set of blogs that can have a certain common trait (e.g. blogs
of employees) and can be displayed on a given site.
|Message is an article created by a blog owner or visitor.
|Message tags are used to classify blog messages by an author-defined subject (e.g.
by theme or purpose).
|Comment is the reply that a visitor speaks on the subject proposed by a
|Trackback address is an absolute URL to a blog message (e.g.
Users can manage blogs in the public section of the site, or via the Control Panel.
Note: only users that have full access to the Blogs module can manage blogs in the Control Panel.
The following entities can be managed in the Control Panel:
- all blogs;
- all blog groups;
Other elements (the blog owner's profile, user groups, blog users, message groups and tags etc.) are managed via the public interface.
Besides that, you can define some other parameters (avatar dimensions and size; path to blogs etc.) in the Blogs module settings form (Settings -> System settings -> Modules -> Blogs):
The following parameters can be defined in the Blogs module settings
- maximum size of a user's avatar;
- maximum size of images that a user can add to a message;
- ability to use nicknames instead of real names;
- ability to change the blog URL of already registered blogs (in fact, the blog name):
- access permissions of user groups for the module.
The Blogs module settings also allow you to define the path to public section of blogs (the folder containing pages that describe the design and user interface of blogs). This parameter must be set for the blogs to function correctly.
A blog group define the subject to which the blog refers (e.g. "tourism", "software", "art"). Each blog in the system should belong to a certain group. You can create and edit groups on the Blog groups page (Services -> Blogs -> Blog groups):
To add a new group, click New group on the context toolbar. To edit parameters of an existing group, click the group ID link or select Edit group parameters in the context menu:
A blog group editing form has the following format:
In the Group site field, choose the site on which blogs of an edited group would be available. This bounds the blog group to a certain site of the system, making new blogs of this group bound to this site.
Note: each blog must belong to a certain group. You can make this assignment in the blog editing form.
Creating and editing a blog
You can manage blogs in the Blogs form (Services -> Blogs -> Blogs):
A new blog in the Control Panel can be created by clicking New blog on the context toolbar. Clicking this button opens a blog editing form:
In addition to common parameters (the blog name, description, owner, group), you can define the following settings.
- Enable comments - if checked, visitors can leave comments to posts in the blog. Only visitors belonging to a group that is granted appropriate permissions can create and add comments:
The two default user groups are available for a blog: All visitors
and Authorised visitors
. Users are free to create their own user groups, e.g. friends
. New user groups can be created in the public section. Access permissions of user groups can be customised in the public section as well as in the Control Panel
- Anti-bot protection (CAPTCHA) - allows to enable or disable the use of CAPTCHA mechanism to prevent automated messages.
- Export RSS .92, RSS 2.0 and Atom .03 - enables export of the blog data to RSS .92, RSS 2.0 or Atom .03. If the option is enabled, the blog pages will show button that, if clicked, will export data to one of these formats.
- Send e-mail notifications - if checked, the blog owner will receive notifications about new comments and messages to their e-mail address.
You can add and modify smileys that will be available in the blog messages, in the Blog smileys form (Services -> Blogs -> Smileys):
You can add more smileys by clicking New smiley, or edit an existing one by selecting the corresponding item in the context menu. This will open a smiley parameters editing form:
Design of the public interface
The blog interface is built up as an aggregate of administration and public files, or pages.
The demo version takes advantage of the new composite component Blogs to create pages and sections for blogs.
Physically, this component occupies only one page; but in fact, it is quite smart to build the fully functional blogging section for a site. Just a single move and you obtain a pile of pages:
- blog index page (displays blog groups, recent messages etc.);
- "Add to friends" page;
- blog settings page;
- user group configuration page;
- tag customization page;
- blog owner profile page;
- blog search page;
- other service pages.
You can explore sample blog public files in /communication/blog/ (according to the Blogs module settings):
Note that the demo version index.php file is used to perform all blogging interface jobs in the common mode (not search engine friendly, SEF), while blog_sef.php handles SEF mode requests.
For example, the following URL may happen to be queried to view a blog post without SEF:
Otherwise in the SEF mode:
Using the public interface
You can manage blogs in the public section by using commands of the context bar that is displayed on every page of the blog section.
To start managing blogs, you have to authorise (Log in button) or register (Registration button) in the system:
Commands of the context bar depend on the currently displayed page and the current user permissions.
For example, a blog owner will enjoy the following commands when viewing the blog review page:
- Blog List - opens a page containing the outline of all blogs;
- My blog - opens the blog of a current user;
- My profile - opens the current user profile for editing;
- Friends Page - displays recent messages of users that are friends of a current user;
- Logout - end the authorised session.
A user viewing pages of their own blog will see the following commands:
Creating a blog
An example that can be found in the trial version opens the blog creation form when a visitor clicks the Create blog link on the blog review page:
This link is displayed if:
- the current user does not have a blog on a current site;
- the current user is a member of a user group that is given a permission to create blogs.
Editing blog parameters
By clicking the Blog settings button:. Please note that the administrator can modify all blogs.
The blog settings page has almost the same layout and preferences as the blog creation page:
However, it contains the following additional parameters:
Creating a post
If a current user is allowed to create posts in the current blog, the New message button is availabe:
Clicking this button opens a new post creation form:
An author can set additional access permissions for visitors:
The new message can be published immediately upon creation, or it can be saved as a draft:
Those messages are stored in the draft message list that can be accessed by clicking the respective button:
Visitors can add comments to posts on the post details page.
If a current blog can be commented and a current user's group has permissions to create comments (in the blog or in the post), the Add comment link will be available at the bottom of a page:
This link opens a comment creation form:
To add a comment to an existing one, click Reply below the comment:
The page also displays the two links: Parent and Link at the bottom of each multilevel comment block:
The Parent link navigates to a comment to which the current one is added. Link allows to copy the URL of a desired comment:
If any comment is added to a post, a special link indicating the current number of comments appears below the post:
Managing the current user profile
To edit or view parameters of the profile, users can click the My profile button on the context toolbar in the public section:
This will open the User profile page:
Finally, clicking the "edit user profile" link (outlined in red on the figure above) opens the profile editing form:
Using message tags
The Tags button opens a form in which users can create and manage tags that define names of categories (e.g. Hints, Music etc.) to which the subject of a post can be referred.
The tag creation form is more than simple:
Clicking Add inserts a new empty text entry field to create more tags.
In future, when creating a new post, users can select the required tag to indicate the post subject:
Tagging allows blog visitors to pick out messages that relate to a certain subject in which a visitor has a particular interest. To view messages under a certain tag, visitors can use links displayed on the right:
Adding users (friends)
A user can add friends to the blog on the Friends page, which can be opened by clicking the respective button:
The Friends page displays a simple form where a user can add friends by nickname, login or blog name:
After clicking Add, a user will be added to the friend candidate list:
Click More fields to add a new row to enter more friends.
You can change the user's membership in groups by clicking the Edit link. To remove a user from your friends, click Delete.
You can also add another user to you friends list when reading that user's blog. To do so, click the Add to friends button:
To become a friend of this user, click the Become a friend button:
To view messages that your friends wrote recently, click the Friends page button on the context toolbar:
Managing user groups
The user groups are used to distinct visitors of your blog and give them different access permissions. To start managing user groups, click Groups settings:
Clicking Add inserts a new empty text entry field to create more groups:
Customization of user group access permissions is performed in the blog parameters editing page, in the public section:
The below are the two examples of using blog user groups:
- Blog user groups can be used to manage permissions to access the blog and blog messages. You can add users to groups on the Friends page.
This page displays all users that are your friend candidates:
Click Edit to open the friend settings form, in which you can bind the user to the required groups:
Note: If there are any public groups in the blog settings, users will be added to those groups automatically.
- When creating a post, an author can define access permissions for each group individually:
Export to RSS
The Blogs module can export the blog contents to RSS. All you have to do is enable it in the module settings. Once you have the RSS export turned on, your blog main page and each post will display buttons allowing to export data to a required format:
A Trackback is the method for blog authors to request notification when somebody links to one of their documents. This enables authors to keep track of who is linking to, or referring to their articles. This helps to avoid duplicating an article in many blogs: if a blog post extends messages in other blogs, it is sufficient to place a link to the article in question in comments to relevant articles in other blogs.
Bitrix Site Manager implements trackbacks in the following way.
- The message editing form has a Trackbacks field in which an author can provide URL's of parent articles (i.e. those to which the current article refers):
- when visitors view the current article, the parent one gets automatically notified of being linked.
Sometimes, trackbacks can put a supplementary load on the site's traffic due to additional requests. To avoid overload, you can disable (or then enable) trackbacking for an individual article, in the message editing form:
If trackbacks are enabled, the article details page will display the Trackback address link:
The Newsletters and subscription module serves bulk-mailing e-mail messages. These can be, for example, new product announcements, company news etc.
Furthermore, the module allows to create public and private mailing lists, and send messages manually or automatically.
Introduction to subsriptions and mailing lists
The wide range of functions offered by the Newsletters and subscription module can help
you solve virtually any task concerning sending e-mail messages from the site. You can use it to
inform your visitors about company news, achievements, services etc.
The following two subscription modes can be used on the site:
The system supports the following methods of sending newsletter issues:
- manual - when creating a newsletter issue, you can select subscriptions to
whose subscribers a newsletter message will be sent. The process of sending messages is
initiated by the Newsletters and subscription module administrator;
- automatic - newsletter issues are generated and sent automatically using
the specified template and schedule (at the time and days specified in advance).
Newsletter categories are subscription rubrics to which visitors can subscribe. Visitors can subscribe to more than one rubric.
The module parameters (including message sending options) are defined in the module settings form (Settings -> System settings -> Module settings -> Subscription).
The settings form contains the following options:
- The flag Allow anonymous subscriptions allows users to subscribe to newsletters without having to register at the site.
- The field Public section containing the subscription edit page specifies the path to a public folder containing the subscription editor form. The path is relative to the site root. The field may include the #SITE_DIR# macro.
- The fields Default From e-mail and Default To e-mail can be used to specify the e-mail addresses which will be used as the default sender and recipient addresses in all newsletter messages. However, you can change the default addresses every time you create a new message.
- The Mail message encoding fields specify the encodings in which the e-mail messages can be created.
- If you require the extended ASCII symbols (0-255), you can enable the Allow 8-bit symbols in message header option. Otherwise, the extended symbols will be printed in Base-64 encoding.
- The fields Method of automatic issue sending and Method of automatic generation offers the following two options:
- agent - the newsletter issues will be scheduled, generated and sent using internal tools of Bitrix Site Manager. Running the agent at the specified time requires that a site is requested (e.g. by a visitor who opens a site page). Otherwise, the agent will be run next time the site is requested. Thus, this method is reasonably effective for popular sites
- cron - this method is only available on Unix based systems because it uses the cron demon of Unix. It is the best way to send newsletters if cron is available on your system since your site needs not be requested.
You can manage your newsletters in the Newsletter categories form (Services -> Newsletters -> Newsletter categories).
To create a new newsletter topic, click the Add button on the context toolbar. To edit an existing newsletter topic, select Modify in the context menu, or simply double-click the required newsletter topic.
Manual mailing lists
Managing manual mailing lists
In general, the process of managing manual newsletters includes the following actions:
- creating a newsletter category (rubric);
- creating facilities to allow visitors subscribe to the rubric;
- creating newsletter issues of the rubric;
- sending e-mail messages.
Let us create a manual subscription Catalog news
. Open the Newsletter categories
-> Newsletter categories
). Click Add
on the context toolbar
- Manual subscriptions require filling in fields of the Subscription tab only:
- To allow visitors to subscribe to issues of the new rubric, check the box Display in public section. This will cause the created newsletter category to be shown in the Subscription form of the public section:
Click Save. Now that we have created a new subscription rubric, we can create newsletter issues and send them to subscribers. You will find the description of these operations in the next lessons.
Providing subscriptions for visitors
Visitors can subscribe to a newsletter:
- without assistance if a newsletter is set to be displayed in the public section;
- with the help of an administrator (e.g. if a newsletter is hidden and thus cannot be accessed from the public section).
The following actions are required to be taken to allow visitors to subscribe without assistance.
- Enable the newsletter to be accessed from the public section. Open the required newsletter for editing (Services -> Newsletter -> Newsletter categories) and enable the Display in public section option:
- Enable visitors to subscribe from the public section by adding appropriate user interface elements to it.
- Add the Subscription form visual component to a design template. This component displays a special form where visitors can type their e-mail address and choose one or more desired newsletter categories for subscription:
Note: Clicking OK opens the subscription preferences editing form in which visitors can modify parameters of the subscription (format etc.), and confirm it by pasting the received subscription confirmation code.
You have to specify the path and name of the subscription editing page in the Subscription form visual component settings. If the page does not exist, you will have to create it later.
Adding the Subscription form visual component to a site design template displays the subscription form on all pages. However, you can add this component to certain pages only where you want the subscription to be available.
By default, the subscription form displays active subscriptions whose option Display in public section is active. If you want hidden subscriptions to be shown, you have to configure the Subscription form component as appropriate.
- Create a special subscription editing page and save it under the name specified in the Subscription form component settings. All you have to do is create a new page in the visual editor and add the Subscription editing page component to it.
With this component, you can:
- allow or disallow anonymous subscribers (unregistered and/or unauthorised visitors);
- invite unauthorised users to log in by displaying an appropriate link;
- define whether hidden newsletters are to be displayed or not.
Once a user has subscribed to a newsletter, a corresponding record is created in the Newsletter module (Services -> Newsletter -> Subscribers):
The record contains information about a subscriber and the selected newsletters.
The site (or newsletter) administrator can edit the record as required (e.g. unsubscribe the user or confirm the subscription manually).
Adding subscribers manually
An administrator can add subscribers (in other words, subscribe users) manually by clicking the Add button on the context toolbar of the Subscribers form (Services -> Newsletter -> Subscribers):
- On the Subscriber tab, enter information about a subscriber:
- For anonymous subscribers, it is sufficient to specify only the destination e-mail address;
- If a subscriber is a registered site user, you can click to find the required user. After you select it, all the required information will be inserted automatically.
- On the Subscriptions tab, select newsletter categories to which the user will be subscribed. You can also specify the required format in which messages will be sent.
: when adding a subscriber manually, you have to check the Subscription confirmed
box to enable the subscriber to receive newsletter issues:
Creating a newsletter issue
Newsletter issue is an e-mail message sent to subscribers of a newsletter category (rubric).
Note: Only issues for manual subscriptions need to be generated by hand. Issues of automatic subscriptions are generated by the system according to a defined schedule.
Messages can be managed on the Newsletter issues form (Services -> Newsletter -> Newsletter issues).
Here, you can click the Add button to create a new issue, or edit an existing one by double-clicking the row of a required issue.
The issue editing form includes the following tabs.
On this tab you will type the text of your newsletter message.
For an e-mail message to be sent and dispatched successfully, you must fill in the required message header fields: the sender, the default recipient and the subject.
By default, the sender and recipient addresses are inferred by the settings of Newsletter or Kernel modules.
Here you can specify user groups or individual persons who will receive the issue message.
You can specify:
- groups of persons who are the subscribers of one or more mailing list;
- user groups;
- e-mails of additional recipients.
You can use specify the e-mail address filter that will restrict destination addresses to its condition. For example: %@bitrixsoft.com.
This tab contain other extra parameters that you can configure.
If you require that the To field contains an address of a respective recipient, enable the Send directly to each recipient option
You can instruct the system to send the issue automatically. Perform the following steps to do so:
- enable the Send the issue automatically at the scheduled time option;
- specify the date and time when the issue is to be sent;
- send the message by clicking Send.
- save the message as draft by clicking Save or Apply;
- send the message immediately by clicking Send.
An issue can be in one of the five statuses, each of which define its state:
- Draft - the message is being edited and is not ready;
- In progress - the message is currently being sent or is pending (for scheduled issues);
- Sent - the message has been sent successfully;
- Sent with errors - the message has been sent but some errors occurred while sending;
- Paused - message sending is stopped.
The following diagram illustrates the issue status flow.
Automatic mailing lists
Managing automatic mailing lists
The process of managing automatic newsletters includes the following actions:
- creating a newsletter category (rubric);
- configuring the issue generation and send parameters;
- creating the subscription front-end.
As an example, we shall create the Company News
automatic subscription. Open the Newsletter categories
-> Newsletter categories
). Click Add
on the context toolbar.
- To enable issues to be generated and sent automatically, check the Automatic box:
- After that, the Automatic generation tab becomes enabled:
The following parameters can be set in this tab:
Before you save the new subscription parameters, you can view an example of issue generated using the specified template just as it will be displayed to subscribers.
To view how an issue of your new subscription will look, click the Check
button on the context toolbar:
Clicking this button opens a page in which you can specify the template check parameters. After all parameters are set, click Check to generate the sample issue.
In the end, you will see the following form:
This form shows:
: this form shows the Add newsletter issue
button. You can click it to save an issue that were generated using the selected template, and then send it later manually.
Click the Edit button on the context toolbar to get back to configuring the new newsletter category.
Save the new newsletter rubric by clicking Save (or Apply). From now on, issues of the new subscription will be sent to subscribers according to the specified schedule.
You may want to change the message generation template. To do so:
- Click the template name link.
- Then, open the template for editing in the Site Explorer form.
- Now you can edit the template by adding static (e.g. title) or dynamic information (e.g. scripts or visual components) to it.
Automatic newsletters can be published for user subscription in the same way as manual newsletters.
Polls and surveys
The Polls and Surveys module is used to set up and conduct various
polls and surveys. The module allows you to create poll groups, restrict user access
to voting functions (e.g. you can prevent a user to vote twice in a single
survey), manage the poll result display etc.
Polls and surveys
The Polls and Surveys module can be used to set up and conduct various polls and surveys and display their results.
Access permissions allow to control users' access to polls and information about the voting dynamics and results.
To control and manage your polls and their parameters you can:
- restrict the polling period;
- display a choice of answers to a question;
- allow visitors to type their own answers to questions;
- configuring the type of result graphs and diagrams;
The following notions are used with polls and surveys.
Creating a poll
Let us create a "What kind of books do you prefer?" poll. We'll make it a member of the Poll in Bookstore poll channel.
- First, create the Poll in Bookstore poll channel with the BOOKS_VOTE symbolic identifier (Services -> Polls and Surveys -> Poll channels, click Create).
Configure user access permissions to polls of this group (the Access tab).
- Now, create the Poll in Bookstore poll.
- The next step is to create a list of questions to this poll.
The Poll in Bookstore poll will contain only one question with a choice of answers.
Create possible variants of answers:
The Radio field type allows to select only a single choice from the list.
Publishing the poll
The Polls and Surveys module visual components are used to publish a poll. Add the created poll to the include area of site page using the Current poll composite component. Do the following.
- Open the page in the HTML visual editor.
- Place the visual component Current poll.
This component is used to display form or results for current poll.
In the component settings, specify the group whose poll will be displayed on the page. In our case, it is the Poll in Bookstore poll group.
- After the page is saved, the poll will be displayed in the public section.
Information about poll respondents will be available in the Control Panel (Services -> Polls and Surveys -> Visitors).
Information about voting results is available on the Visitor votings page (Services -> Polls and Surveys -> Visitor votings).
The process of site management envisions communication via the e-mail with people who are can
concern operation of your web site. For example:
- visitors, customers;
- contractors, suppliers;
- employees responsible for the site contents;
- other groups.
The Mail module is used to receive and process e-mail messages. It empowers you with the
following e-mail management functions:
- centralized storage of e-mail messages;
- unlimited number of mail boxes;
- creating and applying rules to incoming messages, automatically or manually;
- intelligent heuristic spam filtering system;
- delivering e-mail messages without deleting them from mail server, and many other features.
You can manage e-mail accounts in the Mailboxes form (Services -> Mail -> Mailboxes):
Note: Bitrix Framework supports an unlimited number of mailboxes.
A mailbox (mail account) is a record with the following fields:
You can specify the following information in the mail account editing form:
- the system name of an e-mail account;
- the server where a mailbox is hosted;
- mailbox access information (name and password);
- message delivery options.
: you can deliver e-mail messages either manually or automatically.
To check for new e-mail messages automatically, specify the interval (in minutes), in the Check interval field, after which the system will check for new messages on the specified server.
If you want to check for new messages manually, set the value of this field to 0
When setting up a new e-mail account, you can create rules that will be used with this mailbox.
These rules will be applied to messages received from this mailbox. For example, the rules can be spam filters etc.
The Messages form (Services -> Mail -> Messages) displays a table containing information about all the received e-mail messages:
You can have only the required messages displayed in the table by using the filter:
To deliver messages manually, select the required mailbox and click OK on the context toolbar:
|2.|| || |
After you have delivered messages, you can view them.
The message view form offers the following functions.
- If the message is an unsolicited mailing, you can tag it as spam thus training the built-in antispam filter.
- If required, you can apply any of the previously created mail rules.
- Finally, you can delete the message.
: these actions are also available via the action menu of the Messages
You can create and manage e-mail message processing rules in the Mail rules form (Services -> Mail -> Rules):
To create a new rule, click New rule on the context toolbar and choose the required type template:
- manual settings - you will have to configure all parameters of a new rule as required;
- adding message to techsupport - a new rule is created using the special built-in helper template to simplify creating rules to filter out techsupport messages.
A typical e-mail rule has the following parameters :
- the mailbox to whose messages the new rule will be applied;
- one or more conditions;
- actions to be performed if the conditions are met.
: you have to choose the type of event
that will cause the rule to be applied:
- When receiving mail - the rule will be applied whenever a new message satisfying the rule criteria is received;
- When applying the rule manually - the rule can be applied if called intentionally (e.g. when viewing a message).
The Mail processing log displays all events related to the Mail module operation:
- sending requests to mail servers;
- responses from mail servers;
- use of rules and actions.
You can view the log in the Mail processing log form (Services -> Mail -> Mail log):
The log records are highlighted with different colours to emphasize their nature:
- green - request to servers;
- blue - responses from servers;
- red - errors.
Example of creating a mailbox
Let us create and set up a new mailbox record.
The advertising management system provides for banner shows on your site by attaching the
external banner system code or by using the internal banner rotation system.
With the banner management system, you can:
- display banner images or show text banners by injecting the banner code in the HTML code of
- set the banner active period and impression frequency;
- restrict the number of maximum impressions;
- allow or disallow a banner to show on certain pages and sections of the site etc.
Advertising banner is an image or text block containing incentive message which is used for brand awareness and generating sales. Clicking a banner usually opens a page containing the description of a product or service being advertised:
: Site counters can also behave like a banner:
Banner management functions are concentrated in the Banners form (Services -> Advertising -> Banners):
Advertising area is a named location in the site design template where banners are displayed:
Note: Advertising areas are allocated during the site design template creation.
A single advertising area can show as many banners as required. The banner showing probability is the subject of the display priority, or weight, which can be set in the banner editing form:
The more is the banner weight, the higher is the probability that a banner will be selected for showing.
Each banner has the following traits:
Banner type is the conventional name of a banner showing disposition. To put this another way, banner type is the name of an advertising area specified in the design template. To show a banner in a desired area, set its type to the advertising area name:
Note: To view banners that are displayed in an advertising area, click in the required advertising area (this button is display in the site editing mode). Click to edit the currently shown banner.
Important! Banners that are shown in the same advertising area (i.e. banners of the same type) show have equal dimensions. This ensures that the page design will remain sound and will not break.
You can manage banner types in the Banner types form (Services -> Advertising -> Banner types):
Banner group is an optional parameter that can be used to classify banners by some parameter (e.g. advertised product). You can specify the banner group name in the banner editing form.
Note: You can choose any of the previously used banner group names in the drop-down list.
Banner status indicates one of the predefined states that a banner currently has:
- approved - banners in this status can be and are shown;
- under consideration - a banner is not shown; indicates that the banner is to be either approved or rejected;
- rejected - indicates that a banner was disapproved by an administrator and cannot be shown.
You can change banner status in the banner editing form:
or in the list of banners (by switching the quick edit mode on):
Contract is a set of banner showing conditions. A typical contract defines:
- when and where banners of the contract are to be shown;
- keywords for the contract banners, etc.
You can manage contracts in the Advertising contracts form (Services -> Advertising -> Contracts):
Note: the system has the predefined contract Default, which cannot be deleted. By default, this contract does not apply any restrictions on banner shows, but you can change the contract configuration as desired. All new banners are attached to this contract by default.
An advertising contract can be managed by users (contract owners). Contract owners can be given different permissions in respect of contract management:
Users can be bound to a contract if only they are members of a user group that is given the Advertiser permission to the Advertising module.
Adding advertisement to pages
Let us publish a banner in the advertising area LEFT on the main page:
- Create a new contract to which a new banner is to be bound, and name it "Main page" (Services -> Advertising -> Contracts, click Add contract on the context toolbar):
Click the Restrictions tab and mark the banner types that will be managed by this contract. Also, we have to configure the banner showing schedule:
On the Targeting tab, specify pages where the contract banners will be shown:
Save the contract. You can now see it added to the list of contracts in the Advertising contracts form (Services -> Advertising -> Contracts):
- Create a banner that will be displayed in the LEFT advertising area (Services -> Advertising -> Banners). Click Add banner on the context toolbar, and select the contract we have just created in the menu.
Upload the banner image, and specify the link to be opened when a visitor clicks the banner:
: the new banner is bound to the previously created contract Main page
. The contract stipulates that only the banners of the LEFT
type can be created:
Remember that we have specified the banners of this contract to be shown on the main page only (
After save, the banner will be added to the list of banners:
Now we can see the banner shown in the LEFT advertising area.
Giving permissions to publish advertisement
Third-party users can publish and manage advertisement on your site. You can control their actions and restrict their permissions by creating dedicated advertising contracts.
Consider an example of enabling employees of an imaginary company BestShop to publish and manage their advertisement in the LEFT2 advertising area
- Create a new user group (BestShop); it will contain BestShop users. This user group will be given permissions to manage their advertisement.
Open the Access tab and select the Advertiser permission to access the Advertising module.
- Create a new contract; name it Company "BestShop".
On the Restrictions tab, mark banner types that can be controlled by advertisers.
On the Targeting tab, specify site sections where banners of the contract can be shown.
On the Access tab, define contract owners and their rights to manage advertisement in the context of this contract.
As a result, members of the BestShop user group now can create and manage banners of the BestShop advertising contract.
Using keywords to show banners
Using keywords to manage banner advertising is one of the main tactics to target your advertisements. This method allows you to:
- show exact advertisement that is wanted by certain visitors. You can show banners on pages containing information that is of particular interest to this very group of visitors;
- limit banner showings on certain pages depending on correlation between the banner message and the information that a page contains.
This method requires that you set up the following sets of keywords:
- banner keywords;
- page keywords:
You can specify banner keywords in the Keywords field in the banner editing field, the Targeting tab (Services -> Advertising -> Banners):
Page desired keywords can be set in the page properties form using the special predefined property
Note! If the value of the adv_desired_target_keywords property is empty, the system uses the keywords property to define keywords.
You can find more information in the system integration training course.
Users can create reports in the form of graphs and diagrams.
You can view graphs in the following report forms:
- banner graphs: Services -> Advertising -> Reports -> Banner graphs;
- contract graphs: Services -> Advertising -> Reports -> Contract graphs.
Diagrams are available in the following forms:
- banner diagrams: Services -> Advertising -> Reports -> Banner diagrams;
- contract diagrams: Services -> Advertising -> Reports -> Contract diagrams.
Using filters allows to choose the desired type of information to be plotted on a graph or diagram, and set the period for which the report is required.
The e-Learning module can be used to create training courses that visitors can take
A course is the well-organized and logically complete set of web pages giving information on a definite subject. A common practice is to conduct an examination at the end of the course in order to test students’ knowledge.
A common course includes:
- Chapters – logically complete parts of a course. Each chapter can include nested chapters or sections;
- Lessons – form the course content. Lessons can belong to chapters or a course (i.e. without binding to a particular chapter). Each lesson is represented by a single web page.
- Lessons can end up in a series of questions. Some of these questions can be used in self-check tests. Users can hold self-check tests to verify their knowledge.
- In the end of a course, separate questions can be joined up in a final test, where questions of self-check tests can be discarded.
The Attempts journal stores information about all tests hold by users. The journal records show test scores, success and failure ratio etc.
The test results are stored in the Gradebook. A result is a record holding testing score for a user. The result reflects the most successful test attempt.
Tests can be automated using simple administrator-defined criteria. Automatic tests instantly show the results upon holding the exam.
Web courses created using the e-Learning
module can be exported to an external file for uploading to other sites/intranets powered by Bitrix products. The module offers special tools to import and export courses.
Creating lessons and tests
Creating a training course
You can create and manage a training course in the Courses form (Services -> e-Learning -> Courses):
To create a new course, click the Add course button on the context toolbar. This will open the training course editing form:
The following parameters can be specified:
- announcement description (displayed in the list of training courses in the public section);
- full description (displayed on the main page of the course);
- period during which the training course is active;
- access permissions for different user groups.
After the course is created, it is added to the list of courses in the Courses form:
A training course divided in chapters is definitely more convenient to handle by on-line users since it allows to avoid loading all the lessons at once.
You can create a chapter in the following ways:
- by clicking the plus sign (+) in the Chapters column:
- by clicking the New chapter button on the context bar of a chapter report form
(Services -> e-Learning -> Courses -> <your course> -> Chapters):
Main parameters of a chapter are:
- parent level of a chapter. If a new chapter is the descendant of another one, select it in the Parent chapter list;
- the name (will be displayed in the tree menu in both the Control Panel and the public section);
- short and full descriptions.
After the chapter is created, it is added to the list of chapters:
You can survey all lessons of the course in the Lessons form (Services -> e-Learning -> Courses -> <your course> -> Lessons):
The New lesson button opens a form in which you can specify parameters of a new lesson:
- If a new lesson is to be added to the top level of the course, without binding it to a chapter, choose Top level in the Parent chapter list. Otherwise, select the required chapter there.
- You can type a short description of the lesson on the Description tab.
- Click the Text tab and enter the full text of the lesson.
After the lesson is created, it is added to the list of lessons:
You can view all lessons of a particular chapter by clicking the Lessons item in the required chapter:
: to view lessons that are not bound to any chapter, click the Lessons
item in the root chapter:
Creating and configuring tests
Each lesson in a training course can have a set of questions covering subjects explained in a lesson. There are two types of questions: common questions and self-check questions. You can choose the question type in the question settings. Examination tests are based on questions that you create for lessons.
Self-check tests are created automatically and include questions whose option Self check is active.
However, the final examination test requires that you instruct the system how to pick out questions for inclusion in the test. You can do that in the test creation form.
You can create a question by doing one of the following:
- by clicking + in the Questions column of an appropriate lesson;
- by clicking the New question button on the context bar of a form with lesson questions;
- by clicking the New question button on the form with a list of all questions (Services -> e-Learning -> Courses -> <course> -> Questions).
When creating a question, you have to choose the type:
- single choice: a question implies that only one answer is correct;
- multiple choice: a question implies that a user can select one or more answers.
Creating a question
You can enter the question text on the Question tab:
If you want to include the question in the self check test that will be suggested to students after studying the lesson, enable the option Self check.
Now click the Answers tab and specify possible answers to the question.
Important! Remember to mark the correct answer (or answers - for multiple choice questions).
You can open the Description tab to enter the question details and upload an image that will be displayed in the question area. After you click Save, the question will be added to the question lists of both the lesson and the course.
You can create and manage tests in the Tests form (Services -> e-Learning -> Courses -> <course> -> Tests):
To create a new test, click Add test.
- Questions are added to the test depending on the options specified in the Include in test field (1*).
- By default, self-check questions are not added to the test. To include them, mark the corresponding option (3*).
- You can limit the time given a student to pass the test, and the number of attempts (4*).
- You can set the test to calculate results automatically. This means that the system will display the test result and add a record to the log (the gradebook). To enable automatic test control, enable the corresponding option and specify the percentage of questions required to pass the test (5*).
All the examination attempts are recorded in the Attempts form (Services -> e-Learning -> Attempts):
Examination results are displayed in the Grade book form (Services -> e-Learning-> Grade book):
If a test is not automatic, the grade book will display only the scores.
Publishing a training course
Publishing a training course
Components of the e-Learning module are used to create and publish web courses.
: The demo version has some examples of web courses created with these components. The sample pages include:
- a list of web courses;
- a course view page.
These pages are located in /communication/learning/
To view how these pages run, type in your browser: http://<demo_site_address>/communication /learning/. This will open a page showing all the currently existing courses.
Publishing a list of courses
The Course list visual component does all the job required to show the list of existing training courses:
Important! You have to specify the course view page in the component properties. If no such page exists, you should create it.
Publishing the course
The demo version implements the course view section using the Learning course composite component, not using the search engine friendly mode.
Note: you have to place this component on a page no other than the one previously specified in the Course list component properties.
The system renders the course description, sections, lessons and tests using an independent design template. The course design template application conditions can be specified just in the same manner as for any other templates. Specifically, set the path to the web course section as the condition, in the site settings.
The demo version displays web courses based on the «E-learning template». This template is set to be applied to pages that reside in /communication/learning/course/.
When configuring the composite component parameters, you should remember to specify variables that will contain page identifiers:
The settings shown above use CHAPTER_ID to view chapter details, LESSON_ID - lesson details etc.
Following lessons and chapters of a course, the system displays tests for that course. The list of tests is published using the TEST_LIST identifier.
A page that displays an individual test is invoked using the TEST_ID identifier.
Upon having taken the test, a user will see the corresponding message. To view the test results, they can click the View test results link:
A page that shows the test results is invoked using the GRADEBOOK identifier.
Note: this page displays information about all tests that a user has taken.
The Search module indexes your site and provides the information search functions. The module
can search both static and dynamic pages, which enables site visitors to find required information
in the product catalogs, news, forum posts or any static section.
Important! When processing the search request, the system regards permissions of a user
who created the request. It means that the system will search information and display results
only from sections and pages that a user has permissions to access.
The search function allows to restrict the search area by only the required sections, file
formats or type of information. Also, for better search, you can choose information that is to be
included in the search index.
The system uses the search index (in the form of index tables) to search information. The following entities can be added to the index:
- static files;
- forum posts;
- information blocks;
- training courses;
- social network.
All text information added to the site in the form of static HTML pages or via the system interface (e.g. information blocks, forum etc.) is indexed automatically.
Important! Only static pages that have the TITLE tag can be indexed and, consequently, searched for.
In some cases (e.g. after importing products or uploading files via FTP) you will have to recreate the index manually; otherwise, new pages and/or information will not be available through the search form.
You can refresh the index tables in the Site reindexing form (Settings -> Search -> Reindexing):
- If your site contains a huge amount of information, reindexing may take a plenty of time. To make reindexing complete in less time, you can choose a certain site and/or module whose information is to be reindexed (4*), or reindex only modified files (1*).
- If your server experiences considerable load, or if the server software imposes limitation on the script execution time, you can re-index step by step (3*). In this case, you can set the amount of time to elapse between indexing steps.
- Again, if your server has not enough processing power and you have large files, you can limit size of files that are allowed to be re-indexed (2*).
: additionally, you can specify types of files to be included in the index, in the module settings (Settings
-> System settings
-> Module settings
, choose Search
in the drop-down list):
- Include files: this field define files that can be be indexed;
- Exclude files: files with pathnames that match at least one of these wildcards will not be indexed.
The Search module supports morphological search. It means that the search algorithm considers all grammar forms of words when creating the search index and searching for the requested phrases.
For example, when indexing the word child, the system adds both child and children to the index. Similar rule applies to verbs: for bring, the system adds bringing, brought etc. Consequently, if a visitor searches for a phrase "children bring", the system will display all results containing child, children, bring, bringing, brought etc.
To enable morphological search, mark the corresponding option in the Search module settings. Then, re-index the site entirely:
Note: The morphological search algorithm splits sentences into words using the common delimiters (space, full stop, comma etc.) At the same time, there are symbols which are not letters but may be parts of words: for example, dash (-). To prevent the morphology algorithm from unwanted splitting, specify symbols that the analyser must treat as constituents of words (in the Symbols that are not used as word delimiters field).
Adding search function to your site
You can give your visitors two options to search the site: by using a search form and/or by providing a special search page.
The Search form in which visitors can type required keywords and quickly get results, is added to the site template by using a special component.
The appearance and placement of the form depend on the site design. For example, it may look like the following:
When a visitor clicks Search, the system performs the search and takes the visitor to a search page.
The search page contains a special field in which a visitor can type the search text. The search page also displays the search results.
The search page can be created by adding the special visual component (Common Search Page). This component can be added to any page when editing it in the visual HTML editor.
If required, you can customize the component parameters and appearance in the component property bar.
Examples of using the "Search page" component
- To constraint searches to only static pages, select Static files in the Restrict search area field and click OK:
After you have clicked OK, an additional field group (URL starts with any of the following paths) will be added to the component property bar. In these fields, you can specify the folders and/or files in which the search is to be performed. For example:
- You can limit the search to only dynamic information. For example, your site contains a News page where the e-store news are published (using the e-Store News information block, type News). Assume we need to allow visitors to search news.
The following actions are to be performed to achieve this.
- Add the Common search page component to the news page.
- Customize the component in the following way.
In the component property bar, select the type of information blocks in which the search is to be performed (in the Restrict search area field), and click OK.
After that, the Search in the information blocks of type... list will appear in the property bar. In this list, select the information block (in this case, e-Store News) whose elements can be displayed on the search results page:
Now, the search page can look like the following:
After a user enters the search query and clicks Search, the system searches the index and selects pages matching the query. Before results are displayed to a user, they are sorted:
- by relevance (which is usually defined by density of keywords on a given page);
- or by the page timestamp.
Users can choose the sorting mode on the search result page by clicking on one of the links: Sort by relevance or Sort by date.
Sometimes you may need give preference to certain documents when displaying the search results. For example, you may want to put goods that are to be sold out as soon as possible, higher in the search results. To achieve this, a special facility has been developed allowing to assign a required weight (page rank) to required pages. Pages matching the specified ranking criteria will be put at the top of the search result list, according to page ranks indicated in the ranking rules.
A fixed rank can be assigned to:
- static files (requires full path to be supplied);
- information blocks (you can specify an information block type, an information block and an element which should have the specified priority);
- forums (the required forum, a forum thread and a message can be specified).
You can create and manage ranking rules in the Search result sorting rules form (Settings -> Search -> Search result sorting rules):
Adding or modifying a rule involves two steps:
- ranking rules management: creating, modifying or deleting ranking rules;
- search index update.
To create a new rule, click Add on the context toolbar. This will open the rule editing form:
In the form, you have to select the site and the module to which the rule will be applied. Meaning of the other fields depends on the selected module:
- static files: you can specify the priority of a required file;
- information blocks: you can specify the priority of a chosen information block type; information block; information block section and element;
- forums: you can create ranking rules for the selected forum, forum thread or a forum message.
After save, the rule is added to the list:
After you have created a new rule or modified an existing one, you have to refresh the search index by clicking Update:
After the update process completes, results are displayed:
Note: For any changes in rules (modification or deletion ) to take effect, you also have to update the index.
The Google Sitemap is a new while very comprehensive tool, which is used to dispatch information about site pages to the Google database. Google Sitemaps are particularly essential when used with dynamic sites whose pages are generated automatically since it ensures that the Google database will have the complete information about all site pages.
In its core, the Google Sitemap is an XML file. Despite the fact that the file format is simple, creating a Google sitemap is a tedious task taking much time. The Create Google Sitemap form will help you create your sitemap (Settings -> Search -> Google Sitemap):
Note: If your server experiences excessive load, you may want to create the sitemap in several steps. Specify the duration of a single step in the Step duration field.
When the sitemap is ready, you will see brief instructions on how to dispatch your sitemap to Google, as well as the sitemap link for downloading:
Sphinx search set up
External full text search Sphinx is available in Bitrix products v. 14.0.0. It ensures fast and efficient search on site, reduces the server load, and is fully integrated in Search module components.
If for any reason the reference environment Bitrix Virtual Appliance v. 4.3 and higher containing Sphinx is not applied, you can set it up by yourself according to the following recommendation.
- First of all, you need to install the Sphinx package in your environment. See documentation the section Installation on the official website for the procedure description.
For example, suppose the default Sphinx settings file directory is /etc/sphinxsearch/.
- You have to set up Sphinx using the configuration file /etc/sphinxsearch/sphinx.conf.
Minimal configuration code
The basic directives that can be changed depending on the server settings and that must be considered are:
listen – indicate IP, port, Unix-domain socket path or protocol listened by search daemon (in this case, these are ports 9312 and 9306 with MySQL protocol);
log – name of log-file governing Sphinx operation and its location;
query_log – name of log-file governing Sphinx search requests and its location;
binlog_path – path to binary logs location (this parameter is important since if you indicate the directory without permission to its log the search daemon is not started);
binlog_max_log_size – maximum size of binary log file after which new file is created.
lemmatizer_cache – maximum the size of morphological search vocabulary cache;
lemmatizer_base – directory to store language vocabularies (ru.pak, en.pak, de.pak) for morphological search that you must preliminarily download and put into the present directory.
Section index bitrix
Go to Bitrix product page Search module settings (Control Panel > Settings > System settings > Module settings > Search) ) and set up the Sphinx connection as a search engine:
path – index files path and names;
charset_type – site code:
- for UTF –
- for others –
After the settings are applied in the Search module, click the button Re-index website now in the Administration section to reindex the site:
- Use full text search engine – select Sphinx;
- Connection string for index control (MySql protocol) – indicate IP and connection port for indexing using MySql protocol;
- Index ID – indicate index name (e.g. bitrix);
- This page also contains a sample of the configuration file for the Sphinx index in Bitrix products (only for reference).
. If Bitrix products have the Social Network module installed, indexing using the search module must be followed by the reindexing of the social network in the public section. To do this, go to any section of the social network in development mode (where socialnetwork
, socialnetwork_user components
are installed) and click Reindex
Now, the minimal set up of Sphinx as the Bitrix products search engine is finished.
. For more information on the Sphinx search engine tuning, see the
official documentation on this product.
A comprehensive web-portal, no matter whether it's an information site or an online-store, is so
stuffed with various features that users may find it hard to navigate it. In addition, many
companies would like to quickly respond to clients' questions thus maintaining the company
reputation. It's especially important for web-portals tailored at providing to clients online
consultations related to software and hardware performance, etc. A properly structured and organized
site should be able to promptly react to clients' requests and address them to technical support
engineers according to topics.
The Helpdesk module was designed to:
- implement the ticket submission system enabling visitors to contact the technical support specialists;
- manage service level agreement preferences (SLA);
- register ticket response time and efficiency;
- analyse user replies.
Setting up your helpedesk service
The procedure of creating and handling a ticket received by the technical support service is controlled by the service level agreement (SLA).
SLA is a formal agreement between a company and users to provide a certain level of service (in our case, technical support).
- Each user group entitled to create a ticket is assigned a certain SLA which defines the ticket response time and some parameters.
- Users can use the following three methods to create tickets:
- via standard forms on the site;
- via the e-mail;
- via phone call.
Also, certain forum messages (e.g. concerning purely technical problems or that are beyond the forum subject) can be moved to the technical support service. A message can be moved by the site or forum administrator.
Each message is assigned a unique ID which simplifies registering and handling new tickets.
- A technical support ticket is handled according to the SLA preferences. Reply is published on the site and is sent to a user via the e-mail. Only the user who has created the ticket and technical support specialists can view the discussion.
The technical support interface consists of two parts:
- administration which can be accessed via the Control Panel
A common practice for techsupport clients is to access the public interface, while the specialists handle requests in the administration interface. Administration and public interfaces are different in design and functions.
The following roles are used to manage the Helpdesk module user access permission levels.
- Technical support clients are entitled to access the ticket administration menu; they are allowed to create and edit their own tickets in administration and public files.
A technical support client is notified about all events occurring to their ticket via the e-mail (e.g. about ticket status changes, responsible person assignment; ticket reply etc.). Also, when creating a ticket, a user receives notification containing the original ticket information (the ticket number, name of the default responsible person etc.).
- Technical support specialists can access all menu items and Helpdesk pages. They handle tickets for which they are responsible.
A technical support specialist is notified via the e-mail about all events occurring to their tickets. A new responsible person receives the notification containing the ticket information.
- Technical support administrator can edit the technical support dictionary and any ticket as well as assign responsible persons. The administrator receives e-mail messages about all tickets addressed to the technical support service.
Reference book contain information related to client requests to the helpdesk. This information is for reference only and does not affect ticket processing.
Before starting to use the Helpdesk module, it is a good idea to configure the required dictionaries. This allows to:
- automatically assign responsible persons to tickets depending on the ticket parameters and content;
- group incoming tickets;
- track problem complexity and solution efficiency.
Ticket category is an area to which a ticket refers (for example: Bugs, Order payment). Categories are configured here: Services -> Helpdesk -> Reference book -> Categories.
When creating a ticket, a user can select an appropriate category (from the list) to which the described problem refers:
The list of categories that are available to a user is defined by SLA.
Ticket criticality determines the ticket significance (i.e. how urgent is the problem described by the user). For example: Low, Middle, High.
Reference book preferences are configured here: Services -> Helpdesk -> Reference book -> Criticality.
The criticality level is assigned by a user when creating a ticket. This information is for reference only.
The list of criticality levels that are available to users is defined by SLA. Having elaborated on a problem, a support specialist can change the ticket criticality level.
Statuses show the stage of ticket processing, for example: Request accepted, Problem solving in progress, Successfully solved etc.
The list of statuses is created at Services -> Helpdesk -> Reference book -> Statuses.
The ticket status can be assigned to it by the support specialist.
The Answer rates dictionary contains marks that a techsupport client can assign for a given response.
The list of available marks to users is defined by SLA.
You can configure marks at Services -> Helpdesk -> Reference book -> Answer rates.
Marks are used to control the quality of technical support.
The Difficulty dictionary contains description of ticket difficulty levels that can be used, for example, to control the response time.
The dictionary is configured here: Services -> Helpdesk -> Reference book -> Difficulty.
The ticket difficulty is estimated by the support specialist:
Frequently used answers
Replies that are used more frequently can be saved in the Frequently used answers dictionary: Services -> Helpdesk -> Reference book -> Frequently used answers.
Later, typical answers can be used when replying:
This allows to reduce the time spent to process frequent questions.
Service levels can be configured on the Support levels (SLA) page (Services -> Helpdesk -> Support levels).
How to assign the ticket duty
Responsible person is a techsupport staff member liable to resolve tickets and problems.
Responsibilities can be distributed:
- automatically (according to the pre-set parameters);
- manually by a technical support administrator.
The following parameters are considered when a responsible person is assigned automatically:
The technical support administrator can assign or change the responsible person when viewing the ticket:
Functions available in the public section
Using public interface
Working in the public interface
In the public section, a user is entitled to view their tickets and responses only.
A technical support specialist communicate with a client in the private form. That is, other site visitors are not allowed to view tickets created by the client.
Technical support administrators can view all messages, while specialists can view only messages for which they are responsible.
The following information is displayed for each ticket:
- a unique ticket ID;
- the date when the ticket was last modified, and the name of a user who modified the ticket;
- ticket category (if specified);
- specialist responsible for the ticket (depends on the category and the SLA);
- the level of urgency;
- current status of the ticket.
To create a ticket, click Create new ticket.
The ticket creation form allows a user to:
- attach files containing additional required information (for example: screenshot illustrating an error);
- set the ticket emergency level;
- select the ticket category.
If needed, a ticket can be modified after it has been created:
How to send a message via the e-mail
Messages sent via the e-mail are handled using the Mail module rule.
- The Mail module can have an account to which tickets will be forwarded to reach the technical support service. For example, Support:
- Rules can be configured for the created account to stipulate that the forwarded messages will be put into the list of Helpdesk tickets:
Rules are created using the Helpdesk e-mail template.
- The demo version includes examples of rules to add tickets to the techsupport service.
- Rules that are used to add tickets can be applied for any existing account.
The Conditions tab sets prerequisites that define how messages (tickets) will be added to the techsupport service.
For example, the conditions on the above figure:
How to add message from the forum
If required, administrator can moved a message from the forum to the Helpdesk module using the Add to Techsupport button:
This may be necessary if a message touches complicated technical questions that are beyond the forum subject.
Creating public interface
You can easily create a technical support section for your site using the composite component Helpdesk.
This component creates a fully functional technical support system that features viewing ticket lists, adding new tickets and messages.
When setting the component properties, remember to specify the ticket address. If the Enable SEF support
option is unchecked, specify the name of a variable that will pass the ticket identifier:
But, if the option is enabled, specify the SEF folder, the path to the ticket list page, and the path to the ticket editing page:
Functions of the Helpdesk control panel allow to implement the following
- configure ticket parameters (emergency level. ticket
statuses, reply score etc.);
- view and reply to the user techsupport tickets.
Administration interface includes:
- list of tickets;
- dictionary tools and SLA (see earlier).
The summary on incoming tickets and reports about helpdesk service perfromance are available on the Desktop page (Services -> Helpdesk -> Desktop).
Summary reports are the review tables showing the number of assigned, closed and open tickets:
- by responsible specialists;
- by emergency level;
- by the current status
- by category;
- by ticket source;
- by ticket reply score.
The Ticket page displays tickets received by the technical support service. Special indicators help determine the present state of tickets:
- - your party replied to the ticket last time (you are responsible);
- - your party replied to the ticket last time (you are not responsible);
- - the last reply is yours;
- - helpdesk staff member updated the ticket last time;
- - ticket is closed.
Moreover, a notice can be displayed beside the indicator:
- Reply here! Means the reply period stipulated by SLA is about to expire;
- Expired! Means the reply period is expired.
The page filter parameters stipulate that tickets are displayed to a helpdesk specialist who is responsible for them:
- Expired messages are displayed on top of the list (Expired!);
- Then, messages whose reply period is about to expire (Reply here!);
- Other messages are displayed on a first-served basis, according to the reply date (stipulated by SLA).
If a helpdesk staff member has replied to a ticket, the ticket is marked green and moved to the end.
The ticket position will not change if:
- the author has modified or updated the ticket with additional information;
- a helpdesk specialist has added a comment or a hidden message to the ticket.
All tickets that are to be replied shortly (yellow or red indicator) are displayed to the helpdesk administrator by default.
To reply to a ticket, double click it in the list or click the respective context menu item to open the ticket editing page:
The ticket view form consists of three parts:
This part holds the following data:
- site where the ticket was created;
- ticket source (e-mail, phone number, web form, forum) and the author;
A user ticket (for example, via the phone call) can be registered by the administrator or by a helpdesk staff member. The ticket is bound to a certain user in the system using the Author field. Thus, further discussion will be in the context of the ticket.
- the date when the ticket was created and modified;
- the time and date of the last efficacious reply (i.e. the reply that changed the indicator colour to green).
This part contains:
- the list of all the ticket messages;
- records (logs) about actions of both helpdesk specialists and ticket author (yellow indicator). For example: about a reply to a ticket, ticket update, assigning the responsible etc.;
- records about system actions (pink indicator). For example: about indicator change, ticket expiry, ticket autoclose etc.
This section is used to create the ticket reply. The following modes can be used:
The default message mode is selected in the Helpdesk module settings (Settings -> System settings -> Module settings -> Helpdesk).
If a message is opened in the View mode, switch to the Reply mode to reply to the ticket:
Note! The current mode button is inactive and is highlighted with yellow.
List of users who opened the message is displayed in a special area located on the left.
For each user, a mode icon is displayed:
- - view mode:
- - reply mode.
This allows to set up teamwork with tickets and prevent ticket update collisions that may occur if more than one user try to reply to a ticket.
Users viewing the message are updated automatically according to the Helpdesk
link updates the list if users currently viewing the message.
Switching to the Reply mode starts reply timing.
Thus, if a message is opened in the Reply mode by default, timing starts immediately.
While handling a message, a helpdesk specialist can:
Reply to a ticket.
Note! If a created reply is just a remark (e.g. about current helpdesk actions) and is not a final decision, you might want to preserve the current ticket status. To do so, check the Do not change ticket status box.
- Create a hidden message which will be available to the helpdesk staff members only;
Set status, emergency level, difficulty, category, SLA and assign a specialist responsible for the ticket.
If the SLA or category is changed, the default specialist specified in the SLA or category parameters can be assigned as responsible for this ticket. For that, the
icon is used, which is located beside the corresponding field.
- If a ticket cannot be replied within the short time or it has to remain actual, the ticket can be saved as deferred. The current status (ticket indicator) will not change.
- Check the Close ticket box to close the message.
- The option Close after no responses more than defines the expiring time after which the ticket will be automatically closed.
A ticket can be closed automatically if the author has not added more messages to the ticket after the helpdesk specialist reply.
The default value of this field is specified in the Helpdesk module settings.
According to the mail template settings, messages about ticket changes (for example: about a reply, status change etc.) are forwarded to the e-mail addresses of the ticket author, responsible specialist and helpdesk administrator.
A report can be created in the form of a graph or a diagram by the following indexes on the Graphs page:
- techsupport load:
- resolution duration:
- number of messages required to solve the task:
Bitrix Site Manager is equipped with a bunch of special tools, which administrators can use to
check the server for hardware and software requirements compliance; verify and repair the database;
create the database back-up etc.
In this section, you will know about features of the system tools, and how to use them.
Using system tools
Settings -> Tools -> System check
The System check form helps to thoroughly examine the parameters compliance of system on which Bitrix Framework runs.
The form displays information grouped in the following sections.
Settings -> Tools -> File checker
The File check form helps administrators control changes in the system files. Here an administrator can enter a check word (in fact, the word is a password which is known to the administrator only) and calculate the checksum of all files of the site. The checksum depends on the password. The password is not stored anywhere.
The check result file contains information on each file checksum and status. Store the file on your local computer to prevent its loss. In future, you can always perform the check again using the same check word and compare results.
Settings -> Tools -> PHP Settings
This form displays the current PHP settings obtained by calling phpinfo().
Settings -> Tools -> SQL Query
You can use the SQL Query form to execute an arbitrary SQL command.
The system does not place any restrictions on your SQL queries. You must be extremely attentive when running statements like UPDATE, DELETE, DROP etc.
PHP Command Line
This form (Settings > Tools > PHP Command Line) can be used to run a PHP script on the server side.
Settings -> Tools -> Agents
The Agents technology allows running PHP functions (agents) at a specified time interval. When a page starts execution, the system automatically checks for pending agents and executes them if required.
The agent run time precision depends on the site traffic density and uniformity. If you need to precisely run any PHP function at the time specified, you should use cron, which is permitted by most hosting providers.
The report displays agents that currently exist in the system:
To add a new agent, click Add on the toolbar.
Settings -> Tools -> Backup
To help developers move their sites between servers, the system offers a special facility allowing to create back-up copies of the site. It can:
- create back-up copy of all files (tar.gz);
- exclude kernel folders;
- exclude files exceeding the specified limit;
- export (dump) database tables (tar.gz);
- exclude statistics and the search index from the dump.
All created files can be downloaded from the site and used on the other server.
To extract files from the archive, you will use the special script which is uploaded to the server with the archive.
If you encounter errors with MySQL /MyISAM tables, you can use the built-in database tool to check and repair tables.
Please note the following.
- The database check tool can be used with MySQL / MyISAM tables only.
- To run the database check tool, open Settings -> Tools -> Database check and click Check /repair tables:
In case the statistics tables are damaged and you cannot access the Control Panel, you can disable statistics by supplying ?no_keep_statistic_LICENSE-KEY=Y in the page URL. Replace LICENSE-KEY with your valid license key, literally.
- As a last remedy, you can run the database check script (/bitrix/admin/repair_db.php) without having to access the Control Panel.
To run the script, you will need to supply the database login and password in the URL. For example: http://www.mysite.ru/bitrix/admin/repair_db.php?login=DB_Login& password=DB_Password
If these parameters are omitted, their default values will be taken from /bitrix/php_interface/dbconn.php.
Situations may happen when a site denies to reply and returns an empty page to visitors. In this case, open bitrix/php_interface/dbconn.php (contains the database connection parameters), and set the following parameter: $DBDebug = true;
This will cause the error message to be printed. The message usually contains names of damaged tables. If the database damage is the case, you are recommended to use the built-in database check and repair tool. This will allow you to restore the site functionality in the shortest possible time.
The "Component Cache" Tab
The Autocache technology exists to prepare the website and the components for stress load conditions, or adapt the website for operation on virtual servers. The Components 2.0 development concept assumes that developers provide explicit autocache technology support in their projects.
To enable or disable autocache, use the Enable Cache (or Disable Cache) button on the Cache Settings page (Settings > System Settings > Cache Settings) page.
when the autocache mode is on, the components whose cache parameter is set to 'Auto + Managed' will use caching.
To take advantage of the new autocache technology, all a non-IT user needs to do is click the button on the Control Panel toolbar in the public section. This will force all the components whose mode is 'Auto + Managed' to create a private cache and use the cache data without issuing excessive database requests.
Whenever you need to refresh the cached data for any reason, do one of the following.
- Open a page whose contents needs to be updated and click Refresh Page Cache on the Control Panel toolbar:
Note that a component whose cache is being reset may be linked to user groups (see the Regard Access Permission option). If this is the case, the cache will be refreshed only for users who are the members of the same user groups as a person initiating cache reset.
If this option is checked, the system uses different cache for different user groups.
Effectively, checking the Regard Access Permission option entails not refreshing the page contents for unregistered visitors.
The Refresh Component Cache command invalidates only the cache of the components that are on a current page, while the Refresh Page Cache command invalidates the whole page.
- When in edit mode, use the cache controls on the component toolbars:
- For an individual component, the cache timeout feature exists. To activate it, simply select the Cache or Auto+Managed cache mode.
- The components may also reset the cache whenever source data changes. To activate it, use the Auto+Managed cache mode.
- Switching to uncached mode resets the cache contents as well.
The components whose cache mode is Auto+Managed invalidate the cache contents automatically on timeout or whenever data changes.
The components whose cache mode is Cache and the cache timeout period is not zero, always operate in cached mode.
The components whose cache mode is Don’t cache or the cache timeout period is zero, always operate in uncached mode.
The "Component Cache" Tab
Use Enable Managed Cache button to activate this feature. Disabling it is not recommended.
The Cache Dependencies technology automatically refreshes the component’s cache whenever source data changes. Therefore, if the managed cache feature is enabled, you will not have to update the cache manually every time you make changes to your website.
not all components support managed cache technology.
The yellow tip below the cache preferences in the component parameters shows the current system settings:
The current implementation of the Сache Dependencies technology is capable of storing the cache in files as well as using Memcached, APC or eAccelerator. To select the required cache storage, edit one of the configuration parameters.
The "HTML Cache" Tab
The controls on this tab allow a system administrator to enable, disable or edit the HTML cache parameters.
|Inclusion mask||Specifies the files that will be controlled by the HTML cache.|
|Exclusion mask||Specifies the files to avoid when building and managing the HTML cache.|
|Disk quote||Specifies the maximum cache size, in MB.|
Important! It is not recommended that you enable HTML cache if your system contains Web Analytics or Advertising modules.
HTML cache works best for rarely updated sections available to anonymous visitors because:
- the HTML cache engine processes only the pages matching the inclusion mask;
- whenever an authorized visitor hits one of those pages, the engine looks up the cache for this page and, if the latter is found, shows the cached page without querying any of the underlying modules, components or database records. In practice, it means that such visits will not be recorded in statistics and no proper advertisement will be shown;
- if the Compression module was active when creating the page’s cached version, the page will be transferred to the client in compressed form;
- if the engine cannot find the page in the cache, the page will be executed in normal mode and the output will be added to the cache.
The cache is purged completely or partially:
- if the new cache size exceeds the specified quota – the cache is deleted completely;
- if any change occurs in Control Panel – the cache is deleted completely;
- if a POST request occurs in public section – the corresponding cache portion is deleted.
To summarize the HTML cache features:
- no statistics collection occurs;
- the advertising module is called only when a page does not exist in cache and needs to be created (this does not include external banners like GoogleAds etc.);
- you must specify the disk quota to prevent DDoS attacks;
- once the HTML cache engine is enabled, you must double-check the whole section to which the HTML cache is applied (for example, you may encounter problems adding comments if outdated blog templates was used when creating the cache).
The "Delete Cache Files" Tab
Use this tab to delete outdated or faulty cache data.
|Only outdated||Deletes the pages whose lifetime expired.|
|All||Deletes the cache completely.|
|Menu||The menus may become redundantly cached when checking the menu links for validity. This option deletes such menu data. |
|All managed cache||Deletes all files in /bitrix/managed_cache/.|
|All pages in HTML cache||Deletes all pages from the HTML cache.|
Once the cache has been purged, the newly requested data will be actualized and added to the cache.
For best performance, the server software must be properly configured. To unveil weak points in the server software configuration, Bitrix Site Manager offers a range of system tools which will be of much help for a system administrator. So one of these tools, a Performance Monitor, is the subject of this chapter.
To access Performance Monitor global settings, browse to Settings > System Settings > Module Settings > Performance Monitor.
This form has the following options.
- Maximum URL display length: specifies the maximum displayable length of URL strings when showing URL’s on the module pages.
- Log queries: if checked, all the SQL queries will be logged. To view the SQL log, open Settings > Performance > SQL Queries.
- Log PHP warnings: enables PHP error and warning logging. To view the error log, open Settings > Performance > PHP Errors.
- Enable monitor: if any option other than no is selected, runs the performance monitor for the specified period of time. This is functionally analogous to the Test Performance button on the Performance Panel page.
If the monitor is enabled, the Monitor activity field will be showing “running”, and the time left.
- Clear existing stats: specifies to delete all the collected data by clicking Save or Apply.
You can configure access to this module for different user groups in the same way as you would do for any other Bitrix Framework module.
To test performance from within the public section, click the button Performance
. This will show the monitor statistics right on the public webpage, which comes in handy when debugging individual pages:
When debugging from Control Panel, you will also see the SQL query statistics, page execution time and compression information. You may choose which information to display by clicking the drop-down arrow of the Performance button.
- SQL query statistics: specifies to show SQL query performance information;
- Include area statistics: specifies to show statistics of include areas (execution time, queries);
- Page execution time: shows the entire page execution time;
- Compression statistics: shows some useful compression information;
- Statistics summary: a shortcut to select all of the options except compression statistics.
The page generation time, SQL statistics and compression information are displayed at the page bottom:
The Total SQL Queries link opens a detailed report of all the database requests performed while building a page.
If the options Page execution time and SQL query statistics are both selected, the Page generation time field is a link:
which shows the page statistics in a special form:
However, if the Statistics summary option is selected, the Page generation time link shows a much more detailed report:
Click the links in the top portion of this form to show the respective information. Use the links in the bottom section to view the request information.
The Request Information
To view information about requests performed by a component, select the Include area statistics menu item and then click a link showing Queries: X, in the statistics area beside the component:
This will open a form showing the request statistics details:
The bottom area of the form displays the request details. Use the links in the upper area to view the details of a required request.
The Module’s Control Panel Forms
The following pages comprise the user interface of the Performance Monitor module in Control Panel:
You will find below the Performance folder (select Settings > Performance).
To view the page traffic data, use the “Performance monitor: Pages” form (Settings > Performance > Pages):
You can view all the hits done to a page by clicking the page name link. Effectively, this opens the hits statistics form.
The “Performance monitor: Hits” form (Settings > Performance > Hits) shows the hits report:
Beside each page, you will find a link shown as two angle brackets (>>). Use it to open a corresponding page in the public section and view the page statistics:
A more detailed report is also available. Click Performance on the public section toolbar (or select Statistics summary in the button drop-down menu):
Wait until the hits summary is loaded, then find a required page and click a link (>>) to view the detailed statistics information:
To view all the SQL queries performed by a hit page, click the page name link or a respective number in the Queries column.
To view the components used by a hit page, click a number in the Components column.
The “Performance monitor: Components” form (Settings > Performance > Components) shows information about components and include areas used by the website pages:
To view all the SQL queries made by a component, click a number in the Queries column.
The “Performance monitor: Queries” form (<Settings > Performance > SQL Queries) shows summary of all performed SQL queries:
Note that this report is available only if the Log queries option is enabled in the Performance Monitor module settings.
To view the query runtime details, double-click the row showing a required query. This will open the query information in a new window:
When debugging a dynamic website, one of the most essential information a web developer needs is the database structure and the database table dynamics. To view the database tables summary, open Settings > Performance > Tables:
You can view the contents of a database table, click the table name link.
The system keeps track of the most recently viewed tables and makes them available for faster access in the context toolbar. To view one of the recently accessed table, select it in the Recently browsed tables.
Since version 11, it is possible to select rows from bound tables by filter. This feature is now supported for the Search module, those displaying contents of information blocks, and tables with ratings.
Consider the following example. Assume you have picked all the records with ID of 871 (in fact, the only records because the ID’s are unique).
You can hover the mouse pointer over the field values to view information stored in a table:
First of all, you have to get an estimation of your website’s performance. Open Performance Panel (Settings > Performance > Performance Panel).
The module would be of not much help if it showed only the web server performance scores. In fact, the main purpose of it is to find the bottlenecks preventing the website from normal operation. To do so, you have to keep the test running for a certain amount of time: a low traffic web project may require a hour or more, while a highly popular website needs less time. The system will register hits and gather statistics: page execution time, SQL queries and other parameters.
If your website is still yet to be launched, you may have to open pages manually or use some special testing software.
Reading the value on the screenshot shown above (performance = 16.23), one may deduce that the average generation time of a public webpage with an empty template and an empty work area is 1/16.23, or 0.0616 sec. In terms of speed, a web server is capable of creating 16 empty pages per second.
The performance score is in no way based on the performance of the file system, database, sessions or mail subsystem. The purpose of these and all other parameters are to help web developers and system administrators find weak points in the website.
This tab shows the current performance values of the web server subsystems. The reference values are also provided.
If any subsystem is out of the optimum range, the report shows a link opening essential recommendations.
Performance Monitor has no direct access to system resources, therefore the scores obtained by running PHP scripts are a bit more about the PHP interpreter than the server itself.
This tab shows the current system settings that have an immediate effect on the system performance, and the recommendations.
This tab shows average times for the web pages accessed while testing, and potential development errors.
To see the faulty page, click the page link in the first column.
Now let’s see what components this page is using. Click the number in the Components column of a required page. The following screenshot shows the components for the hit #4 at /catalog/furniture/illuminating.
Here we can see the components the page was using, the number of SQL queries and the caching type. #4 is just the uncached editable area gracefully reported by Performance Monitor.
Now we can check the SQL queries for this page (for #4). But how do we know which area (there are four of them) goes uncached?
If interested, you’ll find more details on using Performance Monitor in the public section in Public Interface lesson.
Since version 10.0 a built-in feature exist to test multithreaded and clustered systems.
There is an easy and straightforward method to verify the integrity of your website, find caching issues and other problems before release: just download the whole website to your local hard drive two or three times at a row. To do so, use the freeware wget tool for Linux/Unix. This tool is preinstalled in the VMBitrix virtual machine.
If you are performing the test on the development VM, you will, in fact, get the full-scale pre-release test at the minimum possible network delay. Running the test more than once is essential because the first run creates a cache, and the subsequent tests will be getting pages from it.
To repeat the test, run the last two commands again. If the testing freezes, you can abort it by pressing CTRL+C.
First of all, check if a PHP accelerator is installed. This software precompiles PHP scripts which increases speed considerably.
Verify that the open_basedir extension is disabled.
This is a fairly broad problem which can be concisely expressed by the two scenarios:
Of course there is a lot of reasons for these issues, but the prevalent causes are the following.
This part of the training course has not yet been completed. Please refer to the blog post for information about this topic.
This chapter deals with server scale tools to achieve fault-tolerant cluster system in an increased load environment and balancing of load, traffic, and data among several servers operating on Bitrix Virtual Appliance v5.x.
If Bitrix virtual machine or environment are already set up and located on the provider’s site, the option to select a server from among those offered by the host will appear in the server add-on menu:
After that, the server’s order status can be monitored at the provider’s on the page VPS Orders (Settings > Scalability > Orders).
This menu item permits creating an additional website on the server. To do so, just type the Site name and Site path:
The website will be deleted from the system following execution of the command.
In order to deactivate cron, the website shall also be selected from the pool list:
Now all events on this website will be performed on the agents.
This menu item makes it possible to update server software of Bitrix Virtual Appliance simultaneously on all servers which form part of the pool:
Following the execution of the update wizard all the servers which form part of the pool will have the same software versions of the Bitrix Virtual Appliance:
Following the execution of the role adding wizard (it may take a long time), the page will be loaded and a role selected on this server will be displayed.
To see detailed workload diagrams of various services on each server, go to the tab Load chart (Settings > Scalability > Load chart) and use the filter to select necessary server, category, and a time period you wish to see the diagrams for.
To order a server from the provider, select the necessary provider from the list when adding a new server to the pool.
After that, select the server with the configuration you need from the list of servers offered by the provider.
Following the execution of the command, the server will appear in the list of servers with the status Server granted:
In order to add a server to the pool, select the relevant item in the action menu: