# Post Type Modules
Modules extend the functionality of a post type like Contacts or Groups. A modules can be used to add:
* Fields
* Workflows
* List filters
* Roles
* Other functionality
A module resembles what can be done through a plugin. The big difference is the instance admin can enable/disable the modules they want and the theme/plugins can package multiple modules.
With v1.0 the D.T theme has 2 main modules available by default: the DMM module and the Access modules.\
The DMM adds fields, filters and workflows that go with: coaching, faith milestones, baptism date, baptisms etc. These are fields needed for any DMM.\
The Access module focuses more on contact followup and come with fields like the seeker path, the assigned\_to and subassigned. It also adds our Follow-up filter tab on the lists page.
## Getting The Module List
```php
$modules = dt_get_option( "dt_post_type_modules" );
// check if the access module is enabled
if ( empty( $modules["access_module"]["enabled"] ) ){
return;
}
```
## How To Add A Modules
### Declaring The Module
Hook into the `dt_post_type_modules` filter.
```php
add_filter( 'dt_post_type_modules', function( $modules ){
$modules["module_key"] = [
"name" => "Module Name",
"enabled" => true, // default if the module is enabled. The admin's preference in the settings will take precedence.
"prerequisites" => [ "dmm_module", "contacts_base" ], //don't load this module unless these other modules are also loaded
"post_type" => "contacts", //the post type the module extends
"description" => "Field and workflows for follow-up ministries" //displayed on the wp-admin settings page.
];
return $modules;
}, 20, 1 );
```
### The Module Class
See dt-contacts/access-module.php as an example.
Keep in mind:
* extend `DT_Module_Base`.
* declare the $post\_type and $module public variables.
* call `self::check_enabled_and_prerequisites()` to only load if:
* the module is enabled in the settings.
* the prerequisites are also enabled.
```php
class DT_Contacts_Access extends DT_Module_Base {
public $post_type = "contacts";
public $module = "access_module";
public function __construct(){
parent::__construct();
if ( !self::check_enabled_and_prerequisites() ){
return;
}
//your filters
}
//your functions
}
```
# Adding Fields and Tiles.
## Adding a field to track
You need tell Disciple.tools that you want to track something new. Fields are defined in the theme’s custom post type file. And we give you a way to add to that list using the dt\_custom\_fields\_settings filter.
Here is an example on how to add a spoken language field on the contact:
```php
add_filter( "dt_custom_fields_settings", "dt_contact_fields", 1, 2 );
function dt_contact_fields( array $fields, string $post_type = ""){
//check if we are dealing with a contact
if ($post_type === "contacts"){
//check if the language field is already set
if ( !isset( $fields["language"] )){
//define the language field
$fields["language"] = [
"name" => __( "Spoken Language", "disciple_tools_language" ),
"type" => "key_select",
"default" => [
"english" => __( "English", "disciple_tools_language" ),
"french" => __( "French", "disciple_tools_language" )
],
"tile" => "contact_language"
];
}
}
//don't forget to return the update fields array
return $fields;
}
```
See [Field Options](/theme-core/customization/fields) for documentation on field types.
## Adding a Tile
```php
add_filter( 'dt_details_additional_tiles', 'dt_details_additional_tiles', 10, 2 );
public function dt_details_additional_tiles( $tiles, $post_type = "" ){
if ( $post_type === "contacts" ){
$tiles["contact_language"] = [ "label" => __( "Language", 'disciple_tools' ) ];
}
return $tiles;
}
```
Since the language field is already declared in the fields list with the "contact\_language" tile, D.T will take care of displaying the field.
## Add custom content
If you desire to display a field or element your own way you can also do so: Change the filter priority to determine the order of this code
```php
add_action( "dt_details_additional_section", "dt_add_section", 30, 2 );
function dt_add_section( $section, $post_type ) {
if ( $section === "contact_language" && $post_type === "contacts" ) {
?>
Wanna know something cool? D.T is translated into multiple languages. Check it out!
Here is the basic usage:
## Namespace and Endpoints
When the plugin is activated, a new namespace is added.
```
/jwt-auth/v1
```
Also, two new endpoints are added to this namespace.
| Endpoint | HTTP Verb |
| ------------------------------------- | --------- |
| */wp-json/jwt-auth/v1/token* | POST |
| */wp-json/jwt-auth/v1/token/validate* | POST |
## Usage
### /wp-json/jwt-auth/v1/token
This is the entry point for the JWT Authentication.
Validates the user credentials, *username* and *password*, and returns a token to use in a future request to the API if the authentication is correct or error if the authentication fails.
#### Sample request using AngularJS
```javascript
( function() {
var app = angular.module( 'jwtAuth', [] );
app.controller( 'MainController', function( $scope, $http ) {
var apiHost = 'http://yourdomain.com/wp-json';
$http.post( apiHost + '/jwt-auth/v1/token', {
username: 'admin',
password: 'password'
} )
.then( function( response ) {
console.log( response.data )
} )
.catch( function( error ) {
console.error( 'Error', error.data[0] );
} );
} );
} )();
```
Success response from the server:
```javascript
{
"token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJpc3MiOiJodHRwOlwvXC9qd3QuZGV2IiwiaWF0IjoxNDM4NTcxMDUwLCJuYmYiOjE0Mzg1NzEwNTAsImV4cCI6MTQzOTE3NTg1MCwiZGF0YSI6eyJ1c2VyIjp7ImlkIjoiMSJ9fX0.YNe6AyWW4B7ZwfFE5wJ0O6qQ8QFcYizimDmBy6hCH_8",
"user_display_name": "admin",
"user_email": "admin@localhost.dev",
"user_nicename": "admin"
}
```
Error response from the server:
```javascript
{
"code": "jwt_auth_failed",
"data": {
"status": 403
},
"message": "Invalid Credentials."
}
```
Once you get the token, you must store it somewhere in your application, e.g. in a **cookie** or using **localstorage**.
From this point, you should pass this token to every API call.
Sample call using the Authorization header using AngularJS:
```javascript
app.config( function( $httpProvider ) {
$httpProvider.interceptors.push( [ '$q', '$location', '$cookies', function( $q, $location, $cookies ) {
return {
'request': function( config ) {
config.headers = config.headers || {};
//Assume that you store the token in a cookie.
var globals = $cookies.getObject( 'globals' ) || {};
//If the cookie has the CurrentUser and the token
//add the Authorization header in each request
if ( globals.currentUser && globals.currentUser.token ) {
config.headers.Authorization = 'Bearer ' + globals.currentUser.token;
}
return config;
}
};
} ] );
} );
```
The **wp-api-jwt-auth** will intercept every call to the server and will look for the authorization header, if the authorization header is present, it will try to decode the token and will set the user according with the data stored in it.
If the token is valid, the API call flow will continue as always.
**Sample Headers**
```
POST /resource HTTP/1.1
Host: server.example.com
Authorization: Bearer mF_s9.B5f-4.1JqM
```
### Errors
If the token is invalid an error will be returned. Here are some samples of errors:
**Invalid Credentials**
```javascript
[
{
"code": "jwt_auth_failed",
"message": "Invalid Credentials.",
"data": {
"status": 403
}
}
]
```
**Invalid Signature**
```javascript
[
{
"code": "jwt_auth_invalid_token",
"message": "Signature verification failed",
"data": {
"status": 403
}
}
]
```
**Expired Token**
```javascript
[
{
"code": "jwt_auth_invalid_token",
"message": "Expired token",
"data": {
"status": 403
}
}
]
```
## Usage
Usage:
```php
$token = "token retrieved above"
$args = [
'method' => 'GET',
'headers' => [
'Authorization' => 'Bearer ' . $token,
],
];
return wp_remote_get( 'https://example.disciple.tools/wp-json/dt-posts/v2/contacts', $args );
```
### /wp-json/jwt-auth/v1/token/validate
This is a simple helper endpoint to validate a token; you only will need to make a POST request sending the Authorization header.
Valid Token Response:
```javascript
{
"code": "jwt_auth_valid_token",
"data": {
"status": 200
}
}
```
# Site-to-Site-Link
To authenticate with D.T from another server.
### Creating the token
Go to the wp-admin. Open **Site Links** in the menu on the left. Click the **Add New** button.
In **Site 1** add the D.T domain. Example: example.disciple.tools
In **Site 2** add the remote server's. Example: example.com
note: both domains need to be HTTPS. You can disable this for local testing by enabling `WP_DEBUG`
**Connection type**: You will create a connection type and associate permissions to it. See below.
Since you are not connecting to another D.T instance, under **DT Site** choose 'No, connection for a non-Disciple Tools system.'.
See more documentation on creating a site link [here](https://disciple.tools/user-docs/getting-started-info/admin/site-links/)
### Remote authentication
We'll use the token and the 2 domains we just defined to authenticate with D.T form another server.
Here are example for creating a contact. Note we are not using the endpoints that include "dt\_public" in the url. Those most likely will not work.
PHP Example
```php
function create_contact( $fields ) {
$token = "token from the Site to Site link";
$site_key = md5($token . "example.disciple.tools" . "example.com");
$transfer_token = md5($site_key . date('Y-m-dH'));
$url = 'https://example.disciple.tools/wp-json/dt-posts/v2/contacts';
$req = curl_init();
curl_setopt_array($req, array(
CURLOPT_URL => $url,
CURLOPT_RETURNTRANSFER => true,
CURLOPT_CUSTOMREQUEST => 'POST',
CURLOPT_POSTFIELDS => json_encode($fields),
CURLOPT_HTTPHEADER => array(
"Content-Type: application/json",
"cache-control: no-cache",
"Authorization: Bearer " . $transfer_token
),
));
$response = curl_exec($req);
return json_decode($response);
}
```
Wordpress Example
```php
function create_contact( $fields ){
$token = "token from the Site to Site link"
$site_key = md5( $token . "example.disciple.tools" . "example.com" );
$transfer_token = md5( $site_key . current_time( 'Y-m-dH', 1 ) );
$args = [
'method' => 'POST',
'body' => $fields,
'headers' => [
'Authorization' => 'Bearer ' . $transfer_token,
],
];
return wp_remote_post( 'https://example.disciple.tools/wp-json/dt-posts/v2/contacts', $args );
}
```
Node example
```javascript
import moment from 'moment'
import request from "request-promise"
let CryptoJS = require('crypto-js')
create_contact = (fields)=>{
let token = "token from the Site to Site link"
let key = CryptoJS.MD5(token + "example.disciple.tools" + "example.com")
let date = moment().utc().format("Y-MM-DDHH")
let transfer_token = CryptoJS.MD5(key + date).toString()
let options = {
method: "POST",
uri: 'https://example.disciple.tools/wp-json/dt/dt-posts/v2/contacts',
body: fields,
headers: {
Authorization: 'Bearer ' + transfer_token
},
json: true
}
return request(options)
}
```
## Connection Types
Here is how you add a connection type and the right permissions from you D.T plugin.
For a list of permissions see [Permissions](/theme-core/capabilities). In the `site_link_capabilities` function you can add your own permission that you use later on in your plugin.
```php
add_filter( 'site_link_type', 'site_link_type', 10, 1 );
add_filter( 'site_link_type_capabilities', 'site_link_capabilities', 10, 1 );
function site_link_type( $types ){
if ( !isset( $types["connection_to_system_x"] ) ){
$types["connection_to_system_x"] = "Connection to System X";
}
return $types;
}
function site_link_capabilities( $args ){
if ( $args['connection_type'] === "connection_to_system_x" ){
$args['capabilities'][] = 'view_x_metrics';
}
return $args;
}
```
# Easy-Example
## Create a "Token" Site Link.
Notes:
* Site 1: Your D.T instance
* Site 2: Where you expect the webform to be used. It can be any url is this is not verified).
* Connection Type: At leate "Create Contact" to give the permision needed.
* Use Token As API KEY: This is required to keep the Authentication simple.
## Create a Contact
Create a Post Request to your instance
`POST`: `https://example.disciple.tools/wp-json/dt-posts/v2/contacts`
Use the site key in the Authorization header `Authorization: Bearer 14c5f0f1ebbc3c4b1042e884c1cf4e04410e274198928197c9ae726cbbe15b19`
Usage:
```php
$token = "token from the Site to Site link"
$args = [
'method' => 'POST',
'body' => $fields,
'headers' => [
'Authorization' => 'Bearer ' . $token,
],
];
return wp_remote_post( 'https://example.disciple.tools/wp-json/dt-posts/v2/contacts', $args );
```
$fields need to be in the format specified in [Fields Format](https://github.com/DiscipleTools/Documentation/blob/master/theme-core/authentication/theme-core/api-posts/post-types-fields-format.md)
# Permissions
This is a list of the capabilities used by D.T roles within the theme core. Each role is assigned certain capabilities which determines what the user is able to do.
## WP capabilities
**edit\_posts**\
give the user access and update ability for site links
**edit\_page**\
give the user access and update ability for site links
**read**\
let the user access the wp-admin interface
## D.T Admin capabilities
**manage\_dt**\
let the user update all D.T settings
## User management
**promote\_users**\
Ability to add/update/remove a user roles. Note only and administrator can give or take away the administrator role.
**edit\_users**\
Edit user data in the wp-admin interface
**create\_users**\
Create new users or invite users to the instance
**delete\_users**\
Ability to delete users
**list\_users**\
WP Admin list users
**dt\_list\_users**\
D.T Front End list users
## Metrics
**view\_project\_metrics**\
view more metrics for the whole project
## Locations
**read\_location**\
list locations
## People Groups
**access\_peoplegroups**\
Basic permission list and update all people groups.
**list\_peoplegroups**\
List all people groups in typeaheads.
## Post Types
Replace `post_type` with `contacts`, `groups` or your custom post type.
**access\_\[post\_type]**\
Give the user access to view their or all records of the post\_type
**create\_\[post\_type]**\
Gives the user the ability to create a record of the post\_type
**list\_all\_\[post\_type]**\
List all post\_type record names in typeaheads
**assign\_any\_\[post\_type]**\
Ability to assign any post\_type record to a user.
**access\_specific\_sources**\
Ability to list and update all contacts of source x
**dt\_all\_access\_contacts** >= v1.0.0\
List and update all contact of type 'access'
**view\_any\_\[post\_type]**\
gives full permission to view and update all records of the post type. Recommended only for API/script use.
# Roles and Permissions
Documentation for theme version 1.0.0 or greater
## Permissions
Permissions guide what a user can and cannot see and what records the user has access to. What Roles a user has determines what a user is permitted to do.
### Records Access
By default when a user creates contact, group or any record, that record is shared with the user.\
If a record is shared with a user, that user has permission to view and update that record and can share the record with other users.\
The list page looks up all the records that user has access to and displays them. By default this means the list page will ask for all the records shared with the user.
### Expanding access
Some roles like the Administrator and the Dispatcher can see more than the records they created. This is because their roles has additional capabilities which expands their access to records.\
An example is the Dispatcher role has has permission to see and update all access contacts. The dispatcher role has the `dt_all_access_contacts` capability. The access module looks for users which that capability and gives them access to all contacts of type 'access'.
## Roles
Since version 1.0.0 Roles are modular. The theme sets declares a set of roles and their capabilities. Plugin can add roles and modify capabilities on all roles.
Let's build out the Dispatcher role.
First we hook into the `dt_set_roles_and_permissions` filter to declare role and set the capabilities.
```php
add_filter( 'dt_set_roles_and_permissions', [ $this, 'dt_set_roles_and_permissions' ], 10, 1 );
public function dt_set_roles_and_permissions( $expected_roles ){
$expected_roles['dispatcher'] = [
"label" => __( "Dispatcher", "disciple_tools" ), // the displayed name of the role
"descriptions" => "Monitor new D.T contacts and assign the to waiting Multipliers", //description shown to help the admin choose what role to assign a user.
"permissions" => [
'dt_all_access_contacts' => true, //gives permission to all contacts with the 'access' type.
'view_project_metrics' => true, //view all poject chart is the metrics tab
'list_users' => true, //list users in the wp-admin
'dt_list_users' => true, //list user in the theme (needed for assigning to multipliers)
]
];
return $expected_roles;
}
```
If you want to add capabilities to an existing role from your plugin make sure the filter priority is higher that the number user when declaring the role in the first place. Let's add a capability to the dispatcher role. They priority used by the filter when declaring it was 10. So we'll used 20.
```php
add_filter( 'dt_set_roles_and_permissions', [ $this, 'dt_set_roles_and_permissions' ], 20, 1 );
public function dt_set_roles_and_permissions( $expected_roles ){
//check if the role is declared. You don't need to reset the label and description.
if ( isset( $expected_roles["dispatcher"]["permissions"] ) ){
$expected_roles["dispatcher"]["permissions"]["my_custom_capability"] = true;
}
return $expected_roles;
}
```
## Linking capabilities to permissions
### In listing records
**dt\_filter\_access\_permissions** filter\
This filter is called when querying a list of records. Here you can expand or restrict the records the user has access to based on their role and capabilities.
Example, giving the dispatcher permission to all contacts of type 'access':
```php
public static function dt_filter_access_permissions( $permissions, $post_type ){
if ( $post_type === "contacts" ){
//give user permission to all contacts af type 'access'
if ( current_user_can( "dt_all_access_contacts" ) ){
$permissions[] = [ "type" => [ "access" ] ];
}
}
return $permissions;
}
```
### In viewing records
**dt\_can\_view\_permission** filter
Example, giving the Dispatcher permission to view any contact of type 'access':
```php
add_filter( "dt_can_view_permission", [ $this, 'can_view_permission_filter' ], 10, 3 );
public function can_view_permission_filter( $has_permission, $post_id, $post_type ){
if ( $post_type === "contacts" ){
if ( current_user_can( 'dt_all_access_contacts' ) ){
$contact_type = get_post_meta( $post_id, "type", true );
if ( $contact_type === "access" ){
return true;
}
}
}
return $has_permission;
}
```
### In updating records
**dt\_can\_update\_permission** filter
Example, giving the Dispatcher permission to update any contact of type 'access':
```bash
add_filter( "dt_can_update_permission", [ $this, 'can_update_permission_filter' ], 10, 3 );
public function can_update_permission_filter( $has_permission, $post_id, $post_type ){
if ( $post_type === "contacts" ){
if ( current_user_can( 'dt_all_access_contacts' ) ){
$contact_type = get_post_meta( $post_id, "type", true );
if ( $contact_type === "access" ){
return true;
}
}
}
return $has_permission;
}
```
### In deleting records
**dt\_can\_delete\_permission** filter
Would be similar to the code above.
# Database Tables
### Here is a sumarry of the tabels D.T uses
#### wp\_posts
* D.T records like contacts and groups
* The post row contains limited data like: post ID, name, author, creation date
#### wp\_postmeta
* Stores field data abot the recod
* Example: status, milestones
#### wp\_dt\_post\_user\_meta
* D.T custom table
* Stores record data that is only visible to one user (private fields)
* Example: my favorite contacts
#### wp\_comments
* Stores record comments
#### wp\_commentmeta
* Stores comment meta like
* Example: reactions
#### wp\_dt\_share
* D.T custom table
* Stores who a record is shared with (which users have access to a record)
#### wp\_p2p
* Stores connections to other records
* Example: contact records that form a group's members
#### wp\_p2pmeta
* Stores p2p meta. Currently unused
#### [wp\_dt\_activity\_log](/theme-core/tables/wp-dt-activity-log)
* D.T custom table, stores activity on records
* Example: Milestone "praying" selected on July 27 2020 at 7:23pm
#### wp\_dt\_location\_grid
* D.T custom table.
* Stores the base location grid project. Used in the location field
* Example: Paris, France, grid\_id: 100089652, level: admin2
#### wp\_dt\_location\_grid\_meta
* D.T custom table
* Stores extra geocoding data when using a geocoder from mapbox or google
#### wp\_dt\_notifications
* D.T custom table
* Stores web notifications for user to see when they log in
* Example: You were assigned on contact John Doe
#### wp\_dt\_reports
* D.T custom table
* Stores lightweight events
* Possible example: meeting times
#### wp\_dt\_reportmeta
* D.T custom table
* Store extra information on a report
#### wp\_dt\_movement\_log
* D.T custom table
* Stores geocoded event that can more easily be queried
#### wp\_options
* WP table
* Stores settings and configurations used by D.T
#### wp\_users
* WP table
* Each user that user the D.T system has a user record
#### wp\_usermeta
* WP table
* Stores user information
* Example: prefered language
### Tables that D.T does not use:
* wp\_links
* wp\_term\_relationships
* wp\_term\_taxonomy
* wp\_termmeta
* wp\_terms
# Activity Table
### \[ wp\_dt\_activity\_log ]
D.T custom table; which captures a wide array of system events, such as field updates.
### Field Update Events
The following field types are currently captured:
#### text:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => nickname
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8604
[meta_key] => nickname
[meta_value] => MAKE Stuff Pls
[meta_parent] => unknown
[object_note] => Nickname changed from "MAKE Stuff" to "MAKE Stuff Pls"
[old_value] => MAKE Stuff
[field_type] => text
)
```
#### date:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => baptism_date
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8667
[meta_key] => baptism_date
[meta_value] => 1673395200
[meta_parent] => unknown
[object_note] => Added Baptism Date: 1673395200
[old_value] =>
[field_type] => date
)
```
#### key\_select:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => gender
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8668
[meta_key] => gender
[meta_value] => male
[meta_parent] => unknown
[object_note] => Added Gender: Male
[old_value] =>
[field_type] => key_select
)
```
#### multi\_select:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => milestones
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8669
[meta_key] => milestones
[meta_value] => milestone_has_bible
[meta_parent] => unknown
[object_note] => Added Faith Milestones: Has Bible
[old_value] =>
[field_type] => multi_select
)
```
#### connection:
```php
(
[action] => connected to
[object_type] => contacts
[object_subtype] => $from_field_key
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 572
[meta_key] => contacts_to_groups
[meta_value] => 317
[meta_parent] =>
[object_note] => connection from
[field_type] => connection
)
(
[action] => connected to
[object_type] => groups
[object_subtype] => $to_field_key
[object_id] => 317
[object_name] => Metric Group
[meta_id] => 572
[meta_key] => contacts_to_groups
[meta_value] => 536
[meta_parent] =>
[object_note] => connection to
[field_type] => connection
)
```
#### number:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => number_test
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8671
[meta_key] => number_test
[meta_value] => 5
[meta_parent] => unknown
[object_note] => Added Number field: 5
[old_value] =>
[field_type] => number
)
```
#### communication\_channel:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => contact_other_c8a
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8682
[meta_key] => contact_other_c8a
[meta_value] => @other3
[meta_parent] => unknown
[object_note] => Added contact_other_c8a: @other3
[old_value] =>
[field_type] => communication_channel
)
(
[action] => field_update
[object_type] => contacts
[object_subtype] => contact_other_c8a_details
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8683
[meta_key] => contact_other_c8a_details
[meta_value] => a:1:{s:8:"verified";b:0;}
[meta_parent] => unknown
[object_note] => contact_other_c8a "@other3" not verified
[old_value] =>
[field_type] => details
)
```
#### tags:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => tags_test
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8674
[meta_key] => tags_test
[meta_value] => random
[meta_parent] => unknown
[object_note] => Added Random Tags: random
[old_value] =>
[field_type] => tags
)
```
#### user\_select:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => user_select_test
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8675
[meta_key] => user_select_test
[meta_value] => user-12
[meta_parent] => unknown
[object_note] => Added User Select: user-12
[old_value] =>
[field_type] => user_select
)
```
#### location:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => location_grid
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8676
[meta_key] => location_grid
[meta_value] => 100134548
[meta_parent] => unknown
[object_note] => Added Locations: 100134548
[old_value] =>
[field_type] => location
)
```
#### location\_meta:
```php
(
[action] => field_update
[object_type] => contacts
[object_subtype] => location_grid_meta
[object_id] => 536
[object_name] => MAKE Contact
[meta_id] => 8677
[meta_key] => location_grid_meta
[meta_value] => 123
[meta_parent] => unknown
[object_note] => Hungary
[old_value] =>
[field_type] => location_meta
)
```
# Disciple.Tools Translation
## Overview
Disciple.Tools is built on WordPress and uses the WordPress translation strategy. Extensive resources can be found on WordPress.org giving explanations and help for translators. [WordPress Translation Resources](https://make.wordpress.org/polyglots/handbook/tools/glotpress-translate-wordpress-org/)
We invite you to [contribute a new translation](https://poeditor.com/join/project/KcPvw3oaKD) to Disciple.Tools, and it does not require writing code! You can submit completed translations through Github or through email, and our commit team will review it and add it to the project.
## Current Available Translations
Disciple.Tools is available in 30+ languages. See [Translation](https://disciple.tools/translation/) for more details.
As Disciple.Tools develops, additional translation commits will be needed.
## How to contribute
We are using an online tool called [POEditor](https://poeditor.com/). No downloading, changing, or uploading of files necessary. No coding skills needed either.
To get started visit the main [Disciple.Tools WordPress theme translation project](https://poeditor.com/join/project/KcPvw3oaKD) and the much smaller [D.T app translation project](https://poeditor.com/join/project/dQzfAs5uNc). Or contribute to the translation of some D.T plugins [here](https://poeditor.com/join/project?hash=ts4yDqkDSW)
Either select an existing language from the displayed list or click **“Click here to suggest a new language”** link to add the language you want Disciple.Tools to be translated in to. Enter your email and name and then click “Join this project”
We will receive your request and approve your account as soon as possible. Once approved, you will be free to start translating.
Your translations will become available to everyone when we push a release for the theme
## POEditor: How to do a translation
Log in to and find the translation you have access to. You will arrive at a page like the following:
Click on the **flag** the represents the language you want to translate. You will arrive at a screen that looks like the following:
In the “big empty box”, type in the translation of “the string” (a word or phrase) that is displayed on the left side.
**For example**: The first string is `Location Grid Meta`. Type your translation of that phrase into the “big empty box” to the right. Once you are happy with what you have typed, click out side of the box, and the translation will be saved automatically. If you need to change it, simply click on the string, and the box will become editable again.
On the far right side of each row, there are a few icons that can be used to sort the list.
The `A` icon means “automatic translation” when highlighted will be set to orange in colour and means that the string was automatically translated. When you make a change to the string, the `A` will be unset. When you review a string that was marked as translated automatically, please untick the orange `A` icon to indicate that the string is correct.
The `Comments` icon (represented by the speech bubbles icon) indicates if a comment has been written by any translators relating to this string. If you have a question or comment to make about the string, click the `Comments` icon and write your comment (or question) in the popup window. Your comment will be sent to the main editor for the language project who will reply ASAP, if needed.
The `F` icon means “Fuzzy” which you can toggle to indicate that you aren’t sure if this string has been translated correctly. You can later review or have others easily find the strings that need revision.
## What are those wonky characters?
In POEditor, you will see some strings that look like this:
`Sorry, you don't have permission to view the %1$s with id %2$s.`
What do I do with the `%1$s` and `%2$s` and what do they mean?
These are placeholders that will be replaced with a something else.
Here this sentence in English could be :
Sorry, you don’t have permission to view the contact with id 4344. Sorry, you don’t have permission to view the group with id 493. In this case, `%1$s` corresponds to “contact” or “group”. `%2$s` corresponds to the id of the record
This message can be displayed for a contact or a group. And we don’t know before hand the ID of the record. This lets you, the translator, make a sentence that is gramatically correct while still using placeholders.
To translate the sentence, just copy and paster the characters ( `%s`, `%1$s`, `%2$s` ) to into your translation.
In french this sentence would give:
`Désolé, vous n'avez pas l'autorisation d'afficher le %1$s avec l'id %2$s.`
# Revisions
# v1.0.0-dev-changes
## Code Changes Overview
* Contact and group v1 endpoints removed and API v1 removed (Disciple\_Tools\_Contacts and Disciple\_Tools\_Groups).
* Contact and Group Record and list files removed and replace with the custom post type structure.
* All tiles are modular including details tile.
* Page for creating posts is more flexible.
* Channels merged into fields list.
* List query upgraded.
* List page upgraded.
* Dynamic list columns.
* Dynamic list columns order.
* Roles and capabilities are now built by the post-types.
* Support for deleting a post.
* Contacts are divided into `types`.
* Modules to add to a post-type.
* Some field are only available if the module is active. Ex: the seeker\_path field is only available when the access module is enabled.
## Structure changes
Files removed:
* dt-contacts/contacts.php
* dt-contacts/contact-endpoints.php
* dt-contacts/contacts-template.php
* archive-contacts.php
* template-contacts-new\.php
* single-contacts.php
* dt-assets/parts/contact-details.php
* dt-assets/parts/content-contacts.php
* dt-groups/groups.php
* dt-groups/group-endpoints.php
* dt-groups/groups-template.php
* archive-groups.php
* template-groups-new\.php
* single-groups.php
* dt-assets/parts/group-details.php
* dt-assets/parts/content-groups.php
## API changes
### v1 Function removed
**Search for these**
* Disciple\_Tools\_Contact\_Post\_Type::
* Disciple\_Tools\_Contacts::
* Disciple\_Tools\_Groups\_Post\_Type::
* Disciple\_Tools\_Groups::
And replace as follows:
| Find | Replace | Note |
| ----------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------- |
| `Disciple_Tools_Contacts::get_contact(` | `DT_Posts::get_post( "contacts",` | The order of parameters has also changed. $check\_permissions is before $silent |
| `Disciple_Tools_Contacts::create_contact(` | `DT_Posts::create_post( "contacts",` | The order of parameters has also changed. $check\_permissions is before $silent |
| `Disciple_Tools_Contacts::update_contact(` | `DT_Posts::update_post( "contacts",` | The order of parameters has also changed. $check\_permissions is before $silent |
| `Disciple_Tools_Contacts::add_comment(` | `DT_Posts::add_post_comment( "contacts",` | |
| `Disciple_Tools_Contacts::search_viewable_contacts(` | `DT_Posts::search_viewable_post( "contacts",` | |
| `Disciple_Tools_Contacts::get_contact_fields();` | `DT_Posts::get_post_field_settings( "contacts" );` | |
| `Disciple_Tools_Contact_Post_Type::instance()->get_custom_fields_settings();` | `DT_Posts::get_post_field_settings( "contacts" );` | |
| `Disciple_Tools_Groups::get_group(` | `DT_Posts::get_post( "groups",` | The order of parameters has also changed. $check\_permissions is before $silent |
| `Disciple_Tools_Groups::create_group(` | `DT_Posts::create_post( "groups",` | The order of parameters has also changed. $check\_permissions is before $silent |
| `Disciple_Tools_Groups::update_group(` | `DT_Posts::update_post( "groups",` | The order of parameters has also changed. $check\_permissions is before $silent |
| `Disciple_Tools_Groups_Post_Type::instance()->get_custom_fields_settings();` | `DT_Posts::get_post_field_settings( "groups" );` | |
### Hooks Removed:
* `dt_contact_update`
* `dt_contact_created`
* `dt_group_created`
* `dt_group_updated`
* `dt_pre_contacts_connections_section`
* `dt_post_contacts_progress_section`
* `dt_pre_contacts_progress_section`
* `dt_pre_contacts_other_section`
* `dt_post_contacts_other_section`
* `dt_contact_detail_notification` -> `dt_record_top_above_details`
[API Hooks documentation](/theme-core/hooks/api-hooks) [Record Page Hooks documentation](/theme-core/hooks/record-page-hooks)
### Consistently using post\_date in the API
The post date was represented in 4 different ways:
* create\_date (in creating a post)
* created\_date (in getting a post)
* created\_on (in list query)
* post\_date (in getting a post in the list)
We've changed them all to be `post_date`
* create\_date => post\_date
* created\_date => post\_date
* created\_on -> post\_date
### Consistently using name for record title/name
* List response included: **post\_title**. Now includes **name** and **post\_title**
* Create post accepted: **title** and now accepts **title** and **name**
* Get post returned: **title** and now returns **name** and **title**
* Search posts was N/A -> You can now search for **name**
### ID returned from `create_contact`
`create_contact` used to return the contact\_id.\
`create_post` returns the full post.\
If the user has permissions to create posts but not read posts the function will return only an array with the ID of the new post:
```php
[ "ID" => 123 ]
```
### Field settings changes
* Contacts
* `name`: new field. Type: `text`
* See [Consistently using name for record title/name](#consistently-using-name-for-record-titlename)
* `nickname`: new field. Type: `text`
* `faith_status`: new field (DMM module). Type: `multi_select`
* `post_date`: repurposed. Type: `date`
* See [Consistently using post\_date in the API](#consistently-using-post_date-in-the-api)
* `type`: repurposed. Type: `multi_select`
* Contact `type` field value `media` is now `access` and a migration converts them all.
* `languages`: new field. Type: `multi_select`
* `contact_phone`: Channel migration. Type: `communication_channel`
* See [Channels](#channels)
* `contact_email`: Channel migration. Type: `communication_channel`
* See [Channels](#channels)
* `contact_address`: Channel migration. Type: `communication_channel`
* See [Channels](#channels)
* `contact_facebook`: Channel migration. Type: `communication_channel`
* See [Channels](#channels)
* `contact_twitter`: Channel migration. Type: `communication_channel`
* See [Channels](#channels)
* `baptism_generation`: Changed from `text` to `number`. Type: `number`
* `last_modified`: Changed from `number` to `date`. Type: `date`
* Groups
* `name`: new field. Type: `text`
* `post_date`: repurposed. Type: `date`
* See [Consistently using post\_date in the API](#consistently-using-post_date-in-the-api)
* `member_count`: Changed from `text` to `number`. Type: `number`
* `address`: Channel migration. Type: `communication_channel`
* See [Channels](#channels)
### List query
* `assigned_to => 'all'` is now not a query
* `assigned_to => 'shared'` is now "shared\_with" => \[ "me"]
* The `combine` parameter no longer works.
* Maximum query limit is 1000.
The list query is now more flexible with:
* More fields types supported: communication\_channel, text, number
* Negative queries to exclude data.
* Exact match for text and communication\_channel fields.
* [Better AND/OR capabilities](https://github.com/DiscipleTools/Documentation/tree/d05945fa8e00435ee251dd92ababf88b593c14cc/theme-core/api/posts/list-query.md#combining-with-andor-logic).
* [Get recently viewed posts](https://github.com/DiscipleTools/Documentation/tree/d05945fa8e00435ee251dd92ababf88b593c14cc/theme-core/api/posts/list-query.md#recently-viewed-posts)
[See List Query Documentation](https://github.com/DiscipleTools/Documentation/tree/d05945fa8e00435ee251dd92ababf88b593c14cc/theme-core/api/posts/list-query.md).
### Transfer Contact API
The Endpoint used by the front end to send a contact to another instance has changed:\
POST `dt/v1/contact/transfer` -> POST `dt-posts/v2/contacts/transfer`
The endpoint to receive a transfer has also changed:\
POST `dt-public/v1/contact/transfer` -> POST `dt-posts/v2/contact/receive-transfer`
### Channels
Upgrade to the function to get the channels list:\
`Disciple_Tools_Contact_Post_Type::instance()->get_channels_list();` -> `DT_Posts::get_post_settings( "contacts" )["channels"];`
Channels continue to be available in the "channels" key in the post type settings array.
Channel are now also part of the field list and follow the new format in the field list.\
So Instead of:
```php
"phone" => [
'label' => "Phone
]
```
the field will look like
```php
"contact_phone => [
'name' => "Phone"
]
```
* `dt_custom_channels` filter was removed
* `dt_custom_channels` option was removed
### Javascript changes
`contactsDetailsWpApiSettings` and `wpApiGroupsSettings` are no longer available. Look for `window.detailsSettings` or `window.wpApiShare` instead
Examples: `window.contactsDetailsWpApiSettings.contacts_custom_fields_settings` -> `window.detailsSettings.post_settings.fields` `window.contactsDetailsWpApiSettings.contact` -> `window.detailsSettings.post_fields`
## DT\_Posts Functions
### Removed:
* removed function `find_contacts_by_title()`
* removed function `get_viewable_post()`
### New Functions:
//get the list of tiles for a post\_type\
`DT_Posts::get_post_tiles( $post_type );`
//get the list of fields for a post\_type\
`DT_Posts::get_post_field_settings( $post_type );`
//Get all the post\_type settings\
`DT_Posts::get_post_settings( $post_type )`
//get modules\
`dt_get_option( 'dt_post_type_modules' );`\
[See modules documentation](/theme-core/customization/modules)
//Duplicate checker
#### Notes
Please submit a PR if you find something missing from this page.
# v1.0
This page has moved to:
# Hosting
# 404 Errors on new install
## Permalinks
If you installed Disciple.Tools and are getting 404 errors on `/contacts` or other pages try this: Log in to wp-admin and go to Settings > Permalinks. You don’t need to change anything, just click **save** at the bottom. Click **save** again because WordPress.
## Windows Hosting
**Special Note for hosting on Windows servers**: If you receive a 404 error message when trying to preview or run DT after installing WordPress and the DT theme, check the root WordPress folder (e.g., `C:\inetpub\wwwroot\wordpress`) , and verify the `web.config` file exists. If not, create a text file named `web.config` and include the following code block in the file:
```markup
```
For more information, please refer to .
# CRON
Disciple.Tools relies on cron jobs for certain activities. Some of these are sending scheduled emails and creating update needed notifications.
WordPress’s default scheduling strategy depends on traffic. So then if no one comes to the site, the task may not run for a while. It will wait until the next visitor opens the site. A normal Disciple.Tools instance will not generate much traffic. This also slows down the server for this visitor as all these background tasks are now running.
For WPEngine.com: see this section in their documentatian They will do everything for you.
For other hosting services: we recommend googling the name of you hosting service along with "Replace WordPress Cron"
## Doing it manually:
The solution is to disable the WP cron strategy. To do this, open the wp-config.php file and add the following line before the “/ *That’s all, stop editing! Happy blogging.* /” line:
`define('DISABLE_WP_CRON', true);`
Then,
### Option 1 - Server Cron
you want to setup a cron on your server or with your hosting service to run every 5 mins:
`*/5 * * * * wget -q -O - http://yourdomain.com/wp-cron.php?doing_wp_cron > /dev/null 2>&1`
**Note:** change `yourdomain.com` to you disciple.tools domain
### Option 2 - Outsite Cron service
An alternative to setting up a cron job is to use a service like [Uptime Robot](https://uptimerobot.com/) to ping `http://yourdomain.com/wp-cron.php?doing_wp_cron` every 5 minutes.
## On Multisites
### Option 1
Create a cron job for each subsite
*
*
*
### Option 2
Create a script to call each subsite. Create a file `custom-cron.sh` in the same folder as your wp-config.php
custom-cron.sh contents:
```
/usr/local/bin/php /usr/local/bin/wp site list --field=domain --archived=0 --deleted=0 | xargs -i -n1 /usr/local/bin/php /usr/local/bin/wp cron event run --due-now --url="https://{}";
```
create the cron job, replace `/path/to/wp/install` with the path to you wordpress installating.
`*/15 * * * * cd /path/to/wp/install && /path/to/wp/install/custom-cron.sh`
On a large multisite you might want to make sure cron jobs don't run at the same time. For this we create a lock file while custom-cron.sh is running.
`*/15 * * * * cd /path/to/wp/install && /usr/bin/flock -n /tmp/multisitecron.lock /path/to/wp/install/custom-cron.sh`
# Hosting on WPEngine
## Create an account
Create an account on and pick a plan - an annual $300+ expense. See
## Create a site.
You have the choice between a single instance and a multisite instance.
A single instance is fine if you have one team in one location.
You'll want a multisite if you have multiple teams, multiple locations, or need more control over who has access to what. We suggest using the subdirectly multisite install instead of the subdirectly install. The main benefit is that you can use one ssl cert for the whole site.
We recommend starting with a multisite. This makes it easier to add instances later as your ministry grows.
See [single or multisite](https://developers.disciple.tools/hosting/single-or-multisite) for more information.
Any plan is good for the single site. For multisite you need to start with a plan that supports the "WordPress Multisite available for purchase" option. Currently starting at the "MANAGED HOSTING PROFESSIONAL" plan.
To use multisite you'll need to first purchase the "Wordpress Multisite" Add-on from Billing > Purchase Add-ons (). It will cost \~$200 (one time expense).
You now have a WordPress instance at \[instance\_name].wpengine.com
## Setup Custom Domain
Purchase custom domain (your-domain.com)
Set up DNS to access your instance from your-domain.com or subsite.your-domain.com DNS instructions?
## Install Theme
Download the theme - or link to the downloads page.
Log in to your new wordpress instance.
Install the theme (link to how to install themes) Single/Multisite
## Setup TLS (SSL)
After your custom domain is set up
### Single Site
Click SSL > Add Certificates > Get FREE certificate using the Let's Encrypt option
### Multisite
If you selected "subdirectory" as you multisite install then it is the same single site strategy.
For "subdomain insteals":
If you add each subdomain to the domains panel then it is the single site process.
If you have many sub-domains and will be adding and removing them often:
* Buy the wildcard SSL cert from WPEngine - an annual $200 expense
### Restrict all traffic to use https.
Under SSL, select the certificate and choose “Secure All URLs”.
## Backups
Have a strategy for offsite backups. If WPEngine accidentally deletes your account or it gets frozen (GDPR?) you want to have access to your data. See
## Additional Configuration
### CRON
Enable system schedule processes:
-enable cron
### Caching and Bots
-
-We initially had to contact support to disable caching on GET api requests. This has not been an issue recently.
### Multisites
Install the multisite plugins:
Multisite Tools and helpful functions:
Show update notifications if your main site is not an instance of Disciple.Tools:
### Cloudflare
Consider using cloudflare in front of your hosting for additional security. Create a free account and point the name servers for your domain to cloudflare.
## Notes
* WPEngine does have a publicly accessible error log (though you need to know the link to access it). Error logs have the potential to dump personal contact info.
* WPEngine has a small storage limit per account, so don't store a lot of backups locally.
* With a multisite the option “Secure all URLs” with HTTPS does not always work.
* When you want to add another WPEngine instance, you can stay on the cheapest plan and under Billing > Add-ons add a site for $200
* cairocoder01 has instructions on how to expedite setting up multiple WPEngine instances: [DT Setup Automation](https://github.com/cairocoder01/dt-setup-automation)
# Backups
You know that you need to keep your data backed up. Here are some things to keep in mind. Not all backups are equal. You need to have a backup that you can access if your website goes down or if your hosting provider accidentally deletes your account (this happens). This means that any backup that stays on the server your site is on isn’t a reliable backup. You must have a secure remote backup of you Disciple.Tools instance. This can be with Amazon S3, Google Drive or any other secure storage location.
## UpdraftPlus
We recommend and use [UpdraftPlus](https://updraftplus.com/) for our backups. Multisite support is only available on the paid version.
## BackWPup
We’ve also tested BackWPup: . This plugin is free but more difficult to set up.
# Single Site or MultiSite
## A Wordpress Tool
In setting up Wordpress on a new server we have two options. The default way as single site, or as a multisite.
### Single site
This is the default when you install Wordpress on your server and set it up on your domain or subdomain. Your site will be available at example.com or site.example.com.
### Multisite
During install (preferred) or after Wordpress is installed you can configure Wordpress as a Multisite. This lets you set up multiple sites on ones server.
* example.com
* site1.example.com
* site2.example.com
* site3.example.com
## What does this mean for Disciple.Tools?
A single site will give you an instance where you and your users can collaborate on contacts, groups, and more. All your contacts will be in one place and are managed by the Admin and Dispatchers.
This is a great starting point if you are a small team working in together over one region. But suppose you have a team in New York with a Facebook Ministry and a team in Chicago with a cool Website and another team in a different location doing campus ministry.\
It soon become overwhelming to have all the contacts one spot. This is why you might want to separate the teams out into different instances using Wordpress as a multisite.
The Serve could be set up like this:
* ministry.com - a D.T instance, or a front facing webpage
* new-york.ministry.com - instance for the New York team
* chicago.ministry.com - instance for the Chicago team
* etc
You may choose to have a different instance for each location you are in. You can also separate based on teams, language, media page, etc.
Note: On multisites, only Super Admins can modify a user's email address or password. This makes supporting users harder for the subsite administrator. Note: We'd love to support team functionality inside one instance. Follow us at
## Global Metrics - Network Dashboard
If you have gone with the multisite route, you still would like to see what is happening in one place. We've built the Network Dashboard to collect data form many instances and **show metrics in one place**.\
You can set it up to collect data from all the multisite instances on your server and you can connect it to other instances on others servers as well.
Find out more about the Network Dashboard here
## Site Links - Collaborate Between Instances
D.T allows users to send contacts between instances. This can be the different instances on your multisite, or with other D.T servers.
A **Site Link** is needed to collaborate between instances. Here are instructions on how to set them up:
## Managing a Multisite
### Setup
If you are hosting your own instance check out the Wordpress documentation for enabling multisite [here](https://wordpress.org/support/article/create-a-network/).
If you are using a hosting service like WPEngine google "WPEngine multisite" or contact your hosting support. They will help you get it set up. Sometimes hosting services charge extra for multisites.
### Maintenance - D.T Multisite Plugin
Once your multisite is set up, you can install the Disciple.Tools multisite plugin: .
It offers growing support for updating and managing all your instances at one time.
# Disciple.Tools Development Setup
## Contents
* **Hosting on a Local Computer**
* [LocalWP Based Setup](/local-setup/localwp-setup)
* [Alternative Docker Based Setup](/local-setup/dt-docker)
* [Enable Debugging](/local-setup/dt-docker#enable-debugging)
* [Docker Multi-site Setup](/local-setup/dt-docker#docker-multi-site-setup)
* [**Mobile App Setup**](/local-setup/mobile-app-setup)
# LocalWP
[LocalWP](https://localwp.com/#) provides a simple way to configure a WordPress development environment.
1. Install LocalWP on your machine:
a. Download the appropriate installer for your platform from the list on:
* *If a dialog asking for your platform type appears*, you must have pressed the DOWNLOAD button in the upper right of the web page *instead* - You do not have to fill in all the information, but you must give your email address.
* The installer should download automatically, if not then follow the instructions
b. Installing LocalWP on **MacOS** and **Linux** is straight forward. For Windows, especially with a 3rd-party antivirus, it requires more effort.
> ***Note*****:** Some VPNs set firewalls on your network configuration, which will likely conflict with LocalWP.
>
> ### Installing on Windows
>
> * Select install for **all users** (requires Administrator privileges).
> * **Run Local but do not create a website yet**, LocalWP needs to be able to write to your `c:\Windows\System32\Drivers\etc\hosts` file and set up SSL. Your antivirus will not like this so you **must** first “whitelist” Local.
> * As an example: if you use Kapersky 2020, these are the steps: [*(source)*](https://localwp.com/community/t/how-to-run-local-5-0-7-windows-10-antivirus-software-kaspersky/15290) 1. In the main windows go to More Tools -> Manage applications -> Application Controls -> Manage applications 2. In the search box type “local” 3. Double click on Local.exe – **Be careful it is the right application!** 4. Under Exclusions check:
>
> 
>
> * \[X] Do not monitor application activity
> * \[X] Do not inherit restriction from the (application's) parent process
> * \[X] Do not monitor the activity of child applications
> * Press "Save"
2. LocalWP will ask if you want to create a new site, or press the large **✚** in the lower left corner.
a. Provide a site name and choose ADVANCED OPTIONS to change defaults 1. Change the site domain and browse for where you want your site’s code to be stored. (You may need to create the folder)\
**e.g.** Name: D.T Local site path: *D:\sandbox\DT (e.g. as a Windows path)* 2. Select “CONTINUE”
b. Choose “Preferred” environment 1. Select “CONTINUE”
> * Select the custom option with different values if you run into an issue.
c. Provide WordPress Username, Password and Email address
* **If** you wish the site to be **Multisite**, select this under ADVANCED OPTIONS
* Select “ADD SITE”
d. Wait for WordPress, etc. to be downloaded and the site to be created
> * ***Warning***: This can fail if there is no write access to your hosts file, or your antivirus does not give LocalWP sufficient permissions.
> * ***In Windows:*** if you are not running as an administrator you will need to give it permission to update the hosts file.
> * This and other changes will need admin approval. An alternative is to change the LocalWP shortcut’s Properties -> Advanced… so it always runs as Administrator, but this *can* cause security issues.
e. You can access your site via **both** http\:// and https\://
* LocalWP will create an SSL certificate if you select the **TRUST** button (which will bypass your browser’s security warning)
* e.g. If the site’s name is D.T, then both addresses will work `http://dt.local` and `https://dt.local`
3. Install Theme. See
1. Follow installation instructions:
2. Download latest release:
4. Some plugins are available for installation from the **Extensions** tab
If you need the latest plugin, download the zip files from GitHub, and install plugins using these instructions:\
* e.g.
# Mobile App Setup
This [YouTube playlist](https://www.youtube.com/playlist?list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE) shows how to set up a local development environment for the D.T. Mobile App and contains more information about the environment than this guide.
However, the [playlist](https://www.youtube.com/playlist?list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE) uses Docker for the local Wordpress server and executes the mobile app setup slightly differently. There are links in the steps below to pertinent sections in the video, although they are not necessarily in the same order.
Where the details differ please follow these instructions instead.
## Contents
* [1. Install Mobile App Plugin](#1-install-mobile-app-plugin)
* [2. Configure WordPress Address](#2-configure-wordpress-address)
* [Use Live Link (LocalWP only)](#use-live-link-localwp-only)
* [*OR* Change Site Domain to Your Server’s IP Address](#or-change-site-domain-to-your-servers-ip-address)
* [3. Setup Source Code](#3-setup-source-code)
* [Https Workaround](#https-workaround)
* [Install Expo](#install-expo)
* [Install Dependencies](#install-dependencies)
* [4. Run the Development Environment](#4-run-the-development-environment)
## 1. Install Mobile App Plugin
Download the *latest* mobile app plugin zip file, and install the plugin, by following these instructions:
*
## 2. Configure WordPress Address
Changes need to be made to the *Wordpress* configuration for the mobile app to connect to it.
If you are using **LocalWP** Setup, then there are two choices: Local Live Link address, *or* change the D.T site’s domain to an address reachable from your mobile device. The latter is the only choice if you are using **Docker**
### Use Live Link (LocalWP only)
1. **Enable** ngrok.io Live Link from the centre of the bottom line of the D.T’s Local Sites in the Local app.
2. “**Enable**” button’s text will change to “**Copy**”
3. Transfer address to mobile device – it will look like: `http://0f0f0f0f0f0f.ngrok.io`
### *OR* Change Site Domain to Your Server’s IP Address
> ***Warning*****: With Docker, if your local Wordpress site has NOT been setup to use http (i.e. NOT https) then you will need to reinitialize it.**
>
> * Adding “—volumes” to docker-compose down will remove your previous configuration
>
> ```bash
> > docker-compose down --volumes
> > docker-compose up -d
> ```
> * Go to and repeat the configuration steps from [1.3 Start Wordpress](https://developers.disciple.tools/local-setup/pages/-MU8GvCEOn00R7_9gTH1###start-wordpress)
1. Discover the IP address of your local server
There are multiple commands to do this, and your computer may have multiple network interfaces and it will depend if it uses a wired or wireless connection.
* The address would likely be of the form “192.168.1.2” (as an example)
* On Linux you can use: *i**f**config*
* On Windows you can use: *i**p**config*
2. **If** you are using **LocalWP**,
* In the D.T’s Local Sites in the **Local** app, change the Site Domain to your IP address
**If** you are using **Docker**,
* login to wp-admin and go to Settings > General and update the WordPress and Site Addresses to your servers IP address.
* As examples, if your address is `192.168.1.2` and no port number, then:
* WordPress Address (URL): `http://192.168.1.2`
* Site Address (URL): `http://192.168.1.2`
> NOTE: This [YouTube video](https://www.youtube.com/watch?v=1KJEOY5J3Sw\&list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE\&index=5\&t=6m12s) shows the basic procedure.
## 3. Setup Source Code
Clone the *development* or *master* branch of to the folder where you want the source code to be stored.
This [YouTube video](https://www.youtube.com/watch?v=gdeJHI19F7A\&list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE\&index=4\&t=2m35) goes into much more detail.
```bash
> git clone https://github.com/DiscipleTools/disciple-tools-mobile-app.git
> cd ./disciple-tools-mobile-app/
> git checkout development
```
### Https Workaround
Your local copy of DT does not have the correct https certificates so the mobile app will not be able to connect to it. To work around this, use the http connection instead.
This is shown in this [YouTube video](https://www.youtube.com/watch?v=gdeJHI19F7A\&list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE\&index=4\&t=9m24s).
> **NOTE:** The app code is able to connect to the official demo server if you have an account, but will no longer be able to after these changes.
>
> **For Windows:** These are Linux commands. You will need execute these commands from the **git bash shell**, or another **Linux** shell
From within the *disciple-tools-mobile-app* folder:
```bash
> cd store/sagas
> grep -rl https: . | xargs sed -i "s/https:/http:/g"
```
> **WARNING:** **Do not include these changes with any pull requests** to the main repository! They will be rejected.
### Install Expo
See
1. Expo requires NPM to be installed. Download and setup from
2. Use NPM to install expo:
```bash
> npm install expo-cli -–global
```
3. *Create an account* if you do not have one (You do not have to create a project)
4. Install the Expo client on your mobile device (iOS or Android app stores)
### Install Dependencies
From within the ***disciple-tools-mobile-app*** cloned folder install project dependencies based on the package.json file
This is shown in this [YouTube video](https://www.youtube.com/watch?v=gdeJHI19F7A\&list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE\&index=4\&t=5m53s)
Use the NPM install command:
```bash
> npm install
```
This may take a while
## 4. Run the Development Environment
Use the NPM start command:
```bash
> npm start
```
1. Wait for the GUI to display a QR code and then on your mobile device:
* Again, this may take a while
* **From iOS:** take picture of QR code
* **From Android:** launch Expo app and take a picture of the QR code.
2. Wait for the DT android app to start and ask for you to connect to the server.
* This may a while as well, but the main Expo GUI will provide a status, as will the terminal you started it on.
* Log into the mobile app using the local DT Wordpress server ip address you set the server to [previously](#2-configure-wordpress-address).
> **NOTE:** The end of Part 5 as well as part 6 of the [YouTube videos](https://www.youtube.com/watch?v=1KJEOY5J3Sw\&list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE\&index=5\&t=8m6s) give additional information about using the mobile development environment:
>
> [Part 7](https://www.youtube.com/watch?v=eM2zxplCaOE\&list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE\&index=7) shows you what is happening on the phone while this is taking place:
# Unit Tests
## Setup testing environment
In the theme root within your environment (localWP: "Open site shell" option) run:
```bash
./tests/install-wp-tests.sh [db-host]
```
* `` is the name of the db you want the run the tests in. We suggest creating a separate db form your dev db for testing.
* `` Database username
* `` Database password
* `[db-host]` Database url and port. For localWP get the port from the url when opening Adminer.
Note for localWP on linux the command looks like this for localWP:\
`./tests/install-wp-tests.sh local-test root root localhost:10063`
Notes:
* On localWP, make sure you are running from the "Open site shell" menu option, so the environment is loaded
* On localWP, remove `--protocal=tcp` on line #141 of ./tests/install-wp-tests.sh
* On localWP, you can get the database port from the browser url after opening adminer
* You may need to install svn: `sudo apt install subversion`
* If you get an error that looks like: `Could not find /{path}/wordpress-tests-lib /includes/functions.php, have you run tests/install-wp-tests.sh ?` delete the temp folder and run the install again.
## Running the tests
Install phpunit and phpunit-polyfills form the theme root.
```bash
composer require "phpunit/phpunit=7.5.*"
composer require "yoast/phpunit-polyfills"
```
Run `./vendor/bin/phpunit`
The tests need phpunit v7. v8 and above currently don't work.
## Writing tests
* tests are located in the theme ./tests folder
* unit test files need to start with 'unit-test'
* unit test function need to start with 'test\_'
* phpunit documentation
* assertions:
# Cypress Tests
Support for the [Cypress Testing Framework](https://www.cypress.io) has now been integrated into D.T.
With Cypress, you can easily create declarative tests, debug them visually and automatically run them in your continuous integration builds.
## Getting started
From the terminal, navigate to the `disciple-tools-theme` directory and execute `npm run cy:open`; which should display the Cypress Launchpad.
From there, select the `E2E Testing` option; which should then display the following browser selection view.
See [Cyress Open The App](https://docs.cypress.io/app/get-started/open-the-app) guide for more details.
On browser selection, you should then be taken to the End To End (E2E) view; as shown below.
## E2E Folder Structure
The view from the previous section, displays all E2E tests created under the `./cypress/e2e` directory; which is organised as follows:
* **./cypress/e2e/contacts/**
* Siloed unit tests, covering the testing of `contacts` post type related functionality; such as creating, updating and deleting records, searching, etc.
* Please follow the pattern shown, when introducing tests for new features.
* **./cypress/support/commands.js**
* A holding area for custom functions; typically duplicate code; which can be encapsulated into a global function.
* The following custom functions have been created:
* *dtLogin()*
* D.T frontend login.
## Running Environment
Currently, all tests are run locally; so, you'll need to update the base url and admin credentials within the `./cypress.config.js` file.
```js
import { defineConfig } from "cypress";
export default defineConfig({
e2e: {
setupNodeEvents(on, config) {
// implement node event listeners here
},
baseUrl: ''
},
dt: {
credentials: {
admin: {
username: '',
password: ''
}
}
}
});
```
Lastly, the following Cypress user guides also provide useful information, for gaining a better understanding of the framework.
* [Cypress - Your First Test](https://docs.cypress.io/app/end-to-end-testing/writing-your-first-end-to-end-test)
* [Cypress - Testing Your App](https://docs.cypress.io/app/end-to-end-testing/testing-your-app)
# D.T on Docker Setup
[Docker](https://www.docker.com/) is a container system that can be used to set up all of the infrastructure needed to run a web site. The below will setup containers locally needed to run a MySQL database and an Apache + PHP web server
All of this will be running on a Linux virtual machine in order to duplicate as close as possible the production hosting environment.
## Contents
* [Three Choices](#three-choices)
* [Setup Docker](#setup-docker)
1. [Install Docker](#install-docker)
2. [Configure SSL](#configure-ssl)
3. [Configure Docker](#configure-docker)
* [*Prepackaged Image*](#prepackaged-image)
* [*Video Walk-through*](#video-walk-through)
* [*Example Template*](#example-template)
4. [Start Wordpress](#start-wordpress)
5. [Install Theme](#install-theme)
6. [Install Plugins](#install-plugins)
* [Enable Debugging](#enable-debugging)
* [Docker Multi-site Setup](#docker-multi-site-setup)
## Three Choices
There are currently three sets of instructions for setting up a Disciple Tools server locally using Docker. Choose the one that suites your needs best.
1. Prepackaged Image
is the easiest of the three to install (similar effort to setting up a [LocalWP](/local-setup/localwp-setup) environment), but it is difficult to update preinstalled plugins.
2. Video Walk-through
This [YouTube playlist](https://www.youtube.com/playlist?list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE) shows how to set up for D.T. Mobile App development on a local machine, which includes setting up the Docker server environment
The videos do not follow these instructions exactly, but it is better to use them to help understand these instructions, instead of following them by themselves.
3. Example Template
which these instructions were originally based on, and provides a downloadable set configuration files, which can be updated.
## Setup Docker
### Install Docker
* Install the correct Docker download for your platform
> **For Windows:**
>
> * When you start the Docker Desktop, **if necessary** it will provide you with additional instructions to update WSL 2 (Windows Subsystem for Linux)
> * If the user account you commonly use does not have admin privileges, you can add it to the docker-users group so you can run docker directly **without** requiring “runas” (similar to “sudo” in Linux/MacOS)
>
> From the `Computer Management` app: open System Tools > Local Users and Groups > Groups, double click the "docker-users" group and from the "Add..." dialog add the desired user account.
>
> 
### Configure SSL
Set up the self-signed SSL certificate. (The instructions are explained [here](https://medium.com/@nh3500/how-to-create-self-assigned-ssl-for-local-docker-based-lamp-dev-environment-on-macos-sierra-ab606a27ba8a) in detail)
> **Warning:** If you will be working on the **Mobile app** code, it [does not currently support Https](https://developers.disciple.tools/local-setup/pages/-MU8GvBzSmovtve9l8dv##https-workaround) when connecting to a local server, so this step is not required.
>
> **For Windows:**
>
> * The instructions above for MacOs work if you have OpenSSL installed
> * OpenSSL is available via
>
> [Git Bash](https://git-scm.com/download/win),
>
> [Ubuntu for Windows](https://www.microsoft.com/en-us/store/p/ubuntu/9nblggh4msv6?SilentAuth=1),
>
> [Cygwin](https://www.cygwin.com/),
>
> or [Chocolatey](https://www.cygwin.com/)
>
> **Note:** Already updated *dev.conf* and *dockerfile* configuration files are available from
1. From command line in the project root directory (your copy of the Github repository) run:
```bash
> openssl req -x509 -nodes -days 365 -newkey rsa:2048 -keyout server.key -out server.crt
```
2. Specify the Common Name as 'local.disciple.tools'. You may answer the other questions however you wish.
3. Site will be available on (if you add the needed hosts file mapping) or
### Configure Docker
Configure Docker according to which one of the [3 approaches](#three-choices) you choose:
#### ***Prepackaged Image***
1. Download the `docker-compose.yml` file from into your working directory (or clone it from GitHub)
2. Create a `.env` file and copy/paste the following, and then update the values:
```
DOMAIN=mydomain
EMAIL=noreply@mydomain
MYSQL_USER=wordpress
MYSQL_PASSWORD=wordpress
MYSQL_ROOT_PASSWORD=somewordpress
```
(`DOMAIN` value can be an IP address - e.g., `127.0.0.1` or `192.168.1.2`)
#### ***Video Walk-through***
* As mentioned [above](#three-choices), the [YouTube playlist](https://www.youtube.com/playlist?list=PLNZnizaetELN6_2k3_iRxBhJuyavhqawE) works best to help understand these instructions, rather than following it alone.
#### ***Example Template***
* These instructions were originally based on
* Download the files, or clone the repository from GitHub, to use as a template.
### Start Wordpress
> **Warning:** The configuration files were up to date the last time they were edited, but *always* make sure to double check what the most up to date versions of the software components are, or make certain to install mutually compatible versions.
>
> For example, the *dockerfile* should have up to date version numbers for Wordpress and PHP.
>
> * The first line will look like:
>
> `FROM wordpress:5.4-php7.4-apache`
> * Check for which version of Wordpress disciple-tools-theme has been tested with.>
1. Run `docker-compose up -d` from the project root directory (or `npm run docker-start`).
1. The first time this is run, it will need to download all of the machine images, so it may take a little while.
2. There will be some warning messages that can be ignored, unless Docker cannot bring the Wordpress and Mysql containers up.
2. You should be able to access the site via (if you add the needed hosts file mapping), or
> **For Windows:** You will need to add a “security exception” in your browser from its warning dialog (depending on browser).
>
> **Warning:** When you configure WordPress from “” or “” you will have to continue to use that address or reconfigure it from the …/wp-admin/options-general.php settings page to switch.
3. Step through the WordPress installation process.
* Language:
* Site Title:
* Username:
* Password:
* Your Email:
* Press “Install WordPress”
> **Note:** If you cannot access DT’s home page: or other pages try this:
>
> * Login to *wp-admin* and go to  *Settings > Permalinks*. *You don’t need to change anything*, just click *Save* at the bottom.
>
> (Source: section: [Errors on New Installation](https://developers.disciple.tools/hosting/404))
### Install Theme
> **NOTE:** If you used the [**Prepackaged Image**](#prepackaged-image) this has already been done for you.\
> **However,** if you need to update the theme you must do it manually from within the container!
1. Go to
2. Download latest release:
3. Follow installation instructions:
### Install Plugins
> **NOTE:** If you used the [**Prepackaged Image**](#prepackaged-image) some plugins have already been installed for you.\
> **However,** if you need to update a pre-installed plugin you must do it manually from within the container!
Some production plugins are available for installation from the **Extensions** tab. For developement, or unlisted plugins:
1. Download the latest plugin zip files from below, and install plugins using these instructions:
1.
2.
2. Download JWT Authentication for WP REST API from:
1. Follow directions on plugin page to add auth header config to .htaccess
2. Follow directions on plugin page to add 2 values to wp-config.php
## Enable Debugging
* Edit wp-config.php to add the following values:
```php
define( 'WP_DEBUG', true ); // Enable WP_DEBUG mode
define( 'WP_DEBUG_LOG', true ); // Enable Debug logging to the /wp-content/debug.log file
```
## Docker Multi-site Setup
See
1. Add the following to `wp-config.php`
```php
/* Multisite */
define('WP_ALLOW_MULTISITE', true);
```
2. Go to Tools -> Network Setup and follow on-screen directions, adding the necessary code to .htaccess and wp-config.php
3. After changes, login again and return to wp-admin.
4. A new My Sites item appears in the top menu. Go to My Sites -> Network Admin -> Dashboard
* Copy `disciple-tools-multisite.php` into `wp-content/plugins/disciple-tools-multisite`
5. Add all of the sites as you desire.
* For each site you add, add the needed entry to your local hosts file.\
For example:
```
127.0.0.1 site1.local.disciple.tools
```
# Gulp - CSS and JS
## Setting Up the Build Process
D.T Uses gulp to compile and minify the css and javascript. If you will be contributing styling or JS changes you will need to use gulp.
* First you need to have Node.js installed on your computer. You can download and install Node.js from [here](https://nodejs.org/)
* Second from your terminal enter the Disciple Tools theme folder.
* From your Disciple Tools theme folder run npm install. You should only have to do this once.
* Once the install process is complete you should be able to type `gulp` in the command line and see an output that looks something like
```
[15:09:08] Using gulpfile /wp-content/themes/disciple-tools-theme/gulpfile.js
[15:09:08] Starting 'default'...
[15:09:08] Starting 'styles'...
[15:09:08] Starting 'scripts'...
[15:09:15] Finished 'scripts' after 7.14 s
[15:09:16] Finished 'styles' after 8.02 s
[15:09:16] Finished 'default' after 8.02 s
```
* If you will making multiple changes to css or js files you will probably not want to have to run gulp after every change. In this case you can use the command `gulp watch` and gulp will watch for any changes to scss or js files and will automatically run when the file is changed.
## CSS
D.T uses SCSS for CSS styiling. The SCSS files can be found under `dt-assets > scss.`
You probably want to modify:
* `_details.scss` for contact, group etc record page
* `_list.scss` for the list page
* `_main.scss` most other cases
Compile your changes to css by running `gulp` in your terminal in the theme root.\
This generates the `dt-assets/build/css/style.min.css` file that is used by the browser
## JS
If you modify `dt-assets/js/footer-scripts.js` you will also need to run `gulp` to apply the changes.\
The outpet is `dt-assets/build/js/scripts.min.js`
# Code Contribution
# Theme Contribution Guidelines
Thank you for joining us in contributing to Disciple.Tools! These are the guidelines we expect you to follow in writing code that will be used in or with D.T
## How to Contribute to the theme
Follow these steps.
1. Fork it!
2. Create your feature branch: `git checkout -b my-new-feature`
3. Commit your changes: `git commit -am 'Add some feature'`
4. Push to the branch: `git push origin my-new-feature`
5. Submit a pull request
## Setup for Develope
### Install Composer
Download and install composer via [their instructions](https://getcomposer.org/download/) or via Homebrew:
```
$ brew update
$ brew install composer
```
Install o Run Composer to install dependencies
```
$ composer install
```
### Install NPM dependencies
```
$ npm install
```
## Translations
D.T is already being used in multiple languages. Please help us make D.T translable by taking full advantage of Wordpress’ translatable strings. Any string that will be read by the user must be marked as translatable. Ex: ``
Make sure you look for these in PHP, HTML and JavaScript code.
## PHPCS
We use [PHPCS](https://github.com/squizlabs/PHP_CodeSniffer) and [PHPCS WordPress Coding Standards](https://github.com/WordPress-Coding-Standards/WordPress-Coding-Standards) to test for syntax errors, security vulnerabilities and some styling rules. We expect your commits to pass these tests.
Run `composer install` or `composer update` first.
In the theme you can run `./tests/test_phpcs.sh` or create a pull request to our repo and Travis CI will run the tests for you.
If you are working on a plugin based off our starter plugin run `./includes/admin/test/test_phpcs.sh`
Note: rules for PHPCS are located in the `phpcs.xml` file. We sometimes update the rule list as PHPCS updates. We’ll update the [starter plugin](https://github.com/DiscipleTools/disciple-tools-starter-plugin) `phpcs.xml`, you might want to look there to get the latest version.
Run phpcbf to auto-fix some phpcs issues: `vendor/bin/phpcbf --standard="phpcs.xml" dt-core/`
## Missing WP functions errors
If all of the WP functions are showing up as errors saying that the function is undefined, you can try adding the entire WP site to your editor, so that it can automatically pick up the WP function definitions from `wp-include`, `wp-admin` etc.
## PHPCS sniff errors
If you get errors such as, `phpcs Referenced sniff "WordPress" does not exist` this could be due to your editor not using the correct `phpcs` or `phpcs.xml` file. It could be using a globally installed version instead.
Make sure that you point your editor to the local phpcs file in `vendor/bin/phpcs` and phpcs config file `phpcs.xml` in the `disciple-tools-theme` directory.
In vscode the settings look roughly like this, depending on your setup and where the settings are being kept. In this example a directory specific settings.json file is being used in the root of the website. The paths, may need to be the full absolute paths or relative paths to where the settings file is.
```
"phpcs.executablePath": "wp-content/themes/disciple-tools-theme/vendor/bin/phpcs",
"phpcs.standard": "wp-content/themes/disciple-tools-theme/phpcs.xml"
```
## GitHub and Commits
For new plugins copy our [starter plugin](https://github.com/DiscipleTools/disciple-tools-starter-plugin).
To commit to the theme or an existing plugin start by creating a fork of the repository. When you are ready, create a pull request into our repo.
Note: Depending on your context you may wish to use an anonymous GitHub account.
## `WP_DEBUG`
Enable `WP_DEBUG` in your `wp-config.php`: `define('WP_DEBUG', true);` Checking out a PR and seeing the orange debug table is disappointing.
We look forward to hearing from you!
# How to Correctly Contribute to the Disciple Tools Repository
Keeping track of upstream, origin, and local can be a bit overwhelming sometimes. Here's a step-by-step process that shows you how to contribute to DiscipleTools and not go mad in the process. :)
Follow these steps to make sure your code gets neatly added to the Disciple Tools Theme Repository.
## 1. Fork the repo
The fork will be called called **origin**
In order to fork the main DT repository, go to it and click the `Fork` button on the top-right corner of the page.
## 2. Clone the fork
The cloned fork will be called **local**
`git clone https://github.com/[YOUR_GITHUB_USERNAME]/disciple-tools-theme.git`
## 3. Keep your fork up to date with upstream
The original Disciple.Tools repo will be called **upstream**, but first we have to set it up.
`git remote add upstream https://github.com/DiscipleTools/disciple-tools-theme.git`
To check that everything has been set up correctly, run:
`git remote -v`
**You should see something like this:**
`origin https://github.com/[your username]/disciple-tools-theme.git (fetch)`
`origin https://github.com/[your username]/disciple-tools-theme.git (push)`
`upstream https://github.com/DiscipleTools/disciple-tools-theme.git (fetch)`
`upstream https://github.com/DiscipleTools/disciple-tools-theme.git (push)`
We're almost there! Now we need to create a local branch directly from DT's upstream repository's master branch (the latest stable version of the code).
## 4. Create a new local branch from upstream
Say you want to create a new branch for the feature you want to create or for the bug you want to fix. First, we need to make sure your forked repo has the latest stable version of the code from DiscipleTools. In other words, we need to fetch the upstream code. To do this, type:
`git fetch upstream`
And then create a new branch from upstream master:
`git checkout -b new-branch upstream/master`
This new branch will not contain remnants of previous commits that were merged in via the squash method. You should receive a message like the following:
`Branch 'new-branch' set up to track remote branch 'master' from 'upstream'.`
`Switched to a new branch 'new-branch'`
## All set!
The 'new-feature' branch should be a mirror of the upstream repository's master branch. Check your branches by running the following command:
`git branch`
## 5. Commit your code
After you work your code-writing magic, commit the changes to your fork (AKA, origin), making sure you specify the branch name that doesn't yet exist on your fork.
`git commit -am 'my new awesome commit description goes here'`
`git push origin new-branch`
## 6. Send the code over to DT
In order to get your code into the official Disciple.Tools repository for all the world to enjoy, you need to create a pull request to the upstream repository.
To do this, go to your fork's Github page, select the *new-feature* branch and Click 'Compare & pull request' and then follow the steps shown on the page.
If there are no problems, the Disciple Tools team with merge your code with the main repository.
## 7. Cleaning up
After your code has been pulled into DT, you should clean up your local repo because branches can start to clutter your workspace. To do this, we recommend deleting the `new-feature` branch by typing:
`git branch -d new-feature`
And then push those changes to your fork:
`git push origin --delete new-feature`
## Done!
Thanks for contributing your time and skill on this project. We greatly appreciate every line of code you send our way.
# How to Translate Your Plugin
You finished coding your Disciple.Tools plugin and now you want to make it accessible to the whole community. Before uploading it, you can add translations in order to make the content understadable for every user.
There are a few different ways of translating your plugin. Here are a few.
## Using Poedit Software
1. Download Poedit: [link here](https://poedit.net/download/)
2. Open the software and select the `Edit a translation` option
3. Select the `default.pot` file in your plugin's `/languages` folder
4. Go to the `Catalog` menu and click on `Update from Source Code`. You should see the strings used in your plugin's code.
5. Click the `Create New Translation` button at the bottom and select the language you want to translate into
6. Translate each string by clicking on them and add its respective translation in the `Translation` text area
7. After translating every string, save the file. Poedit will suggest a file name that is the language code you selected for your translation. Don't delete or modify that text. Write your plugin name before it making sure you only use lowercase and replace spaces with hyphens. (`eg. my-plugin-name-es_ES.po`)
8. Make sure your code echoes the translated strings with the following format: ``
9. Done! Your translation should appear for your plugin on the Disciple.Tools theme.
## Using Poedit & Poeditor Website for community translations
1. Register in [www.poeditor.com](http://www.poeditor.com) and create a new project for your plugin
2. Add a new language
3. In Poedit, load the `default.pot` file in your plugin's `/languages` folder
4. Go to the `Catalog` menu and click on `Update from Source Code`. You should see the strings used in your plugin's code.
5. Save the `default.pot` file with the imported strings
6. In poeditor.com, go to the translation project for your plugin and upload the `default.pot` file by clicking the `Import` button. Your plugin's terms should have been added automatically.
7. Translate all the terms and export the `.po` and `.mo` files from the project language menu. These files should be saved in your plugin's `/languages` folder. The file name should be your plugin's name in lowercase and with hyphens instead of spaces followed by the language code. (eg. `my-plugin-name-es_ES.po`)
8. Make sure your code echoes the translated strings with the following format: ``
9. Done! Your translation should appear for your plugin on the Disciple.Tools theme.
## How to translate strings in JS files
1. Open `dt-assets/functions/enqueue_scripts.php`.
2. Search for the if statement that looks for the PHP file that calls your JS script. If it doesn't appear in `enqueue_scripts.php`, you will have to create an if statement that looks for it. Live examples of these if statements already exist in this file. You can use them as a reference.
3. Inside the if statement, make sure that your JS script is added with `dt_theme_enqueue_script()`. We're going to need the handle parameter for the next step (the first parameter in the `dt_theme_enqueue_script()` function).
### Example:
```
dt_theme_enqueue_script('my_js_script', 'path/to/script/my-js-script.js' );
```
1. Create a `$translations` array that contains the keys and values for what you want the string to show.
### Example:
```
$translations = [
'hello_world' => __( 'Hello, World!', 'disciple_tools' ),
'hello_user', => _x( 'Hello, %s!', 'Hello, John!', disciple_tools' ),
];
```
1. If it's not already there, add a `wp_localize_script()` function to localize your script. Script localization passes values obtained through PHP to your JS script.
2. The `wp_localize_script()` should have the handle from step 3 passed as the first parameter. The second parameter should be `new_record_localized` and the third parameter should be the information you want to localize. See example below.
```
wp_localize_script( 'my_js_script', 'new_record_localized', array(
'translations' => $translations,
) );
```
1. Now we move to the JS file, find the place that contains the string you wish to translate and replace it with the translated string. Translated strings are inside the `window.new_record_localized.translations` object.
### Example:
```
function say_hello_world() {
return window.new_record_localized.translations['hello_world'];
// This returns 'Hello, World!'
}
function say_hello_to_user(username) {
return window.new_record_localized.translations['hello_user'].replace('%s', username);
// username = 'Bob', this returns: 'Hello, Bob!'
}
```
# Style Guide
## Branding
Please use "Disciple.Tools" or "D.T" and avoid "Disciple Tools", or "DiscipleTools" or other variants.
## Logos
| File | Description | Link |
| -------------------------------------------------------------------------------------------------- | -------------------- | ----------------------------------------------------------------------------------------------------- |
|  | Black logo with text | [Download](https://github.com/DiscipleTools/Documentation/blob/master/assets/logos/DT-black-text.png) |
|  | White logo with text | [Download](https://github.com/DiscipleTools/Documentation/blob/master/assets/logos/DT-white-text.png) |
|  | Icon in png format | [Download](https://github.com/DiscipleTools/Documentation/blob/master/assets/logos/dt-caret.png) |
|  | Icon in svg format | [Download](https://github.com/DiscipleTools/Documentation/blob/master/assets/logos/dt-caret.svg) |
## Theme Colors
 Main color blue: #3f729b\
 Secondary color: #8BC34A\
 Darker blue: #224f72\
 Success/New green: #4caf50\
 Action butons: #00897B
Status Colors\
 Active: #4CAF50\
 Paused: #FF9800\
 New: #F43636\
 other: #366184\
 Archived: #808080
## CSS filters for svg icons.
Add this css to an icon to change its color.
To #3F729B  `filter: invert(41%) sepia(42%) saturate(518%) hue-rotate(164deg) brightness(94%) contrast(100%);`
To find a good filter see
Use the existing `dt-white-icon`,`dt-blue-icon` and`dt-green-icon` classes to quitly change an icon color.
Example: `
` gives 
`` gives 
# Disciple.Tools Code of Conduct
Like the technical community as a whole, the DiscipleTools team and community is made up of volunteers from all over the world. Diversity is a strength, but it can also lead to communication issues and unhappiness. To that end, we have a few ground rules that we ask people to adhere to.
**Be friendly and patient**.
**Be welcoming**. We strive to be a community that welcomes and supports people of all backgrounds and identities. This includes, but is not limited to members of any race, ethnicity, culture, national origin, colour, immigration status, social and economic class, educational level, sex, sexual orientation, gender identity and expression, age, size, family status, political belief, religion, and mental and physical ability.
**Be considerate**. Your work will be used by other people, and you in turn will depend on the work of others. Any decision you take will affect users and colleagues, and you should take those consequences into account when making decisions. Remember that we’re a world-wide community, so you might not be communicating in someone else’s primary language.
**Be respectful**. Not all of us will agree all the time, but disagreement is no excuse for poor behavior and poor manners. We might all experience some frustration now and then, but we cannot allow that frustration to turn into a personal attack. It’s important to remember that a community where people feel uncomfortable or threatened is not a productive one. Members of the DiscipleTools community should be respectful when dealing with other members as well as with people outside the DiscipleTools community.
**Be careful in the words that you choose**. We are a community of professionals, and we conduct ourselves professionally. Be kind to others. Do not insult or put down other participants. Harassment and other exclusionary behavior aren’t acceptable. This includes, but is not limited to:
* Violent threats or language directed against another person.
* Discriminatory jokes and language.
* Posting sexually explicit or violent material.
* Posting (or threatening to post) other people’s personally identifying information (“doxing”).
* Personal insults, especially those using racist or sexist terms.
* Unwelcome sexual attention.
* Advocating for, or encouraging, any of the above behavior.
* Repeated harassment of others. In general, if someone asks you to stop, then stop.
**When we disagree, try to understand why**. Disagreements, both social and technical, happen all the time and DiscipleTools is no exception. It is important that we resolve disagreements and differing views constructively. Remember that we’re different. Different people have different perspectives on issues. Being unable to understand why someone holds a viewpoint doesn’t mean that they’re wrong. Don’t forget that it is human to err and blaming each other doesn’t get us anywhere. Instead, focus on helping to resolve issues and learning from mistakes.
This isn’t an exhaustive list of things that you can’t do. Rather, take it in the spirit in which it’s intended - a guide to make it easier to enrich all of us and the technical communities in which we participate. This code of conduct applies to all spaces of the DiscipleTools community.
Attribution
Original text courtesy of the Sphinx project: