Geowidget v4 User's Guide (Old)

Owned by Wojciech Naras (Unlicensed)
Last updated: Nov 27, 2023 by Michał Machowski
5 min read


Note: Dear user the section "New Integration of Geowidget" shows the new way to integrate the Geowidget map, if you are looking for information about the previous possibilities to integrate Geowidget V4, go to the section "OLD version Integration of Geowidget"

New Integration of Geowidget


To use Geowidget v4, add the following lines to your page headers.

script async src="https://geowidget.easypack24.net/js/sdk-for-javascript.js"></script>
<link rel="stylesheet" href="https://geowidget.easypack24.net/css/easypack.css"/>

To initialize the map using the defined contexts, specify values for instance, context, and token in the parameters. Point selection is implemented as an event callback to the mapWidget function (example below).

<script type="text/javascript">           
    easyPack.init({
        instance: 'pl',
        context: "context name",
        token: "a token generated in the Parcel Locker Manager for API Points"
    });
    var map = easyPack.mapWidget('easypack-map', function(point) {
        console.log(point);
    });               
/script>
  
<div id="easypack-map"></div>

Parameter Description:

name
description
tokenParameter to which the PUBLIC token generated in parcel locker manager application should be provided (https://manager.paczkomaty.pl/  - tab MOJE KONTO > API > GEOWIDGET).
contextParameter specifying which functions/types the points displayed on the map should have (names of contexts and their description below in the table).
instanceInstance name parameter, for PL the value is 'pl'

Configuration options:

#
Description
Option
1Display pickup points for prepaid orderscontext: 'parcelCollect'
2Display collection points for cash on delivery orderscontext: 'parcelCollectPayment'
3Display of collection points for PWW orderscontext: 'parcelCollect247'
4Display of broadcast pointscontext: 'parcelSend'

Example: https://geowidget.easypack24.net/examples/multi-maps-contexts.html

OLD Version integration of Geowidget


Basic info

GEOv4 (also known as Geowidget v4) is a point locator and picker designed by Integer sp. z o.o. It's main goal is to show map of points with several types (for example machines), provide informations about this points and give possibility to integrate with clients external systems. GEOv4 is a widget-type software, it means that whole code and processing is held on Integer servers, external clients only attach link to this code and specify configuration that will be used on theirs systems.

Data source

API Points

Nomenclature basics: https://api-{locale}-points.easypack24.net/v1

InstanceEnvironmentEndpoint
PLProductionhttps://api-pl-points.easypack24.net/v1
UKProductionhttps://api-uk-points.easypack24.net/v1
ITProductionhttps://api-it-local-points.easypack24.net/v1/points

Responsive Web Design (RWD)



 

Integration

Basic integration (easypack.mapWdget())

Geowidget v4 can be easily integrated into any system or web page. Client web page should insert script in <head> tag:

<script async src="https://geowidget.easypack24.net/js/sdk-for-javascript.js"></script>
<link rel="stylesheet" href="https://geowidget.easypack24.net/css/easypack.css"/>

... then initialize widget by specifying DOM element ID (HTML) and configuration of their choice:

<script type="text/javascript">
	window.easyPackAsyncInit = function () {
		easyPack.init({});
		var map = easyPack.mapWidget('easypack-map', function(point){
			console.log(point);
		});
	};
</script>

<div id="easypack-map"></div>

Example 1 - https://geowidget.easypack24.net/examples/basic.html

Configuration options should be passed inside easyPack.init({}) object. It's not obligatory but client will definitely need to adjust it for himself.

For example:

easyPack.init({
	defaultLocale: 'pl',
	points: {
		types: ['parcel_locker']
	},
	map: {
		defaultLocation: [51.507351, -0.127758],
		initialTypes: ['parcel_locker']
	}
});

xample 2 - https://geowidget.easypack24.net/examples/basic-with-params.html

Parameters

Parameter nameDescriptionDefaults by instance
instance

Override default config by config prepared for instance.

Default: pl

Available: pl,uk,it


apiEndpoint

URL to API Points which will be connected to Geowidget

pl: https://api-pl-points.easypack24.net/v1
uk: https://api-uk-points.easypack24.net/v1
it: https://api-it-points.easypack24.net/v1
defaultLocale

Geowidget language that will be uses in front-end.

Available: pl,uk

pl: pl
uk: uk
locales

Languages that will be display as list in front layer. They can be dynamically changed.

pl: ['pl']
uk: ['uk'] 
mobileSize
Screen width below which mobile version is triggered.
768
langSelection
Determines if language selection bar should be displayed.
false
filters

Determines if filters (functions) bar should be displayed.

false
addressFormat

Visible format of address

'{street} {building_number} <br> {post_code} {city}'
listItemFormat
Visible format of address on list
[
	"<b>{name}</b>",
	"{address_details.street} {address_details.building_number}"
]
display
Enable/disable visible type filters and search bar
{
	showTypesFilters: true,
	showSearchBar: true,
}
mapType

Setup map type, available to use Open Street Map or Google Maps.

Available: osm, google

For 'google' option map.googleKey is required.

'osm'
searchType

Setup search type, available to use Open Street Map Nominatim or Google Maps Autocomplete.

Available: osm, google

For 'google' option map.googleKey is required.

'osm'
map
Setup map details.
{
	googleKey: '', // required to use Google Maps API
	useGeolocation: true,
	initialZoom: 13,
	detailsMinZoom: 15, // minimum zoom after marker click
	autocompleteZoom: 14,
	visiblePointsMinZoom: 13,
	defaultLocation: [52.229807, 21.011595],
    initialTypes: ['pop', 'parcel_locker'], // which type should be selected by default. Options: parcel_locker_only, parcel_locker, pop
}
points

Setup points details

Available functions:

parcel - points with functions send and collect 
parcel_send - points with functions send only
parcel_collect - points with functions collect only

{
	types: ['pop', 'parcel_locker'],  # Options: parcel_locker_only, parcel_locker, pop     
    allowedToolTips: ['pok', 'pop'],
    functions: []
}
customDetailsCallback

Allows to set custom callback for details action

Available: function(point){...}, false

false
customMapAndListInRow
Allow to change layout where list of point is below map. Points on list were paginated, number of point per page can be configured.
{
	enabled: false,
	itemsPerPage: 8
}
listItemFormat
Allows to change default layout of point information on points list.
[
	"<b>{name}</b>",
	"<strong>{address_details.street}</strong> {address_details.building_number}"
]
mobileFiltersAsCheckbox

Option set to false make filter option as radio in mobile, option true as checkobx.

true
paymentFilter

visible:false,

#zezwala na wyświetlenie filtra płatnosć w Paczkomat®

defaultEnabled: false,

#włączony filtr dla płatności w Paczkomat® już przy inicjalizacji

showOnlyWithPayment: false

#wymusza pokazywanie obiektów tylko z płatnością w Paczkomat®

False

Getting selected point data

If client wants to get point data that user selected on Geowidget, he can configure callback like this:

var map = easyPack.mapWidget('easypack-map', function(point) {
    alert(point.name);
});

Example 2 - https://geowidget.easypack24.net/examples/basic-with-params.html

Example 3 - https://geowidget.easypack24.net/examples/basic-with-collect-only.html

Modal Map (easyPack.modalMap())

It is possible to display Geowidget inside modal and then select point also:

easyPack.modalMap(function(point, modal) {
    modal.closeModal();
    console.log(point);
}, { width: 500, height: 600 });

Example 4 - https://geowidget.easypack24.net/examples/modal.html

Dropdown Widget (easyPack.dropdownWidget())

It is possible to display Geowidget as dropdown for select point.

 easyPack.dropdownWidget('easypack-widget', function(point) {
	console.log(point)
});

Example 5 - https://geowidget.easypack24.net/examples/dropdown-widget.html

Enable Google Maps

Defaults settings for display map and search place by address is setup to use Open Street Map.

Google API Key is required

https://developers.google.com/maps/documentation/javascript/get-api-key

with enabled interfaces:

  • Geocoding API
  • Geolocation API
  • Google Cloud APIs
  • Maps JavaScript API
  • Places API

Initialize Geowidget with params:

easyPack.init({
	mapType: 'google',
	searchType: 'google',
	map: {
		googleKey: 'your-google-api-key'
	}
});

Example 6 - https://geowidget.easypack24.net/examples/google.html


Functions of mapWidget

searchLockerPoint(pointName)

Function for search point by name and show it on map.

map.searchLockerPoint('PointName');

Example 7 - https://geowidget.easypack24.net/examples/search-locker-point.html

searchPlace(placeName)

Function fo search place by name and show it on map.

map.searchPlace('Wroclaw');

Example 8 - https://geowidget.easypack24.net/examples/search-place.html

Examples

Display points with different types


Params in init()

PARCEL_LOCKER_ONLY
In results we have points - physical machines only

points: {
  types: [‘parcel_locker_only']
},
map: {
  initialTypes: [‘parcel_locker_only']
}

POP
In results we have points with types 'pop' and 'super_pop'

points: {
  types: [‘pop']
},
map: {
  initialTypes: [‘pop']
}

PARCEL_LOCKER
In results we have points -physical machines and 'super_pop' type

points: {
   types: [‘parcel_locker']
},
map: {
  initialTypes: [‘parcel_locker']
}

PARCEL_LOCKER_SUPERPOP
In results we have points - 'super_pop' type only

points: {
  types: [‘parcel_locker_superpop']
},
map: {
  initialTypes: [‘parcel_locker_superpop']
}

PARCEL LOCKER + POP
In results we have points - physical machines, 'pop' and 'super_pop' types

points: {
  types: [‘parcel_locker', 'pop']
},
map: {
  initialTypes: [‘parcel_locker', 'pop']
}

PARCEL LOCKER + POP
In results we have points - physical machines, 'pop' and 'super_pop' types but selected is only 'parcel_locker' and 'super_pop' type

points: {
types: [‘parcel_locker, pop']
},
map: {
  initialTypes: [‘parcel_locker']
}

PARCEL LOCKER + POP
In results we have points - physical machines, 'pop' and 'super_pop' types but selected is only 'pop' and 'super_pop' type

points: {
  types: [‘parcel_locker, pop']
},
map: {
  initialTypes: [‘pop']
}


Example 1 - https://geowidget.easypack24.net/examples/basic.html - Basic integration

Example 2 - https://geowidget.easypack24.net/examples/basic-with-params.html - Basic integration with params and callback after point choose

Example 3 - https://geowidget.easypack24.net/examples/basic-with-collect-only.html - Basic integration with params and callback after point choose, points only with collect function

Example 4 - https://geowidget.easypack24.net/examples/modal.html - Open map as modal

Example 5 - https://geowidget.easypack24.net/examples/google.html - Enable Google Maps

Example 6 - https://geowidget.easypack24.net/examples/search-locker-point.html - Function searchLockerPoint()

Example 7 - https://geowidget.easypack24.net/examples/search-place.html - Function searchPlace()

Example 8 - https://geowidget.easypack24.net/examples/multi-maps.html - Open multi maps with different initial parameters

Example 9 - https://geowidget.easypack24.net/examples/payment-filter.html - Basic integration with payment filter