diff --git a/docs/best-practices/documentation-style-guide.md b/docs/best-practices/documentation-style-guide.md
index c7e3b50df4b65b79a43cff16cf311386a6c52976..a319d84991542b17f9fe4492eb0692516d3dcb9a 100644
--- a/docs/best-practices/documentation-style-guide.md
+++ b/docs/best-practices/documentation-style-guide.md
@@ -1,7 +1,7 @@
# Documentation style guide
All CiviCRM guides *(like this Developer Guide)* are intended to provide
-high-quality "finished" [documentation] (documentation.md)
+high-quality "finished" [documentation](/documentation.md)
about CiviCRM. This Style Guide page documents the standards we wish to
uphold to ensure all guides maintain this high level of quality.
diff --git a/docs/build.md b/docs/build.md
deleted file mode 100644
index 47d45f233ed31ae84cb204ad7749248acd656b7b..0000000000000000000000000000000000000000
--- a/docs/build.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# Building CiviCRM
-
-TODO:
-
-- Nightlies vs gitify vs civibuild
-- gitify
-- civibuild (https://github.com/civicrm/civicrm-buildkit/blob/master/doc/civibuild.md)
diff --git a/docs/core/architecture.md b/docs/core/architecture.md
index 9993d6edf53ff9c7abfdebb19228c696406a6270..8f8bf96f85acd8d1ba8341d1bbd50f28c6231dba 100644
--- a/docs/core/architecture.md
+++ b/docs/core/architecture.md
@@ -2,8 +2,10 @@
This chapter provides a general overview of the codebase organisation.
-In order to explore the directories inside the CiviCRM repository it is
-generally quickest to to make a local clone of the CiviCRM from GitHub.
+!!! tip
+ In order to explore the directories inside the CiviCRM repository it is
+ generally quickest to to make a local clone of the CiviCRM from GitHub,
+ or better yet install the [buildkit](/requirements/#buildkit).
!!! tip
The CiviCRM codebase is object oriented. If you aren't familiar with object
@@ -38,33 +40,76 @@ Namespaces are designated with "\".
Use `Civi` when creating new object-oriented subsystems (like `\Civi\API`).
## Business logic
+
Most of the business logic of CiviCRM, is found in the CRM directory (`CIVICRM_ROOT/CRM`).
This logic is the part of CiviCRM that
defines what it does and how it behaves
-(e.g. that allows people to register on events)
+(e.g. that allows people to register on events).
In this directory, you will find directories for core CiviCRM functions like
contacts, groups, profiles, deduping, importing, and the CiviCRM components
like CiviCampaign, CiviMail, Pledges, etc.
-Each of these directories is slightly different depending on what they do but
+Each of these directories is slightly different depending on their purpose, but
there are some common subdirectories: BAO, DAO, Form and Page.
### DAO
-DAO stands for data access object. Code in this directory exposes the contents
-of the database. The DAOs are automatically generated for each release based
-on the data schema. DAO objects tend to be instantiated in BAO classes.
+The CiviCRM **data access objects** (DAOs) are PHP classes that
+([e.g. `CRM/Pledge/DAO`](https://github.com/civicrm/civicrm-core/tree/master/CRM/Pledge/DAO))
+expose the contents
+of the database. The release script generates each DAO automatically based
+on the matching XML file in the [data schema](#database-structure). DAO objects tend to be instantiated in BAO classes.
+
+The DAO classes all extend the core
+[DAO base class](https://github.com/civicrm/civicrm-core/blob/master/CRM/Core/DAO.php)
+which itself is an extension of the external
+[DataObject class](https://github.com/civicrm/civicrm-packages/blob/master/DB/DataObject.php).
+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. Looking at the field 'pledge.amount' we see
+* A couple of functions to define the labels for enumerated fields
+
+```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.
-The DAO has a property for each field (using the actual field name, not the
-unique name). They also have standard CRUD (create retrieve update delete) type
-functions, etc. <!--fixme why the etc? what else?? -->
+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.
### BAO
-BAO stands for business access object. BAOs map to DAOs and extend them with
+BAO stands for business access object
+([example](https://github.com/civicrm/civicrm-core/blob/master/CRM/Event/BAO/Event.php)).
+BAOs map to DAOs and extend them with
the business logic of CiviCRM. A lot of the meat of CiviCRM is found 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.
@@ -108,7 +153,7 @@ and Page classes.
Customising templates is discussed in more detail in 'Techniques'
## The API
-The application programming interface (API) is stored in the api root
+The application programming interface (API) is stored in the `/api`
directory. Best practice for using the API is discussed in more detail in
'Techniques'
@@ -121,7 +166,7 @@ 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
-developers won't need to edit files in this directory.
+developers will not need to edit files in this directory.
## l10n
This directory contains lots of automatically generated localisation files.
@@ -134,24 +179,51 @@ CiviCRM makes use of a lot of 3rd party packages for things like the database,
shouldn't need to edit these packages directory.
## Database structure
-The database structure is defined in a series of XML files. These files are
-not packaged in the releases but are available in the Github repository. They
-are located in Civicrm/xml/Schema. All the folders within this directory also
-have folders in the main CRM folder which contain a DAO folder and generally a
-BAO folder too.
-Looking in `CiviCRM/xml/Schema/Pledge` we see 4 files:
-
-- files.xml
-- Pledge.xml
-- PledgePayment.xml
-- PledgeBlock.xml
+The database structure is defined in a series of XML files
+([example](https://github.com/civicrm/civicrm-core/blob/master/xml/schema/SMS/History.xml)).
+These files are
+not packaged in the releases but are available in the Github repository. They
+are located in
+[`/xml/schema`](https://github.com/civicrm/civicrm-core/blob/master/xml/schema).
+All the folders within the schema directory also
+have matching folders in the main
+[`/CRM`](https://github.com/civicrm/civicrm-core/blob/master/CRM).
+folder which contain the DAOs and BAOs.
+
+!!! Info
+ A [`GenCode` script](https://github.com/civicrm/civicrm-core/blob/master/xml/GenCode.php) (which calls the
+ [`CRM_Core_CodeGen_Main` class](https://github.com/civicrm/civicrm-core/blob/master/CRM/Core/CodeGen/Main.php))
+ performs the magic of translating the XML files to
+ the DAO PHP classes and the database table creation SQL scripts
+ `civicrm.mysql` and `civicrm_data.mysql` in the
+ [`/sql`](https://github.com/civicrm/civicrm-core/blob/master/sql) folder.
+
+
+Looking in [`/xml/schema/Pledge`](https://github.com/civicrm/civicrm-core/blob/master/xml/schema/Pledge)
+ as an example we see 4 files:
+
+- `files.xml`
+- `Pledge.xml`
+- `PledgePayment.xml`
+- `PledgeBlock.xml`
+
+The `files.xml` is just a list of the other files. Each of the other files describes a
+table in the database, defining both table-leve and field-level metadata
+including foreign keys and indexes:
-The files.xml is just a list of the other files. Each of the others represents a
-table in the Database. The XML files describe the database and are used to
-build both the DAO files and the new database SQL generation script.
+```
+<table>
+ <base>CRM/SMS</base>
+ <class>History</class>
+ <name>civicrm_sms_history</name>
+ <comment>SMS History can be linked to any object in the application.</comment>
+ <add>1.4</add>
+ <drop>2.0</drop>
+ ... etc
+```
-The XML describes fields, foreign keys and indexes, an example of a field definition is:
+An example of a field definition is:
```
<field>
@@ -165,3 +237,13 @@ The XML describes fields, foreign keys and indexes, an example of a field defini
<add>2.1</add>
</field>
```
+
+<!-- fixme:
+The field 'amount' in the table 'pledge' has a unique name to distinquish it from fields in other tables (e.g. contribute) with the same field. This isn't consistent in all tables and I am trying to find out the reason / rules for this. Also, I presume 'import' means the field is exposed for .... imports?.-->
+
+We can see that the above 'pledge_amount' field was added in CiviCRM v2.1.
+
+Occassionally tables are dropped from the core schema so will not have associated DAOs.
+For example, the
+[SMS history](https://github.com/totten/civicrm-core/blob/master/xml/schema/SMS/History.xml)
+table was dropped in version 2.0, as indicated by a `<drop>2.0</drop>` field.
diff --git a/docs/customize.md b/docs/customize.md
deleted file mode 100644
index 4f106477decc415a6e8d0a94a4bca6509e00354b..0000000000000000000000000000000000000000
--- a/docs/customize.md
+++ /dev/null
@@ -1,13 +0,0 @@
-# Customizing CiviCRM
-
-TODO:
-
-- *(Requirements: Don't need full git install)*
-- *(When possible, link to User/Admin Guide or other existing docs instead
- of giving details.)*
-- Custom fields, profiles, option groups, etc
-- webform_civicrm
-- Extensions (download+install; web and CLI).
-- (Maybe) CiviRules
-- (Maybe) CSS override
-- (Maybe) *.extra.tpl
diff --git a/docs/develop-deprecated.md b/docs/develop-deprecated.md
deleted file mode 100644
index 081885c0002da12f2045bd505d335b0cac52bf9d..0000000000000000000000000000000000000000
--- a/docs/develop-deprecated.md
+++ /dev/null
@@ -1,31 +0,0 @@
-# Deprecated developer instructions
-
-These instructions are for historical reference only, but may be of use if the newer processes don't suit your working environment.
-
-## Deprecated: Manual checkout from Github
-
-Steps:
-
-* Perform a standard CiviCRM install from tarball
-* Use the "gitify" command to replace the codebase with the latest code from git.
-
-Obtain the existing CiviCRM directory (such as `/var/www/drupal/sites/all/modules/civicrm` or `/home/myuser/src/civicrm`), then run the `gitify` command. You will need to adapt the command arguments, but a typical case would be:
-
- cd /tmp
- wget https://github.com/civicrm/civicrm-core/raw/master/bin/gitify
- bash gitify Drupal git://github.com/civicrm /var/www/drupal/sites/all/modules/civicrm --hooks
-
-If you develop for multi-CMS, then you might have one copy of CiviCRM (e.g. `/home/myuser/src/civicrm`) shared by each CMS. You can use `gitify` to setup this directory, and then use symlinks to share among CMSs:
-
- ## Create ~/src/civicrm
- mkdir -p ~/src/civicrm
- wget https://github.com/civicrm/civicrm-core/raw/master/bin/gitify
- bash gitify all git://github.com/civicrm ~/src/civicrm --l10n --hooks
-
- ## Replace an old symlink with new symlink
- rm /var/www/drupal7/sites/all/modules/civicrm
- ln -s ~/src/civicrm /var/www/drupal7/sites/all/modules/civicrm
-
-## References
-
-* [Wiki: GitHub For CiviCRM](https://wiki.civicrm.org/confluence/display/CRMDOC43/GitHub+for+CiviCRM)
diff --git a/docs/extend.md b/docs/extend.md
deleted file mode 100644
index ca1c5e05d88c39af897637c4450993df7723304f..0000000000000000000000000000000000000000
--- a/docs/extend.md
+++ /dev/null
@@ -1,8 +0,0 @@
-# Creating CiviCRM Extensions
-
-This page is moving. See [writing extensions](/extensions/basics).
-
-<!--
-TODO:
-- delete this page after redirection in place
--->
diff --git a/docs/extensions/config.md b/docs/extensions/config.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/config.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/docs/extensions/create-page.md b/docs/extensions/create-page.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/create-page.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/docs/extensions/custom-api.md b/docs/extensions/custom-api.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/custom-api.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/docs/extensions/custom-reports.md b/docs/extensions/custom-reports.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/custom-reports.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/docs/extensions/custom-searches.md b/docs/extensions/custom-searches.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/custom-searches.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/docs/extensions/customize-screens.md b/docs/extensions/customize-screens.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/customize-screens.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/docs/extensions/payment-processor.md b/docs/extensions/payment-processor.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/payment-processor.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/docs/extensions/permissions.md b/docs/extensions/permissions.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/permissions.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/docs/extensions/storing-data.md b/docs/extensions/storing-data.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/storing-data.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/docs/extensions/using-hooks.md b/docs/extensions/using-hooks.md
deleted file mode 100644
index 6863c09819bc0daadc3a33b2d746606cf5e36710..0000000000000000000000000000000000000000
--- a/docs/extensions/using-hooks.md
+++ /dev/null
@@ -1 +0,0 @@
-Coming soon!
diff --git a/mkdocs.yml b/mkdocs.yml
index 8738f8773976f7122da64636885fc5f682757fd1..ab2716279668acc7dcb6807aa18d808d820ea0cf 100644
--- a/mkdocs.yml
+++ b/mkdocs.yml
@@ -11,56 +11,73 @@ markdown_extensions:
pages:
- Home: index.md
- Basics:
- - Developer Community: basics/community.md
- - Prerequisite skills: basics/skills.md
+ - Developer Community: basics/community.md # page-tree = DONE
+ - Useful Skills: basics/skills.md # page-tree = DONE
+ - Planning Your Project: basics/planning.md # page-tree = DONE
+- Documentation:
+ - Writing Documentation: documentation.md # page-tree = NEED_PAGE_MOVE to /documentation/writing.md
+ - Markdown: markdownrules.md # page-tree = NEED_PAGE_MOVE to /documentation/markdown.md
+ - Style Guide: best-practices/documentation-style-guide.md # page-tree = NEED_PAGE_MOVE to /documentation/style-guide.md
+- Setup:
+ # buildkit: /setup/buildkit.md # page-tree = NEED_NEW_PAGE # summary: See Github README for download instructions. Alternatively, follow links and install particular tools as-needed.
+ - Debugging: dev-tools/debugging.md # page-tree = NEED_PAGE_MOVE to /setup/debugging.md
+- Core Development:
+ - When to edit core: core/hacking.md # page-tree = NEED_PAGE_MOVE to /core/deciding.md
+ # How to Contribute: /core/contributing.md # page-tree = NEED_NEW_PAGE # summary: General summary of process (git+issues+PRs+Mattermost)
+ - Codebase & Architecture: core/architecture.md # page-tree = DONE
+ # Reporting Bugs & Issues: /core/reporting.md # page-tree = NEED_NEW_PAGE
+ # Submitting a Patch: /core/patches.md # page-tree = NEED_NEW_PAGE
+ # Review Process: /core/review.md # page-tree = NEED_NEW_PAGE # summary: Detailed guidance on how to review PRs
+ # Verifying a Bug Fix: /core/verifying.md # page-tree = NEED_NEW_PAGE
+- API:
+ - API Intro: api/general.md # page-tree = DONE
+ - API Usage: api/usage.md # page-tree = DONE
+ - API Actions: api/actions.md # page-tree = DONE
+ - API Parameters: api/params.md # page-tree = DONE
+ # API Permissions: api/permissions.md # page-tree = NEED_NEW_PAGE
+ - API Chaining: api/chaining.md
+ # API Changes: api/changes.md # page-tree = NEED_NEW_PAGE
+- Extensions Development:
+ - Basics: extensions/basics.md # page-tree = DONE
+ - civix: extensions/civix.md # page-tree = DONE
+ # Creating Pages: extensions/create-page.md # page-tree = NEED_NEW_PAGE
+ # Storing Configuration: extensions/config.md # page-tree = NEED_NEW_PAGE
+ # Storing Data: extensions/storing-data.md # page-tree = NEED_NEW_PAGE
+ # Setting Permissions: extensions/permissions.md # page-tree = NEED_NEW_PAGE
+ # Adding API Functions: extensions/api.md # page-tree = NEED_NEW_PAGE
+ # Reports: extensions/reports.md # page-tree = NEED_NEW_PAGE
+ # Searches: extensions/searches.md # page-tree = NEED_NEW_PAGE
+ # Payment Processors: extensions/payment-processors.md # page-tree = NEED_NEW_PAGE
+ - Publishing Extensions: extensions/publish.md # page-tree = DONE
+ - Extension Lifecycle: extend-stages.md # page-tree = NEED_PAGE_MOVE to /extensions/lifecycle.md
+ - Troubleshooting: extensions/troubleshooting.md # page-tree = DONE
+ - Advanced patterns: extensions/advanced.md
+ #### Framework Reference:
+ # Bootstrap: /framework/bootstrap.md # page-tree = NEED_NEW_PAGE
+ # Cache: /framework/cache.md # page-tree = NEED_NEW_PAGE
+ # Components: /framework/components.md # page-tree = NEED_NEW_PAGE
+ # Database: /framework/database.md # page-tree = NEED_NEW_PAGE
+ # Resources: /framework/resources.md # page-tree = NEED_NEW_PAGE
+ # Upgrade: /framework/upgrade.md # page-tree = NEED_NEW_PAGE
+ #### Code Standards:
+ # PHP: /standards/php.md # page-tree = NEED_NEW_PAGE
+ # Javascript: /standards/js.md # page-tree = NEED_NEW_PAGE
+ # API: /standards/api.md # page-tree = NEED_NEW_PAGE
+ # Git: /standards/git.md # page-tree = NEED_NEW_PAGE
+ #### Testing:
+ # Testing: /testing/testing.md # page-tree = NEED_NEW_PAGE
+ # Other Reference:
+ # CiviMail: /reference/civimail.md # page-tree = NEED_NEW_PAGE
+ # CiviReport: /reference/civireport.md # page-tree = NEED_NEW_PAGE
+ # Payment Processing: /reference/payment.md # page-tree = NEED_NEW_PAGE
+- MISC TO REORGANIZE OR DELETE:
+ - Extensions files: extensions/files.md
+ - Some of the hooks: hooks-db.md
- Requirements: requirements.md
- - Planning your project: basics/planning.md
- - Build: build.md
- - Customize: customize.md
- - Extend: extend.md
- Develop: develop.md
- - Testing: testing.md
- - Writing Documentation: documentation.md
-- Development Environment:
- - Debugging: dev-tools/debugging.md
-- APIv3:
- - API Intro: api/general.md
- - API Usage: api/usage.md
- - API Actions: api/actions.md
- - API Parameters: api/params.md
- - API Chaining: api/chaining.md
-- Hooks:
- - How to Use Hooks: hook.md
- - All Available Hooks: hooks-db.md
-- Writing Extensions:
- - Basics: extensions/basics.md
- - Using civix: extensions/civix.md
- - Anatomy of Files: extensions/files.md
- - Advanced Patterns: extensions/advanced.md
- - Troubleshooting: extensions/troubleshooting.md
- # - Using hooks: extensions/using-hooks.md
- # - Customizing Screens: extensions/customize-screens.md
- # - Creating Pages: Forms/extensions/create-page.md
- # - Storing Configuration: extensions/config.md
- # - Storing Data: extensions/storing-data.md
- # - Setting Permissions: extensions/permissions.md
- # - Custom API Functions: extensions/custom-api.md
- # - Custom Reports: extensions/custom-reports.md
- # - Custom Searches: extensions/custom-searches.md
- # - Payment Processors: extensions/payment-processor.md
- - Publish: extensions/publish.md
-- Best Practices:
- - Documentation Style Guide: best-practices/documentation-style-guide.md
-- Core code:
- - Hacking the core: core/hacking.md
- - Architecture: core/architecture.md
-- Miscellaneous:
- - Extension Lifecycle: extend-stages.md
- - Markdown: markdownrules.md
- # - hookref-old: hookref-old.md
-- Deprecated:
- - Building CiviCRM from source: develop-deprecated.md
+ - hookref-old: hookref-old.md
- Hooks:
+ - Using hooks: hook.md # page-tree = NEED_PAGE_MOVE to /hooks/usage.md
- Database hooks:
- hook_civicrm_copy: hooks/hook_civicrm_copy.md
- hook_civicrm_custom: hooks/hook_civicrm_custom.md
@@ -177,3 +194,4 @@ pages:
- hook_civicrm_viewProfile: hooks/hook_civicrm_viewProfile.md
- Report hooks:
- hook_civicrm_alterReportVar: hooks/hook_civicrm_alterReportVar.md
+
diff --git a/redirects/internal.txt b/redirects/internal.txt
new file mode 100644
index 0000000000000000000000000000000000000000..8b137891791fe96927ad78e64b0aad7bded08bdc
--- /dev/null
+++ b/redirects/internal.txt
@@ -0,0 +1 @@
+