Customer address book

Important Information

ShopWired's platform checkout feature automatically includes address book functionality so that users can choose from stored addresses (or add new ones) during the checkout flow. Theme changes are not required to enable address book functionality.

If you're not already using the platform checkout feature, we'd strongly recommend upgrading your account to do so, please contact us to enable this feature.

Version 3 and later themes

All themes installed in ShopWired accounts on or after 3rd May 2020 are Version 3 (or later themes) which have inbuilt support for address book functionality.

If you're using a Version 3 or later theme, you do not need to make coding changes to support this feature and can instead just install the app.

General installation guidance

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

We can install this app for you if you prefer, to request installation by us navigate to your account and click the 'request installation' button on the app 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.

Address book functionality within customer accounts

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 menu (usually at the side of the page) 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.

Address book functionality at 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 %}

Javascript

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).

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).