User Guide | Location Helper Data

Helper functions are used to provide value formatting and calculation functionality, or to return data from the carts database tables.

The functions can act independently of data within the cart session, using database table ids or custom data directly submitted to the function to return values, rather than for example requiring the row id of an item in the cart.

This independence from data within the cart session means the functions can be used on pages across a site that do not display cart data, or even on items that have not been added to the cart.

Location Helper Functions

Location Function Index | Location Config | Get Location Session Data | Set Location Session Data | Location Admin Data
Get Location Data from Database

get_shipping_location() | get_tax_location()

Display Location Data Functions

locations_tiered() | locations_inline() | location_zones()

Help with Helper Functions

Show / Hide Help

Name: The name of the function (method).

Data Type: The data type that is expected by the function.

  • bool : Requires a boolean value of 'TRUE' or 'FALSE'.
  • string : Requires a textual value.
  • int : Requires a numeric value. It does not matter whether the value is an integer, float, decimal etc.
  • array : Requires an array.

Required: Defines whether the parameter requires a value to be submitted.

Default: Defines the default parameter value that is used if no other value is submitted.

get_shipping_location()

Looks-up the database and returns all active shipping locations that are of a specific location type and are the child locations of any higher tier shipping location that may be set.
Typically, the returned location data can be used to populate HTML inputs fields.

Library and Requirements

Available via the standard library only.

Requires location database tables to be enabled.

Function Parameters
get_shipping_location(sql_select, location_type_id) Help
Name Data Type Required Default Description
sql_select string | array No FALSE Define the database fields returned via an SQL SELECT statement.
Read the defining SQL documentation for further information.
location_type_id int No 0 Define the location type id that all returned shipping locations should be a direct child of.
See the documentation and examples below for further information.
How it Works

The function looks-up the current shipping location and gets the location id that matches the location type that was submitted.

The function then uses the retrieved location id to query the location table for any child locations with a matching parent location id.

For example, using the default configuration of the flexi cart demo, if the carts current shipping location has been set as a country, and a 'location_type_id' of 1 was submitted, it would return all available states of that specific country.

Notes

This function can be chained with CodeIgniters query functions 'result()', 'row()' etc.

Read the Query Result documentation for further information on all the combined flexi cart and CodeIgniter functions that are available.

Return Values

Failure:FALSE | An error message will be set.

Success:object or array

Example
// Read the defining SQL documentation for further information on setting SQL statements.
$sql_select = array(
'loc_id', 
'loc_name'
);

// The second parameter is an example of a location type id of '1'.
$this->flexi_cart->get_shipping_location($sql_select, 1);

// Produces: 
// SELECT `loc_id`, `loc_name`
// FROM (`locations`)
// WHERE `loc_parent_fk` =  '10'
// 	AND `loc_status` =  1

get_tax_location()

Looks-up the database and returns all active tax locations that are of a specific location type and are the child locations of any higher tier tax location that may be set.
Typically, the returned location data can be used to populate HTML inputs fields.

Library and Requirements

Available via the standard library only.

Requires location database tables to be enabled.

Function Parameters
get_tax_location(sql_select, location_type_id) Help
Name Data Type Required Default Description
sql_select string | array No FALSE Define the database fields returned via an SQL SELECT statement.
Read the defining SQL documentation for further information.
location_type_id int No 0 Define the location type id that all returned tax locations should be a direct child of.
See the documentation and examples below for further information.
How it Works

The function looks-up the current tax location and gets the location id that matches the location type that was submitted.

The function then uses the retrieved location id to query the location table for any child locations with a matching parent location id.

For example, using the default configuration of the flexi cart demo, if the carts current tax location has been set as a country, and a 'location_type_id' of 1 was submitted, it would return all available states of that specific country.

Notes

This function can be chained with CodeIgniters query functions 'result()', 'row()' etc.

Read the Query Result documentation for further information on all the combined flexi cart and CodeIgniter functions that are available.

Return Values

Failure:FALSE | An error message will be set.

Success:object or array

Example
// Read the defining SQL documentation for further information on setting SQL statements.
$sql_select = array(
'loc_id', 
'loc_name'
);

// The second parameter is an example of a location type id of '1'.
$this->flexi_cart->get_tax_location($sql_select, 1);

// Produces: 
// SELECT `loc_id`, `loc_name`
// FROM (`locations`)
// WHERE `loc_parent_fk` =  '10'
// 	AND `loc_status` =  1

locations_tiered()

Gets all current active locations and formats them into an array, grouped into each locations respective location type.
This data can then be used to create a tiered group of HTML select menus listing all available locations group by each location type.

Library and Requirements

Available via the lite, standard and admin libraries.

Requires all location database tables to be enabled.

How it Works

