geo_labels

GeoLabels

GeoLabels is a rails engine that allows you to create entries that will be resolved to their geographic location so that they can be shown on a map.

The idea is to also create a hierarchical structure of labels and assign the lowest level applicable label to the contact entry.

Now interesting queries can be made based on this organization. Examples:

• Give me the good coffee places in the state of Texas
• Give me the Vietnamese food places in Miami

The geo-contacts and their labels can be managed in the engine's GUI, but also using a text format. This can be a useful, but also dangarous feature.

Installation

Add the engine to your rails app

Add this line to your application's Gemfile:

gem "geo_labels"

And then execute:

$ bundle
$ bundle exec rails db:migrate

Mount the engine to your routes

In your config/routes.rb file add:

  mount GeoLabels::Engine => '/geo-labels'

Add the authorizations

Authorization is handled by cancan. In your app/models/ability.rb file add the authorizations. This is a custom operation that you have to adjust to your needs. To allow all users full controll to the contracts add:

    can :manage, GeoLabels::Contact
    can :manage, GeoLabels::ContactLabel

If the Ability file does not yet exist, generate it using:

rails generate cancan:ability

Other languages (i18n)

To use for a lets say Spanish based website add rails-i18n to your Gemfile

gem 'rails-i18n'

And configure your application in config/application.rb to handle the languages:

  config.i18n.available_locales = %i[en es]
  config.i18n.default_locale = :en

Customization

The main page

The main page of this engine is the query page where the created structure can be queried.

The link home content

The default value for config/application.rb is:

  config.x.geo_labels.link_home_content = -> { '<i class="arrow left icon"></i> Back' }

To change for example the icon, see the options at the fomantic-ui site. Note that the value is a lambda to allow the use of for example I18n.

Contributing

There are many ways to contribute. Here some example steps that should work.

1. Fork the repository

Go to the original repository at https://gitlab.com/benja-2/geo\_labels and fork the project. Then git clone your code on your local computer.

If you are in the git repository directory you can tell your system to use the local code when actually the gitlab repository is specified for faster debugging. To achieve this type:

bundle config local.geo_labels .

2. Add your forked codebase to a project

To start from zero, create a new rails (> 7) project and add the geo_labels gem configured to use gitlab as a base:

rails new my_geo_labels_project
cd my_geo_labels_project

Then in the Gemfile

git_source(:gitlab) do |repo_name|
  repo_name = "#{repo_name}/#{repo_name}" unless repo_name.include?("/")
  "[e-mail]:#{repo_name}.git"
end

gem 'geo_labels', gitlab: '<your gitlab name>/geo_labels', branch: :master

TESTING

Testing against other databases

Since there are some more advanced queries in this gem and was discovered that mysql does not support the IN (SELECT ...) syntax, support for testing against multiple databases was added.

The default test (rspec spec) database is sqlite.

Test against a mysql database

To setup the mysql environment type (optional new window after the docker-compose command):

docker-compose test_mysql up
DATABASE_URL=mysql2://root:password@127.0.0.1:33062/test rails db:create
DATABASE_URL=mysql2://root:password@127.0.0.1:33062/test rails db:migrate

then run the specs against the mysql database:

DATABASE_URL=mysql2://root:password@127.0.0.1:33062/test rspec spec

Test against postgresql database

To setup the postgresql environment type (optional new window after the docker-compose command):

docker-compose test_postgresql up
DATABASE_URL=postgres://pguser:pgpassword@127.0.0.1:54321/test rails db:create
DATABASE_URL=postgres://pguser:pgpassword@127.0.0.1:54321/test rails db:migrate

then run the specs against the mysql database:

DATABASE_URL=postgres://pguser:pgpassword@127.0.0.1:54321/test rspec spec

CHANGELOG

The CHANGELOG can be found using CHANGELOG.md

License

The gem is available as open source under the terms of the MIT License.