Customer Address Book

The Customer Address Book Extension allows registered customers to save (and later edit) more than one address in their account.

At checkout, the customer can be asked to choose from one of their saved addresses and your website can then auto-populate the delivery and billing addresses so that they can checkout more quickly.

Addresses are configured on an 'address book' page, as shown on the example below.

Saved addresses are presented to the customer at checkout, as shown on the example below.


Installing the extension

We've provided detailed instructions below on how you can install this extension on your theme's files. Installing the extension requires at least basic knowledge of HTML/CSS/JS.

We can install this extension for you if you prefer, to request installation by us navigate to your account and click the 'request installation' button on the extension page. The charge for this service is listed in your account.

To add the relevant code you'll need to use the page editor, if you haven't used this tool before then we'd advise familiarising yourself with it by reviewing the help guidance here.

You'll need to use the 'advanced mode' on the page editor so that you can create new files.

Important!

Please read the Javascript warning in the 'checkout' section (near the bottom of this help guide) before embarking on this installation.


Account Addresses

Saved addresses are presented to a user (so they can edit and delete them) on a new page in their account with the path account/addresses. You'll need to create a new twig view to enable this page.

1. Create a new file called account_addresses.twig

2. We'd recommend copying and pasting the content from the account_home.twig view into this new file so that you have a base file to work from.

3. You'll then need to present a table to the user which contains the details of the user's current saved addresses:

{% for address in addresses %}
    {{ address.name }}
    {{ address.all }}
    {{ address.url }}
    <form action="{{ address.url }}" method="post">
        <input type="hidden" name="delete" value="1">
        <button type="submit">Delete</button>
    </form>
{% endfor %}

{{ address.name }} Renders the name stored on the address, e.g. 'Joe Bloggs'

{{ address.all }} Renders the stored address

{{ address.url }} Renders the URL of the stored address (at which it can be edited) - see below

<form action="{{ address.url }}"...></form> Renders a button allowing the user to delete the stored address

4. You may also want to include a link on this page to allow a user to create a new address, this can be done at the path /account/address.

