Ubigeo Rails
¿Qué es Ubigeo?
Bueno, en cierto país donde nací(Perú), el ubigeo es un número de identificación que identifica a un departamento, provincia o distrito del país, algo así:
- Departamento de Lima: 15
- Provincia de Lima: 1501
- Distrito de Lima: 150101
Esta gema es una abstracción de dos acciones relacionadas a este concepto, que son:
- Endpoints de json que nos dan las provincias de una departamento.
- Una librería de Javascript que abstrae la idea de selectores dependientes que es el widget más usado para ingresar información de ubigeo en internet.
Asunciones
- Usas Formtastic (posiblemente a futuro se haga algo para SimpleForm o alguna opción más agnóstica como un helper que funcione como un widget)
Uso
Instalación
Agrega la gema al Gemfile
gem 'ubigeo_rails'
Luego, instala la gema, lo que creará una ruta y un inicializador.
rails g ubigeo_rails:install
Agrega la siguiente librería a tu manifiesto (app/assets/application.js
):
//= require ubigeo
Llena el Ubigeo
Si ya tienes una tabla de Ubigeo
Edita el inicializador (en app/config/initializers/ubigeo_rails.rb) con datos como los siguientes:
UbigeoRails.config do |config|
config.table_name 'ubigeo_ubigeo'
config.db_connection { "general_#{Rails.env}" }
end
La razón principal de estas opciones es para poder conectar a bases de datos ya existentes.
Si no la tienes
Si no tienes una bd ya existente, puedes llenar la base de datos de ubigeo en dos pasos:
Crear la tabla:
rails g migration create_ubigeos name:string parent_id:integer
rake db:migrate
Generar los seeds (la información):
rails g ubigeo_rails:seeds
El primero creará una migración y el segundo agregará código al archivo seeds.rb
que permitirá generar la data usando el estándar:
rake db:seed
Crea una relación
Para asociar el modelo de Ubigeo a otro, debes especificar la clase exacta de Ubigeo, que es UbigeoRails::Ubigeo
. Por ejemplo, si queremos asociarla a un usuario:
class User << ActiveRecord::Base
belongs_to :ubigeo, class_name: "UbigeoRails::Ubigeo"
end
Úsala en un formulario
Puedes usarlo el plugin como cualquier input de Formtastic. Sólo debes colocar el valor :ubigeo
en la opción :as
:
# Imaginemos un formulario para un usario
= semantic_form_for @user do |f|
= f.input :ubigeo_id, as: :ubigeo, prompt: ["selecciona un departamento", "selecciona una provincia", "selecciona un distrito"]
La única opción por el momento es prompt
, que te permitirá elegir los 3 elementos vacíos que puede haber sobre cada uno de los 3 selects que conforman el plugin. De no necesitar este prompt, simplemente no lo colocamos.
Extras
La Ruta
Por defecto, la engine (esto es una rails engine) será montada en /ubigeo
. Puedes revisar el código generado en config/routes.rb
para cambiar el punto de montaje.
El Modelo
También puedes usar los siguientes métodos de la clase Ubigeo:
- #has_department?: Si el código de ubigeo contiene o no la información de un departamento
- #has_province?: Si el código de ubigeo contiene o no la información de una provincia
- #has_district?: Si el código de ubigeo contiene o no la información de un distrito
- .with_parent(id): Devuelve los hijos de un ubigeo. Por ejemplo, los distritos de Lima o las provincias de Arequipa.