These base classes provide standard CRUD (create, retrieve, update and delete)
methods, etc. <!--fixme why the etc? what else?? -->
The generated DAO object has:
* A property for each field using the actual field name, not the unique name
* A `links()` method which retrieves the links to other tables (off the foreign keys)
* An `import()` method and an `export()` method for ?
* A `fields()` method which returns an array of fields for that object keyed by the field's unique name.
* A couple of functions to define the labels for enumerated fields
Looking at the field 'pledge.amount' we see
```php
'pledge_amount'=>array(
'name'=>'amount',
'type'=>CRM_Utils_Type::T_MONEY,
'title'=>ts('Total Pledged'),
'required'=>true,
'import'=>true,
'where'=>'civicrm_pledge.amount',
'headerPattern'=>'',
'dataPattern'=>'',
'export'=>true,
'bao'=>'CRM_Pledge_BAO_Pledge',
'table_name'=>'civicrm_pledge',
'entity'=>'Pledge',
),
```
The key is the unique name but the 'name' field is the field's name and the 'where' field shows the MySQL description of it. We also see the data type and whether it is available for search or export.
Generally fields should be exportable unless there is a security reason or they are weird and confusing as the search builder is also driven by this setting.
Fields whose option values can be calculated will also have a `pseudoconstant` section.
the business logic of CiviCRM. The core logic of CiviCRM belongs in the
BAOs, for example they have the code that creates follow up activities when an
activity is created, or create activities and populating custom fields when a
pledge is created.
!!! note
Historically some BAOs had both `add()` and `create()` methods. Current practice
is to favour a single `create()` method.
### Form
In general each form page in CiviCRM maps to a file in one of
the form directories. Form files contain a class that extends CRM_Core_Form.
This class has different methods that the core calls before display to
check permissions, retrieve information (`preProcess`), display
the form (`buildForm`), validate the form (`formRule`) and carry out tasks once the
form is submitted (`postProcess`). Forms can display information from the BAO
to users and then call the BAO on submission. Generally each form has an
associated template (see below) which defines the form's html.
!!! Note
Logic in forms should support friendly user-interfaces but core application logic belongs in the BAO layer.
Moving logic to BAO layer facilitates unit testing and developing modernised front-end applications in the future.
## Traditional `CRM_*` classes (DAO, BAO, Form, Page)
!!! tip
Perhaps the best way to get to grips with the Forms is by experience and
experimentation.
### Page
If a CiviCRM screen is not a Form, it is probably a Page. Pages files contain a
class that extend CRM_Core_Page. Similar to the form class, Pages have methods
that are called before the page is displayed to control access, set the title,
etc. (`preProcess`), and when the page is displayed (`run`). Pages tend to
take information from the BAO to be displayed to users. In general, each
page has an associated template (see below) which is used to create the
html of the page.
### xml
This directory contains a menu directory which maps urls to CRM form or page
Historically, most code driving the functionality of CiviCRM was located in CRM_ DAO/BAO/Form/Page classes:
-**DAO** (*data access object*) classes extended PearDB-DataObject, which allowed a database table to be accessed like a php object (e.g. `$dao->fetch()`). These php files used to be generated from an xml document. Historically each DAO file corresponded to an entity (table) and contained metadata about the entity (table name, a list of fields, indices, etc.).
-**BAO** (*business access object*) classes extended DAOs, and added entity-specific functionality (e.g. creating event participants). These used to contain functions like `create()` and `del()` which mixed generic CRUD functionality with entity-specific logic.
-**Form** objects extended Pear-QuickForm, called BAO functions to read/write data, and added extra user-facing logic (e.g. checking if an event was full before registering). Form elements were assigned to a Smarty template for display.
-**Page** objects would fetch data and assign it to a Smarty template for rendering.
Although much CiviCRM core code still looks like this, a transition is underway to use newer patterns:
-**DAO** classes have all been reduced to an empty stub. They now extend a class which provides the old methods for backward-compatibility. The new way to read/write an entity is via [APIv4](../api/v4/usage.md) or `Civi::entity()`.
-**BAO** functions are in a process of deprecation. The new way to add entity-specific logic is via hooks or events.
-**Form** classes are still widely in use, but [Afform](../afform/overview.md) is a new way to write forms.
-**Page** classes are still heavily used, but some pages can be replaced with [SearchKit Displays](../searchkit/displays.md).
### Schema
This directory contains *entityType* files; each declares an entity.
For example the `Activity.entityType.php` file declares the *Activity* entity, defines its schema,
and describes other attributes of the entity such as title, description, field metadata, etc.
For details see the chapter on [CiviCRM Entities](entities/index.md).
### Xml
This directory contains the menu (router) which maps urls to CRM form or page
classes and controls access to these URLs using permissions.
## Templates
...
...
@@ -146,16 +65,15 @@ based on the class name.
For example, the class CRM_Member_Form_MembershipRenewal looks for a template
in `templates/CRM/Member/Form/MembershipRenewal.tpl`.
Templates are written in smarty, a common PHP template engine. Variables can
be passed to smarty using the assign() method which is available to all Form
Templates are written in Smarty, a common PHP template engine. Variables can
be passed to smarty using `$this->assign()` which is available to all Form
and Page classes.
Customising templates is discussed in more detail in 'Techniques'
Customising templates is discussed in more detail in the [Page Templates](templates/index.md) chapter.
## The API
The application programming interface (API) is stored in the `/api`
directory. Best practice for using the API is discussed in more detail in
'Techniques'
The latest version of CiviCRM's application programming interface (APIv4) is located in the `Civi/Api4`
directory. See the [APIv4 Usage](../api/v4/usage.md) chapter for details.
## bin scripts
The bin directory contains a variety of scripts that can be run to carry out
...
...
@@ -164,16 +82,17 @@ example the CiviMail 'send' and 'process' scripts. Others are run on a one-off
or occasional basis, e.g. update geo-coding.
## SQL
The SQL directory is automatically generated as part of a release. It contains
useful files like the SQL to create the database and insert demo data. Most
The SQL directory contains sql files that e.g. insert demo data. Most
developers will not need to edit files in this directory.
## l10n
This directory contains lots of automatically generated localisation files.
This directory contains automatically generated localisation files.
You should not need to edit this directory directly. You should instead use
CiviCRM's online translation tool transifex.
CiviCRM's online translation tool Transifex.
## Composer
Most 3rd party libraries are included via Composer. PHP libraries are downloaded to the `vendor` directory,
while most javascript libraries are (for historic reasons) placed in `bower_components`.
## packages
CiviCRM makes use of a lot of 3rd party packages for things like the database,
form, javascript and pdf libraries, wysiwyg editors and so on. You
shouldn't need to edit files under the packages directory.
## Packages
Older libraries that are not downloadable via composer are found in the `packages` directory.