The function runs a SQL SELECT query to get all location types. The location types are then looped through and another SQL SELECT query is run to get all locations that are related to the location type.

If locations exist for each location type, then they are added to a multi-dimensional array of each location type and its related locations.

The returned array data can then be used to create a tiered group of HTML select menus.

Notes

The intended purpose of this function is use the returned data to create a series of HTML select menus that are dependent of each other.

Using the default demo data as an example, this means that there would be three select menus, Countries, States and Post/Zip Codes. When a Country is selected, the State select menu would then list States from that Country rather than all States from all Countries.

To improve the user experience of updating the data displayed via the select menus when an option has been selected, an example JavaScript function and snippet has been included in the demo. This is not a part of the flexi cart library, so needs to be included in your own JavaScript include files. It is free for you to use and customise however you wish.

Return Values

Failure:array (Empty) | An error message will be set if a required table/feature is disabled.

Success:array

Example
$this->flexi_cart->locations_tiered();

// Click to show an example array produced.
Array
(
[Country] => Array
(
	[0] => Array
	(
		[loc_id] => 1
		[loc_parent_fk] => 0
		[loc_name] => United Kingdom (EU)
	)
		[1] => Array
	(
		[loc_id] => 10
		[loc_parent_fk] => 0
		[loc_name] => United States
	)
)
[State] => Array
(
	[0] => Array
	(
		[loc_id] => 14
		[loc_parent_fk] => 10
		[loc_name] => California
	)
	[1] => Array
	(
		[loc_id] => 15
		[loc_parent_fk] => 10
		[loc_name] => Florida
	)
	[2] => Array
	(
		[loc_id] => 16
		[loc_parent_fk] => 10
		[loc_name] => New York
	)
	[3] => Array
	(
		[loc_id] => 17
		[loc_parent_fk] => 10
		[loc_name] => Pennsylvania
	)
)
[Post / Zip Code] => Array
(
	[0] => Array
	(
		[loc_id] => 18
		[loc_parent_fk] => 16
		[loc_name] => 10101
	)
	[1] => Array
	(
		[loc_id] => 19
		[loc_parent_fk] => 16
		[loc_name] => 10102
	)
)
)

locations_inline()

Gets all current active locations and formats them into an array.
This data can then be used to create a single HTML select menu listing all available locations.

Library and Requirements

Available via the lite, standard and admin libraries.

Requires all location database tables to be enabled.

Function Parameters
locations_inline(separator) Help
Name Data Type Required Default Description
separator string No ' > ' Sets a characters(s) to separate each location from each other.
How it Works

The function runs a SQL SELECT query to get all locations. The location data is then looped through and a string is built up grouping each child location with its parent location, and then with its grandparent location etc.

The finalised string is then added to a single dimensional array.

The returned array data can then be used to create a single HTML select menu listing all available locations.

Return Values

Failure:array (Empty) | An error message will be set if a required table/feature is disabled.

Success:array

Example
$this->flexi_cart->locations_inline();

// Click to show an example array produced.
Array
(
[0] => Array
(
	[loc_id] => 8
	[loc_name] => Australia
)
[1] => Array
(
	[loc_id] => 11
	[loc_name] => Australia > NSW
)
[2] => Array
(
	[loc_id] => 12
	[loc_name] => Australia > Queensland
)
[3] => Array
(
	[loc_id] => 13
	[loc_name] => Australia > Victoria
)
)

location_zones()

Gets all current active location zones and formats them into an array.

Library and Requirements

Available via the lite, standard and admin libraries.

Requires all location database tables to be enabled.

Function Parameters
location_zones(zone_type) Help
Name Data Type Required Default Description
zone_type string No FALSE Defines whether to return zones that have either shipping locations, tax locations or both types related to them.
How it Works

Locations can each be added to one shipping zone and one tax zone.

The function checks the 'zone_type' parameter whether to filter zones by either shipping zones, tax zones or both.
Valid 'zone_type' values are:

  • 'shipping' - returns only shipping zones.
  • 'tax' - returns only tax zones.
  • FALSE - returns all zones.

When the function applies the filter, it returns only zones that have locations in the defined 'zone_type' parameter.

Return Values

Failure:array (Empty) | An error message will be set if a required table/feature is disabled.

Success:array

Example
$this->flexi_cart->location_zones();

// Click to show an example array produced.
Array
(
[0] => Array
(
	[lzone_id] => 4
	[lzone_name] => Tax EU Zone
	[lzone_description] => Example Tax Zone for EU countries
)
[1] => Array
(
	[lzone_id] => 5
	[lzone_name] => Tax Non EU Zone
	[lzone_description] => Example Tax Zone for Non EU European countries
)
)
Copyright © 2024, Rob Hussey, All Rights Reserved.
flexi cart was designed and developed by