5. A sample page file for the account/addresses page is shown below (please note that theme structures vary and so this file may not work 'out of the box' on your theme depending on how page files are rendered through templates (specifically the page template).

{% extends 'templates/page.twig' %}
{% set title = 'Your Addresses' %}
{% set wide = true %}
{% block content %}
    <div class="row">
        <div class="col-sm-12">
            <p>
                <a href="/account/address">
                    Create A New Address
                </a>
            </p>
            <div class="table-responsive account-home-table">
                <table class="table table-condensed">
                    <thead>
                        <tr>
                            <th>NAME</th>
                            <th>LOCATION</th>
                            <th>EDIT</th>
                            <th>DELETE</th>
                        </tr>
                    </thead>
                    <tbody>
                        {% for address in addresses %}
                            <tr>
                                <td>
                                    {{ address.name }}
                                </td>
                                <td>
                                    {{ address.all }}
                                </td>
                                <td>
                                    <a href="{{ address.url }}">
                                        Edit
                                    </a>
                                </td>
                                <td>
                                    <form action="{{ address.url }}" method="post">
                                        <input type="hidden" name="delete" value="1">
                                        <button type="submit">Delete</button>
                                    </form>
                                </td>
                            </tr>
                        {% else %}
                            <tr>
                                <td colspan="4">You do not have any addresses.</td>
                            </tr>
                        {% endfor %}
                    </tbody>
                </table>
            </div>
        </div>
    </div>
{% endblock %}

Don't forget to save your changes once done.


Account Address

Users create a new stored address, or edit an existing one, on a new page in their account with the path /account/address. You'll need to create a new twig view to enable this page.

1. Create a new file called account_address.twig

2. We'd recommend copying the content from the account_edit.twig view into this new file so that you have a base file to work from.

3. You'll then need to present a form to the user which allows them to create/edit a saved address. We recommend calling the file address_form.twig

4. The address_form.twig file can contain the following form fields (twig variables to render existing content are shown in brackets) and follow the same format to the account_form.twig file.

company_name (address.company_name)
first_name (address.first_name)
last_name (address.last_name)
line1 (address.line1)
line2 (address.line2)
line3 (address.line3)
city (address.city)
postcode (address.postcode)
country_id (address.country_id)

5. A sample file for the /account/address page is shown below (please note that theme structures vary and so this file may not work 'out of the box' on your theme depending on how page files are rendered through templates (specifically the page template).

{% extends 'templates/page.twig' %}
{% set title = address.id ? 'Edit Your Saved Address' : 'Create A New Address' %}
{% set wide = true %}
{% block content %}
    <div class="row">
        <div class="col-lg-6 col-md-7">
            {% include 'partials/address_form.twig' %}
        </div>
    </div>
{% endblock %}

Don't forget to save your changes when once done.


Testing

You should now test the implementation to ensure that customers can:

• Create a new saved address
• View each saved address
• Edit an existing saved address
• Delete an existing saved address


Menu/page links

You'll need to allow your users to access these new pages through your website's menus or through text on your website, else they won't be able to find them.

If your theme has an account area side menu then you can add in a link to the stored addresses page by creating a link to /account/addresses.

You can also add in a link to the page to create a new address, by creating a link to /account/address.


Checkout

At checkout, you'll want your customers to be able to select from one of their saved addresses when entering their delivery and billing addresses.

This is achieved by placing Twig, HTML and Javascript code on the checkout_address.twig file.

Open the checkout_address.twig file.

This page has access to the addresses property on the customer object.

You can use the code below to render the saved addresses on this page (it checks that a customer is logged into an account and that they have at least one saved address).

{% if global.customer.id and global.customer.addresses %}
    {% for address in global.customer.addresses %}
        {{ address.name }}
        {{ address.all() }}
    {% endfor %}
{% endif %}

You'll now need to code the Javascript on your theme that will allow them to select from one of these saved addresses and auto-populate the checkout fields with the selected address. This will usually be done with a radio button (as shown in the example below).

Warning!

Unfortunately, we cannot provide instructions on exactly what Javascript code to enter into your theme's files to make this function work. All themes are different and the Javascript code used will differ from theme to theme. The code shown below is an example implementation that may not necessarily work on your theme.

Near the top of the checkout_address.twig file the following code is added (above the <form> tag).

{% if global.customer.id and global.customer.addresses %}
    <script>
        var savedAddresses = {{ global.customer.addresses|json_encode|raw }},
            customerEmailAddress = '{{ global.customer.email }}';<span class="redactor-invisible-space"></span>
        {% for address in global.customer.addresses %}
            savedAddresses[{{ loop.index0 }}].country_name = '{{ address.countryName }}';
        {% endfor %}
    </script>
{% endif %}

The code to present the user with saved addresses is then placed within the <form> tag.

{% if global.customer.id and global.customer.addresses %}
    <h3>Select one of your saved addresses...</h3>
    {% for address in global.customer.addresses %}
        <input type="radio" name="address_id" value="{{ address.id }}" class="saved-address-radio">
        {{ address.name }}
        <br>
        {{ address.all() }}
    {% endfor %}
    <h3>Alternatively enter a new address below...</h3>
{% endif %}

A class is added to each form field.

checkout-field-{{ label }}

In application.js, code is added to pre-populate the address fields with the selected address.

$('.saved-address-radio').on('change', function() {
    if(!this.checked) {
        return;
    }
    var address = false,
        addressId = $(this).val(),
        container = $(this).closest('.address-container');
    for(var i = 0, length = savedAddresses.length; i < length; i++) {
        if(savedAddresses[i].id == addressId) {
            address = savedAddresses[i];
            break;
        }
    }
    if(!address) {
        return;
    }
    container.find('.checkout-field-name input').val(address.first_name + ' ' + address.last_name);
    container.find('.checkout-field-company input').val(address.company_name);
    container.find('.checkout-field-email input').val(customerEmailAddress<span class="redactor-invisible-space">);</span>
    container.find('.checkout-field-postcode input').val(address.postcode);
    container.find('.checkout-field-address1 input').val(address.line1);
    container.find('.checkout-field-address2 input').val(address.line2);
    container.find('.checkout-field-address3 input').val(address.line3);
    container.find('.checkout-field-city input').val(address.city);
    container.find('.checkout-field-province input').val(address.province)
    container.find('.checkout-field-state select').val(address.state_id).trigger('change render update');
    container.find('.checkout-field-country select').val(address.country_name).trigger('render');
});

Once done, save your changes and test each feature to ensure it is working correctly.


Saving an address from the checkout page

The visitor can opt to save a new address entered on the checkout page.

This is achieved by including a field named save_customer_address. For example

<p>
    <label>Save this address</label>
    <input type="checkbox" name="save_customer_address">
</p>

This tick box should be surrounded by a check that the visitor is logged into a customer account using the global.customer.id variable.

You should check that the address being saved is a new address rather than an address already saved in the account. The platform may return an error if the visitor attempts to save an address already saved.

The address will be saved once the checkout form is submitted (by clicking a payment button).