Commit ee748ccf authored by mattwire's avatar mattwire
Browse files

Add documentation. Release 1.10

parent 8f9963d8
# Postcode lookup for CiviCRM
## Overview
For having postcode lookup feature in CiviCRM backend and Front end profiles.
### Supported Providers
* [AFD](http://www.afd.co.uk)
* [Civipostcode](http://civipostcode.com/)
* [Experian](http://www.qas.co.uk)
* [PostcodeAnywhere](http://www.postcodeanywhere.co.uk/)
* [getAddress()](https://getaddress.io/)
### Installation
1. See: https://docs.civicrm.org/sysadmin/en/latest/customize/extensions/#installing-a-new-extension.
1. Configure postcode lookup provider details in *Administer->Postcode Lookup*.
### Permissions
**From version 1.6 you need to give the `Access CiviCRM Postcode lookups` permission to anyone who can do postcode lookups (eg. anonymous user).** Previously the permission required was `Access CiviEvent`.
### Integration with Drupal Webform
This drupal module provides integration with Drupal Webform: https://github.com/compucorp/webform_civicrm_postcode
### Usage
* For backend, postcode lookup features is automatically enabled for address fields when adding/editing
contacts and configuring event location.
* For front end profiles, postcode lookup feature is enabled for payment billing address, primary address
and all location types set in *Administer->Postcode lookup*.
Include 'Supplemental Address 1' and 'Supplemental Address 2' fields in the profile for address lines based on the rules in the Royal Mail programmers guide.
## Changelog
### 1.9
* Cleanup the postcode selector that was being added multiple times in some cases.
* Only show a single loading "spinner" when searching for postcodes.
### 1.8
* Update jQuery and trigger change on all billing fields that we touch to trigger other functions (eg. billing address is the same). This fixes issues when "My Billing address is the same" is checked.
* Switch to \Civi::settings to get/set settings (removes a deprecated function warning).
### 1.7
* Fixed parsing of address.
This extension adds a UK postcode lookup service to CiviCRM.
For more information see [Documentation](https://docs.civicrm.org/ukpostcodes).
# Postcode lookup for CiviCRM
## Overview
For having postcode lookup feature in CiviCRM backend and Front end profiles.
### Supported Providers
* [AFD](http://www.afd.co.uk)
* [Civipostcode](http://civipostcode.com/)
* [Experian](http://www.qas.co.uk)
* [PostcodeAnywhere](http://www.postcodeanywhere.co.uk/)
* [getAddress()](https://getaddress.io/)
### Installation
1. See: https://docs.civicrm.org/sysadmin/en/latest/customize/extensions/#installing-a-new-extension.
1. Configure postcode lookup provider details in *Administer->Postcode Lookup*.
### Permissions
**From version 1.6 you need to give the `Access CiviCRM Postcode lookups` permission to anyone who can do postcode lookups (eg. anonymous user).** Previously the permission required was `Access CiviEvent`.
### Integration with Drupal Webform
This drupal module provides integration with Drupal Webform: https://github.com/compucorp/webform_civicrm_postcode
### Usage
* For backend, postcode lookup features is automatically enabled for address fields when adding/editing
contacts and configuring event location.
* For front end profiles, postcode lookup feature is enabled for payment billing address, primary address
and all location types set in *Administer->Postcode lookup*.
Include 'Supplemental Address 1' and 'Supplemental Address 2' fields in the profile for address lines based on the rules in the Royal Mail programmers guide.
## Information
Releases use the following numbering system:
**{major}.{minor}.{incremental}**
* major: Major refactoring or rewrite - make sure you read and test very carefully!
* minor: Breaking change in some circumstances, or a new feature. Read carefully and make sure you understand the impact of the change.
* incremental: A "safe" change / improvement. Should *always* be safe to upgrade.
* **[BC]**: Items marked with [BC] indicate a breaking change that will require updates to your code if you are using that code in your extension.
## Release 1.10
* Add postcode lookup to "On Behalf of Organisation"
* Add caching to getAddressIO. Refactor tpl and javascript to improve maintainability.
## Release 1.9
* Cleanup the postcode selector that was being added multiple times in some cases.
* Only show a single loading "spinner" when searching for postcodes.
## Release 1.8
* Update jQuery and trigger change on all billing fields that we touch to trigger other functions (eg. billing address is the same). This fixes issues when "My Billing address is the same" is checked.
* Switch to \Civi::settings to get/set settings (removes a deprecated function warning).
## Release 1.7
* Fixed parsing of address.
......@@ -13,13 +13,12 @@
<url desc="Support">https://lab.civicrm.org/extensions/ukpostcodes/issues</url>
<url desc="Licensing">http://www.gnu.org/licenses/agpl-3.0.html</url>
</urls>
<releaseDate>2020-02-22</releaseDate>
<version>1.9</version>
<releaseDate>2020-12-08</releaseDate>
<version>1.10</version>
<develStage>stable</develStage>
<compatibility>
<ver>5.19</ver>
<ver>5.28</ver>
</compatibility>
<comments>Developed by Veda NFP Consulting LTD.</comments>
<civix>
<namespace>CRM/Civicrmpostcodelookup</namespace>
</civix>
......
site_name: UK Postcode Lookup
repo_url: https://lab.civicrm.org/extensions/ukpostcodes
theme:
name: material
markdown_extensions:
- attr_list
- admonition
- def_list
- codehilite
- toc:
permalink: true
- pymdownx.superfences
- pymdownx.inlinehilite
- pymdownx.tilde
- pymdownx.betterem
- pymdownx.mark
nav:
- Overview: index.md
- Release Notes: releasenotes.md
{*
+--------------------------------------------------------------------+
| Copyright CiviCRM LLC. All rights reserved. |
| |
| This work is published under the GNU AGPLv3 license with some |
| permitted exceptions and without any warranty. For full license |
| and copyright information, see https://civicrm.org/licensing |
+--------------------------------------------------------------------+
*}
{literal}
<script type="text/javascript">
CRM.$(function($) {
var addressSelectors = {/literal}{$ukpostcodesAddressSelectors}{literal};
var blockId = '';
var blockNo = '';
var postCodeHtml = '';
// Location Types from settings
if (addressSelectors) {
$.each(addressSelectors, function(id, address) {
if ($(address.selector).length > 0) {
blockId = address.prefix + address.id;
var postcodeElement = 'inputPostCode_' + blockId;
postCodeHtml = '' +
'<div class="crm-section addressLookup form-item">' +
'<div class="label">' +
'<label for="addressLookup">Search for an address</label>' +
'</div>' +
'<div class="edit-value content">' +
'<div class="postcodelookup-textbox-wrapper">' +
'<input placeholder="Start typing a postcode" name="' + postcodeElement + '" id="' + postcodeElement + '" class="crm-postcodelookup ui-autocomplete-input" style="width: 25em;">' +
'</div>' +
'</div>' +
'<div class="clear" />' +
'</div>';
if ($('#' + postcodeElement).length === 0) {
$(address.beforeSelector).before(postCodeHtml);
var minCharacters = 4;
var postcodeProvider = '{/literal}{$civiPostCodeLookupProvider}{literal}';
if (postcodeProvider !== 'civipostcode') {
$(postcodeElement).attr("placeholder", "Type full postcode to find addresses");
minCharacters = 5;
}
var sourceUrl = CRM.url('civicrm/{/literal}{$civiPostCodeLookupProvider}{literal}/ajax/search', {"json": 1});
$('#' + postcodeElement).autocomplete({
source: sourceUrl,
minLength: minCharacters,
data: {postcode: $('#' + postcodeElement).val(), mode: '0'},
select: function(event, ui) {
if (ui.item.id !== '') {
findAddressValues(ui.item.id, address.id, address.prefix);
}
return false;
},
html: true, // optional (jquery.ui.autocomplete.html.js required)
//optional (if other layers overlap autocomplete list)
open: function(event, ui) {
$(".ui-autocomplete").css("z-index", 1000);
}
});
}
}
});
}
function findAddressValues(id , blockNo, blockPrefix) {
setAddressFields(false, blockNo, blockPrefix);
var sourceUrl = CRM.url('civicrm/{/literal}{$civiPostCodeLookupProvider}{literal}/ajax/get', {"json": 1});
$.ajax({
dataType: 'json',
data: {id: id, mode: '0'},
url: sourceUrl,
success: function (data) {
setAddressFields(data.address, blockNo, blockPrefix);
setAddressFields(true, blockNo, blockPrefix);
}
});
}
function setAddressFields(address, blockNo, blockPrefix) {
var postcodeElement = '#' + blockPrefix + 'postal_code-'+ blockNo;
var streetAddressElement = '#' + blockPrefix + 'street_address-'+ blockNo;
var AddstreetAddressElement = '#' + blockPrefix + 'supplemental_address_1-'+ blockNo;
var AddstreetAddressElement1 = '#' + blockPrefix + 'supplemental_address_2-'+ blockNo;
var cityElement = '#' + blockPrefix + 'city-'+ blockNo;
var countyElement = '#address_'+ blockNo +'_state_province_id';
var countryElement = '#' + blockPrefix + 'country_id-' + blockNo;
if ($(countryElement).length === 0) {
countryElement = '#' + blockPrefix + 'country-' + blockNo;
}
var allFields = {
postcode: postcodeElement,
line1: streetAddressElement,
line2: AddstreetAddressElement,
line3: AddstreetAddressElement1,
city: cityElement
};
if (address === true) {
for (var field in allFields) {
$(allFields[field]).removeAttr('disabled');
}
}
else if(address === false) {
for (var field in allFields) {
$(allFields[field]).attr('disabled', 'disabled');
}
}
else {
$(streetAddressElement).val('');
$(AddstreetAddressElement).val('');
$(AddstreetAddressElement1).val('');
$(cityElement).val('');
$(postcodeElement).val('');
$(countyElement).val('');
if (($(AddstreetAddressElement1).length === 0) && (typeof address.supplemental_address_2 !== 'undefined')) {
if (typeof address.supplemental_address_1 !== 'undefined') {
address.supplemental_address_1 = address.supplemental_address_1 + ', ';
}
address.supplemental_address_1 = address.supplemental_address_1 + address.supplemental_address_2;
}
if (($(AddstreetAddressElement).length === 0) && (typeof address.supplemental_address_1 !== 'undefined')) {
address.street_address = address.street_address + ', ' + address.supplemental_address_1;
}
$(streetAddressElement).val(address.street_address);
$(AddstreetAddressElement).val(address.supplemental_address_1);
$(AddstreetAddressElement1).val(address.supplemental_address_2);
$(cityElement).val(address.town);
$(postcodeElement).val(address.postcode);
$(countryElement).val('1226'); // United Kingdom
if (typeof(address.state_province_id) !== 'undefined' && address.state_province_id !== null) {
$(countyElement).val(address.state_province_id);
}
// Trigger change on all the elements we touch so that other functions can react
// eg. a checkbox for "My billing address is the same".
$(streetAddressElement).trigger('change');
$(AddstreetAddressElement).trigger('change');
$(AddstreetAddressElement1).trigger('change');
$(cityElement).trigger('change');
$(postcodeElement).trigger('change');
$(countryElement).trigger('change')
$(countyElement).trigger('change');
}
}
});
</script>
{/literal}
{* Include file having postcodelookup textbox and JS functions *}
{include file='CRM/Civicrmpostcodelookup/Form/Postcodelookup.tpl'}
{*
+--------------------------------------------------------------------+
| Copyright CiviCRM LLC. All rights reserved. |
| |
| This work is published under the GNU AGPLv3 license with some |
| permitted exceptions and without any warranty. For full license |
| and copyright information, see https://civicrm.org/licensing |
+--------------------------------------------------------------------+
*}
<tr id="addressLookup">
<td colspan="2">
<label for="addressLookup">Search for an address</label><br>
<input placeholder="Start typing a postcode" name="inputPostCode_{$blockId}" id ="inputPostCode_{$blockId}">
</td>
</tr>
{literal}
<style type="text/css">
.ui-autocomplete { height: 200px; overflow-y: scroll; overflow-x: hidden;}
</style>
<script type="text/javascript">
var info = []; //Needed to access data from outside the JSON processing function
cj(document).ready(function() {
var blockNo = {/literal}{$blockId}{literal};
var buttonElement = '#postcodeLookupButton_'+blockNo;
var houseElement = '#inputNumber_'+blockNo;
var postcodeElement = '#inputPostCode_'+blockNo;
var addressResultElement = '#addressResult_'+blockNo;
var addressResultsElement = '#addressResults_'+blockNo;
var minCharacters = 4;
var delay = 200;
var postcodeProvider = '{/literal}{$civiPostCodeLookupProvider}{literal}';
if (postcodeProvider !== 'civipostcode') {
cj(postcodeElement).attr("placeholder", "Type full postcode to find addresses");
minCharacters = 5;
}
cj(function() {
var sourceUrl = CRM.url('civicrm/{/literal}{$civiPostCodeLookupProvider}{literal}/ajax/search', {"json": 1});
cj(postcodeElement).autocomplete({
source: sourceUrl,
minLength: minCharacters,
delay: delay,
data: {postcode: cj( postcodeElement ).val(), number: cj(houseElement).val(), mode: '0'},
//max: {/literal}{crmSetting name="search_autocomplete_count" group="Search Preferences"}{literal},
search: function( event, ui ) {
cj('#loaderimage_'+blockNo).show();
},
response: function( event, ui ) {
cj('#loaderimage_'+blockNo).hide();
},
select: function(event, ui) {
if (ui.item.id != '') {
findAddressValues(ui.item.id, blockNo);
cj('#loaderimage_'+blockNo).show();
}
return false;
},
html: true, // optional (jquery.ui.autocomplete.html.js required)
//optional (if other layers overlap autocomplete list)
open: function(event, ui) {
cj(".ui-autocomplete").css("z-index", 1000);
}
});
});
});
function addslashes (str) {
return (str + '').replace(/[\\"']/g, '\\$&').replace(/\u0000/g, '\\0');
}
function findAddressValues(id , blockNo) {
cj('#loaderimage_'+blockNo).show();
setAddressFields(false, blockNo);
var sourceUrl = CRM.url('civicrm/{/literal}{$civiPostCodeLookupProvider}{literal}/ajax/get', {"json": 1});
cj.ajax({
dataType: 'json',
data: {id: id},
url: sourceUrl,
success: function (data) {
setAddressFields(data.address, blockNo);
setAddressFields(true, blockNo);
},
complete: function (data) {
cj('#loaderimage_'+blockNo).hide();
}
});
}
function setAddressFields(address, blockNo) {
var postcodeElement = '#address_'+ blockNo +'_postal_code';
var streetAddressElement = '#address_'+ blockNo +'_street_address';
var AddstreetAddressElement = '#address_'+ blockNo +'_supplemental_address_1';
var AddstreetAddressElement1 = '#address_'+ blockNo +'_supplemental_address_2';
var cityElement = '#address_'+ blockNo +'_city';
var countyElement = '#address_'+ blockNo +'_state_province_id';
var allFields = {
postcode: postcodeElement,
line1: streetAddressElement,
line2: AddstreetAddressElement,
line3: AddstreetAddressElement1,
city: cityElement
};
if(address == true) {
for(var field in allFields) {
cj(allFields[field]).removeAttr('disabled');
}
}
else if(address == false) {
for(var field in allFields) {
cj(allFields[field]).attr('disabled', 'disabled');
}
}
else {
cj(streetAddressElement).val('');
cj(AddstreetAddressElement).val('');
cj(AddstreetAddressElement1).val('');
cj(cityElement).val('');
cj(postcodeElement).val('');
cj(countyElement).val('');
cj(streetAddressElement).val(address.street_address);
cj(AddstreetAddressElement).val(address.supplemental_address_1);
cj(AddstreetAddressElement1).val(address.supplemental_address_2);
cj(cityElement).val(address.town);
cj(postcodeElement).val(address.postcode);
if(typeof(address.state_province_id) != "undefined" && address.state_province_id !== null) {
cj(countyElement).val(address.state_province_id);
}
cj(countyElement).trigger("change");
}
}
</script>
{/literal}
{if !empty($form.address.$blockId.street_address)}
<tr id="streetAddress_{$blockId}">
<td colspan="2">
{$form.address.$blockId.street_address.label} {help id="id-street-address" file="CRM/Contact/Form/Contact.hlp"}<br />
{$form.address.$blockId.street_address.html}
{if $parseStreetAddress eq 1 && ($action eq 1 || $action eq 2)}
&nbsp;&nbsp;<a href="#" title="{ts}Edit Address Elements{/ts}" onClick="processAddressFields( 'addressElements' , '{$blockId}', 1 );return false;">{ts}Edit Address Elements{/ts}</a>
{help id="id-edit-street-elements" file="CRM/Contact/Form/Contact.hlp"}
{/if}
</td>
</tr>
{if $parseStreetAddress eq 1 && ($action eq 1 || $action eq 2)}
<tr id="addressElements_{$blockId}" class=hiddenElement>
<td>
{$form.address.$blockId.street_number.label}<br />
{$form.address.$blockId.street_number.html}
</td>
<td>
{$form.address.$blockId.street_name.label}<br />
{$form.address.$blockId.street_name.html}<br />
</td>
<td colspan="2">
{$form.address.$blockId.street_unit.label}<br />
{$form.address.$blockId.street_unit.html}
<a href="#" title="{ts}Edit Street Address{/ts}" onClick="processAddressFields( 'streetAddress', '{$blockId}', 1 );return false;">{ts}Edit Complete Street Address{/ts}</a>
{help id="id-edit-complete-street" file="CRM/Contact/Form/Contact.hlp"}
</td>
</tr>
{/if}
{if $parseStreetAddress eq 1}
{literal}
<script type="text/javascript">
function processAddressFields( name, blockId, loadData ) {
if ( loadData ) {
var allAddressValues = {/literal}{if $allAddressFieldValues}{$allAddressFieldValues}{else}''{/if}{literal};
var streetName = eval( "allAddressValues.street_name_" + blockId );
if (streetName === null) streetName = '';
var streetUnit = eval( "allAddressValues.street_unit_" + blockId );
if (streetUnit === null) streetUnit = '';
var streetNumber = eval( "allAddressValues.street_number_" + blockId );
if (streetNumber === null) streetNumber = '';
var streetAddress = eval( "allAddressValues.street_address_" + blockId );
if (streetAddress === null) streetAddress = '';
}
if ( name == 'addressElements' ) {
if ( loadData ) {
streetAddress = '';
}
cj('#addressElements_' + blockId).show();
cj('#streetAddress_' + blockId).hide();
} else {
if ( loadData ) {
streetNumber = streetName = streetUnit = '';
}
cj('#streetAddress_' + blockId).show();
cj('#addressElements_'+ blockId).hide();
}
// set the values.
if ( loadData ) {
cj( '#address_' + blockId +'_street_name' ).val( streetName );
cj( '#address_' + blockId +'_street_unit' ).val( streetUnit );
cj( '#address_' + blockId +'_street_number' ).val( streetNumber );
cj( '#address_' + blockId +'_street_address' ).val( streetAddress );
}
}
</script>
{/literal}
{/if}
{/if}
{* Include file having postcodelookup textbox and JS functions *}
{*{include file='CRM/Civicrmpostcodelookup/Form/Postcodelookup.tpl'}*}
{* Include file having postcodelookup textbox and JS functions *}
{include file='CRM/Civicrmpostcodelookup/Form/Postcodelookup.tpl'}
{* Include file having postcodelookup textbox and JS functions *}
{include file='CRM/Civicrmpostcodelookup/Form/Postcodelookup.tpl'}
\ No newline at end of file
{* Include file having postcodelookup textbox and JS functions *}
{include file='CRM/Civicrmpostcodelookup/Form/Postcodelookup.tpl'}
Supports Markdown
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment