locomotivemtl/charcoal-geolocation

Charcoal geolocation tools

dev-master / 0.1.x-dev 2022-04-07 21:23 UTC

Requires

• php: >=5.6.0 || >=7.0
• locomotivemtl/charcoal-property: ~0.5

Requires (Dev)

• php-coveralls/php-coveralls: ^2.0
• phpunit/phpunit: ^5.7 || ^6.5
• seld/jsonlint: ^1.7
• squizlabs/php_codesniffer: ^3.0

MIT

• Locomotive

• framework
• geolocation
• map
• charcoal
• locomotive

README

A Charcoal service provider my cool feature.

Table of Contents

• Installation
  • Dependencies
• Configuration
• Usage
• Development
  • API Documentation
  • Development Dependencies
  • Coding Style
• Credits
• License

Installation

The preferred (and only supported) method is with Composer:

$ composer require locomotivemtl/charcoal-geolocation

Dependencies

• charcoal-core
• charcoal-admin

Required

• PHP 5.6+: PHP 7 is recommended.

Configuration

Add the views and the metadata paths to the config file.

"metadata": {
       "paths": [
           "...",
           "vendor/locomotivemtl/charcoal-geolocation/metadata/"
       ]
   },
   "view": {
       "paths": [
           "...",
           "vendor/locomotivemtl/charcoal-geolocation/views/"
       ]
   }

Usage

The module is basically a collection of properties, inputs and widgets. All you have to do is use them.

• GeolocationCollection widget implementation example for an object's dashboard :

"map": {
    "type": "charcoal/geolocation/widget/geolocation-collection",
    "geometry_property": "geometry",
    "infobox_template": "project/widget/example-infobox",
    "priority": 10
}

To use the properties provided by this Module, you have to refer to them with their full PHP path from the object metadata : Charcoal\\Geolocation\\Property\\MapStructureProperty Charcoal\\Geolocation\\Property\\PointProperty Charcoal\\Geolocation\\Property\\PolylineProperty Charcoal\\Geolocation\\Property\\PolygonProperty

Widgets

The following base widgets are available to build the various admin templates:

• GeolocationCollection
  • Widget That can show a collection of object that has a property that implements GeolocationInterface
  • Specify the property ident to use
  • Specify a template to show the

Property Inputs

The following property inputs are available to build forms in the admin module:

• MapStructure

  • A specialized widget to add and edit geolocation data on a map.
    • Supported geolocation types:
      • Point
      • Polyline
      • Polygon
  • Cannot be multiple
  • Requires google-map.
  • Requires gmap.
  • Extends StructureProperty from charcoal-property.
  • Implements GeolocationInterface.

• AbstractGeolocation

  • Base property for:
    • Point
    • Polyline
    • Polygon
  • Extends AbstractProperty from charcoal-property.
  • Implements GeolocationInterface.

• Point

  • A specialized widget to add and edit Point geolocation data on a map.
  • Requires google-map.
  • Requires gmap.

• Polyline

  • A specialized widget to add and edit Polyline geolocation data on a map.
  • Requires google-map.
  • Requires gmap.

• Polygon

  • A specialized widget to add and edit Polygon geolocation data on a map.
  • Requires google-map.
  • Requires gmap.

Development

To install the development environment:

$ composer install

To run the scripts (phplint, phpcs, and phpunit):

$ composer test

API Documentation

• The auto-generated phpDocumentor API documentation is available at:
  https://locomotivemtl.github.io/charcoal-geolocation/docs/master/
• The auto-generated apigen API documentation is available at:
  https://codedoc.pub/locomotivemtl/charcoal-geolocation/master/

Development Dependencies

• [php-coveralls/php-coveralls][phpcov]
• [phpunit/phpunit][phpunit]
• [squizlabs/php_codesniffer][phpcs]
• [seld/jsonlint][jsonlint]

Coding Style

The charcoal-geolocation module follows the Charcoal coding-style:

• PSR-1
• PSR-2
• PSR-4, autoloading is therefore provided by Composer.
• phpDocumentor comments.
• phpcs.xml.dist and .editorconfig for coding standards.

Coding style validation / enforcement can be performed with composer phpcs. An auto-fixer is also available with composer phpcbf.

Credits

• Locomotive
• Joel Alphonso [e-mail]

License

Charcoal is licensed under the MIT license. See LICENSE for details.