popolo 0.0.1

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2012 Open North Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,41 @@
+# Popolo
+
+[![Build Status](https://secure.travis-ci.org/opennorth/popolo.png)](http://travis-ci.org/opennorth/popolo)
+[![Dependency Status](https://gemnasium.com/opennorth/popolo.png)](https://gemnasium.com/opennorth/popolo)
+[![Code Climate](https://codeclimate.com/badge.png)](https://codeclimate.com/github/opennorth/popolo)
+
+Popolo's goal is to make it easier for civic developers to create government transparency, monitoring and engagement websites.
+
+Popolo is a [Ruby on Rails engine](http://guides.rubyonrails.org/engines.html) that provides additional functionality to a [Ruby on Rails](http://rubyonrails.org/) application, so that developers can focus on what's special about the governments they want to monitor, instead of re-implementing features commonly found in open government websites. The core Popolo engine provides basic models, controllers and views for the objects found in all open government websites – people, organizations and the relationships between the two. Other engines provide additional functionality.
+
+In addition to being a Rails engine, Popolo is also a [data standard](http://popoloproject.com/data.html) and an [API specification](http://popoloproject.com/api.html).
+
+## Getting Started
+
+Popolo uses Mongoid to connect to MongoDB, which requires Rails 3 and supports only MRI 1.9.3 and HEAD, and JRuby 1.6.0+ in 1.9 mode.
+
+First, create your Rails application:
+
+    rails new myapp --skip-active-record
+
+Add the `popolo` gem to your `Gemfile`:
+
+    gem 'popolo'
+
+If you didn't run `rails new` with the `--skip-active-record` option, follow Mongoid's [installation instructions](http://mongoid.org/en/mongoid/docs/installation.html). Otherwise:
+
+    rails generate mongoid:config
+
+Finally, run the `popolo` generator:
+
+    rails generate popolo
+
+## Bugs? Questions?
+
+This engine's main repository is on GitHub: [http://github.com/opennorth/popolo](http://github.com/opennorth/popolo), where your contributions, forks, bug reports, feature requests, and feedback are greatly welcomed.
+
+## Acknowledgements
+
+This gem is developed by [Open North](http://www.opennorth.ca/) through a partnership with the [Participatory Politics Foundation](http://www.participatorypolitics.org/).
+
+Copyright (c) 2012 Open North Inc., released under the MIT license

data/Rakefile

@@ -0,0 +1,16 @@
+require 'bundler'
+Bundler::GemHelper.install_tasks
+
+require 'rspec/core/rake_task'
+RSpec::Core::RakeTask.new(:spec)
+
+task :default => :spec
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new
+rescue LoadError
+  task :yard do
+    abort 'YARD is not available. In order to run yard, you must: gem install yard'
+  end
+end

data/app/assets/javascripts/popolo/application.js

@@ -0,0 +1,13 @@
+// This is a manifest file that'll be compiled into application.js, which will include all the files
+// listed below.
+//
+// Any JavaScript/Coffee file within this directory, lib/assets/javascripts, vendor/assets/javascripts,
+// or vendor/assets/javascripts of plugins, if any, can be referenced here using a relative path.
+//
+// It's not advisable to add code directly here, but if you do, it'll appear at the bottom of the
+// the compiled file.
+//
+// WARNING: THE FIRST BLANK LINE MARKS THE END OF WHAT'S TO BE PROCESSED, ANY BLANK LINE SHOULD
+// GO AFTER THE REQUIRES BELOW.
+//
+//= require_tree .

data/app/assets/stylesheets/popolo/application.css

@@ -0,0 +1,13 @@
+/*
+ * This is a manifest file that'll be compiled into application.css, which will include all the files
+ * listed below.
+ *
+ * Any CSS and SCSS file within this directory, lib/assets/stylesheets, vendor/assets/stylesheets,
+ * or vendor/assets/stylesheets of plugins, if any, can be referenced here using a relative path.
+ *
+ * You're free to add application-wide styles to this file and they'll appear at the top of the
+ * compiled file, but it's generally better to create a new file per style scope.
+ *
+ *= require_self
+ *= require_tree .
+ */

data/app/controllers/popolo/areas_controller.rb

@@ -0,0 +1,48 @@
+module Popolo
+  class AreasController < PopoloController
+    inherit_resources
+    # inherited_resources assumes the routes are namespaced. If an engine is
+    # mounted at root, however, there will be no namespace.
+    self.resources_configuration[:self][:route_prefix] = nil
+
+    respond_to :html, :json
+    actions :index, :show
+    custom_actions collection: :nested_index, resource: :nested_show
+
+    before_filter :validate_path, only: [:nested_index, :nested_show]
+
+    def index
+      @areas = Area.roots
+      index!
+    end
+
+    def show
+      @area = Area.find_by_slug_or_id(params[:id])
+      show!
+    end
+
+    def nested_index
+      @areas = @area.children
+
+      nested_index! do |format|
+        format.html { render action: 'index'}
+      end
+    end
+
+    def nested_show
+      nested_show! do |format|
+        format.html { render action: 'show'}
+      end
+    end
+
+  protected
+
+    # @raises [Mongoid::Errors::DocumentNotFound] if a resource is improperly nested
+    def validate_path
+      parts = params[:path].split '/'
+      parts.each do |part|
+        @area = Area.find_by(parent_id: @area, slug: part)
+      end
+    end
+  end
+end

data/app/controllers/popolo/organizations_controller.rb

@@ -0,0 +1,48 @@
+module Popolo
+  class OrganizationsController < PopoloController
+    inherit_resources
+    # inherited_resources assumes the routes are namespaced. If an engine is
+    # mounted at root, however, there will be no namespace.
+    self.resources_configuration[:self][:route_prefix] = nil
+
+    respond_to :html, :json
+    actions :index, :show
+    custom_actions collection: :nested_index, resource: :nested_show
+
+    before_filter :validate_path, only: [:nested_index, :nested_show]
+
+    def index
+      @organizations = Organization.roots
+      index!
+    end
+
+    def show
+      @organization = Organization.find_by_slug_or_id(params[:id])
+      show!
+    end
+
+    def nested_index
+      @organizations = @organization.children
+
+      nested_index! do |format|
+        format.html { render action: 'index'}
+      end
+    end
+
+    def nested_show
+      nested_show! do |format|
+        format.html { render action: 'show'}
+      end
+    end
+
+  protected
+
+    # @raises [Mongoid::Errors::DocumentNotFound] if a resource is improperly nested
+    def validate_path
+      parts = params[:path].split '/'
+      parts.each do |part|
+        @organization = Organization.find_by(parent_id: @organization, slug: part)
+      end
+    end
+  end
+end

data/app/controllers/popolo/people_controller.rb

@@ -0,0 +1,12 @@
+module Popolo
+  class PeopleController < PopoloController
+    inherit_resources
+    respond_to :html, :json
+    actions :index, :show
+
+    def show
+      @person = Person.find_by_slug_or_id(params[:id])
+      show!
+    end
+  end
+end

data/app/controllers/popolo/posts_controller.rb

@@ -0,0 +1,12 @@
+module Popolo
+  class PostsController < PopoloController
+    inherit_resources
+    respond_to :html, :json
+    actions :index, :show
+
+    def show
+      @post = Post.find_by_slug_or_id(params[:id])
+      show!
+    end
+  end
+end

data/app/controllers/popolo_controller.rb

@@ -0,0 +1,3 @@
+class PopoloController < Popolo.parent_controller.constantize
+  helper PopoloHelper
+end

data/app/helpers/popolo_helper.rb

@@ -0,0 +1,10 @@
+module PopoloHelper
+  # @note inherited_resources sets incorrect arguments for glob routes.
+  # @see https://github.com/josevalim/inherited_resources/blob/master/lib/inherited_resources/url_helpers.rb
+  def nested_resources_path(*args)
+    send("nested_#{resource_collection_name}_path", *args)
+  end
+  def nested_resource_path(*args)
+    send("nested_#{resource_instance_name}_path", *args)
+  end
+end

data/app/models/popolo/address.rb

@@ -0,0 +1,27 @@
+module Popolo
+  # A physical location or a mail delivery point.
+  class Address
+    include Mongoid::Document
+
+    embedded_in :addressable, polymorphic: true
+
+    # The address' type, e.g. 'capitol'.
+    field :type, type: String
+    # The postal address.
+    field :address, type: String
+    # A voice telephone number.
+    field :voice, type: Integer
+    # A facsimile telephone number.
+    field :fax, type: Integer
+    # A mobile telephone number.
+    field :cell, type: Integer
+    # A toll-free telephone number.
+    field :tollfree, type: Integer
+    # A video conferencing telephone number.
+    field :video, type: Integer
+    # A paging device telephone number.
+    field :pager, type: Integer
+    # A telecommunication device for people with hearing or speech difficulties.
+    field :textphone, type: Integer
+  end
+end

data/app/models/popolo/area.rb

@@ -0,0 +1,25 @@
+module Popolo
+  # A bounded area, like an administrative boundary.
+  #
+  # @note There is an upper limit to the number of administrative levels;
+  #   however, there is little agreement as to what those levels are. Therefore,
+  #   instead of having a different model for each administrative level – which
+  #   would have advantages – we use a flexible tree structure.
+  class Area
+    include Mongoid::Document
+    include Mongoid::Tree
+
+    include Popolo::Sluggable
+    index({slug: 1, parent_id: 1}, unique: true)
+
+    # Memberships related to the area, e.g. officials.
+    has_many :memberships, class_name: 'Popolo::Membership'
+    # Organizations related to the area, e.g. governments.
+    has_many :organizations, class_name: 'Popolo::Organization'
+    # Posts related to the area, e.g. officials.
+    has_many :posts, class_name: 'Popolo::Post'
+
+    # The area's category.
+    field :classification, type: String
+  end
+end

data/app/models/popolo/event.rb

@@ -0,0 +1,46 @@
+module Popolo
+  # An occurrence, e.g. an action mentioning or performed by an agent.
+  #
+  # Turtle document: @todo move into popoloproject.com
+  #
+  #     <http://example.com/events/57cc67093475061e3d95369d.ttl>
+  #       a cnt:ContentAsText;
+  #       cnt:characterEncoding "UTF-8";
+  #       cnt:chars "Lorem ipsum dolor sit amet, consectetur adipiscing elit. ...";
+  #       dcterms:format "text/plain";
+  #       dcterms:isFormatOf <http://example.org/news/123.html>;
+  #       dcterms:issued "2012-01-01T00:00:00Z"^^xsd:dateTime;
+  #       dcterms:identifier "57cc67093475061e3d95369d";
+  #       dcterms:created "2012-01-01T00:00:00Z"^^xsd:dateTime;
+  #       dcterms:modified "2012-01-01T00:00:00Z"^^xsd:dateTime .
+  #
+  # @see http://www.w3.org/TR/Content-in-RDF10/
+  # @see http://dublincore.org/documents/dcmi-terms/
+  class Event
+    include Mongoid::Document
+    include Mongoid::Timestamps
+
+    # The identifier of the source of information for the event.
+    field :source, type: String
+    # The URL to which the event may be attributed.
+    field :url, type: String
+    # The event's content.
+    field :body, type: String
+    # The time of the event or of its publication.
+    field :issued_at, type: Time
+    # The records related to the event.
+    field :related, type: Hash
+    # Any additional information about the event.
+    field :extra, type: Hash
+
+    # @note It's not possible to do a many-to-many polymorphic relation, so we
+    #   must list every index individually.
+
+    index 'related.area' => 1, source: 1, issued_at: -1
+    index 'related.membership' => 1, source: 1, issued_at: -1
+    index 'related.organization' => 1, source: 1, issued_at: -1
+    index 'related.post' => 1, source: 1, issued_at: -1
+
+    validates_presence_of :source, :url, :body, :issued_at
+  end
+end

data/app/models/popolo/identifier.rb

@@ -0,0 +1,15 @@
+module Popolo
+  # An issued identifier.
+  class Identifier
+    include Mongoid::Document
+
+    embedded_in :organization, class_name: 'Popolo::Organization'
+
+    # An issued identifier, e.g. a DUNS number.
+    field :identifier, type: String
+    # An identifier scheme, e.g. DUNS.
+    field :scheme, type: String
+
+    validates_presence_of :identifier
+  end
+end

data/app/models/popolo/link.rb

@@ -0,0 +1,16 @@
+module Popolo
+  # A URL for a document about a person.
+  class Link
+    include Mongoid::Document
+
+    embedded_in :person, class_name: 'Popolo::Person'
+
+    # A URL for a document about a person.
+    field :url, type: String
+    # A note, e.g. 'Wikipedia page'.
+    field :note, type: String
+
+    validates_presence_of :url
+    # @note Add URL validation to match JSON Schema?
+  end
+end

data/app/models/popolo/membership.rb

@@ -0,0 +1,25 @@
+module Popolo
+  # A relationship between a person and an organization.
+  class Membership
+    include Mongoid::Document
+
+    # An area related to the membership, e.g. an electoral riding.
+    belongs_to :area, index: true, class_name: 'Popolo::Area'
+    # The person who is a party to the relationship.
+    belongs_to :organization, index: true, class_name: 'Popolo::Organization'
+    # The organization that is a party to the relationship.
+    belongs_to :person, index: true, class_name: 'Popolo::Person'
+
+    # The role that the person fulfills in the organization. Roles should
+    # preferably belong to a controlled vocabulary.
+    field :role, type: String
+    # The date on which the relationship began.
+    field :start_date, type: String
+    # The date on which the relationship ended.
+    field :end_date, type: String
+
+    validates_presence_of :organization_id, :person_id
+    validates_format_of :start_date, with: /\A\d{4}(-\d{2}){0,2}\z/, allow_blank: true
+    validates_format_of :end_date, with: /\A\d{4}(-\d{2}){0,2}\z/, allow_blank: true
+  end
+end

data/app/models/popolo/organization.rb

@@ -0,0 +1,32 @@
+module Popolo
+  # A group with a common purpose or reason for existence that goes beyond the
+  # set of people belonging to it, e.g. a political structure.
+  class Organization
+    include Mongoid::Document
+    include Mongoid::Tree
+
+    include Popolo::Sluggable
+    index({slug: 1, parent_id: 1}, unique: true)
+
+    # An area related to the organization, e.g. a region or country.
+    belongs_to :area, index: true, class_name: 'Popolo::Area'
+    # The relationships to which the organization is a party.
+    has_many :memberships, class_name: 'Popolo::Membership', dependent: :destroy
+    # The posts within the organization.
+    has_many :posts, class_name: 'Popolo::Post', dependent: :destroy
+    # The organization's alternate or former names.
+    embeds_many :other_names, as: :nameable, class_name: 'Popolo::OtherName'
+    # The organization's issued identifiers.
+    embeds_many :identifiers, class_name: 'Popolo::Identifier'
+
+    # The organization's category.
+    field :classification, type: String
+    # The organization's date of founding in ISO 8601:2004 format.
+    field :founding_date, type: String
+    # The organization's date of dissolution in ISO 8601:2004 format.
+    field :dissolution_date, type: String
+
+    validates_format_of :founding_date, with: /\A\d{4}(-\d{2}){0,2}\z/, allow_blank: true
+    validates_format_of :dissolution_date, with: /\A\d{4}(-\d{2}){0,2}\z/, allow_blank: true
+  end
+end

data/app/models/popolo/other_name.rb

@@ -0,0 +1,21 @@
+module Popolo
+  # An alternate or former name.
+  class OtherName
+    include Mongoid::Document
+
+    embedded_in :nameable, polymorphic: true
+
+    # An alternate or former name.
+    field :name, type: String
+    # The date on which the name was adopted.
+    field :start_date, type: String
+    # The date on which the name was abandoned.
+    field :end_date, type: String
+    # A note, e.g. "Birth name".
+    field :note, type: String
+
+    validates_presence_of :name
+    validates_format_of :start_date, with: /\A\d{4}(-\d{2}){0,2}\z/, allow_blank: true
+    validates_format_of :end_date, with: /\A\d{4}(-\d{2}){0,2}\z/, allow_blank: true
+  end
+end

data/app/models/popolo/person.rb

@@ -0,0 +1,49 @@
+module Popolo
+  # A real person, alive or dead.
+  class Person
+    include Mongoid::Document
+
+    include Popolo::Sluggable
+    index({slug: 1}, unique: true)
+
+    # The relationships to which the person is a party.
+    has_many :memberships, class_name: 'Popolo::Membership'
+    # The posts held by the person.
+    has_many :posts, class_name: 'Popolo::Post'
+    # The person's alternate or former names.
+    embeds_many :other_names, as: :nameable, class_name: 'Popolo::OtherName'
+    # Links to pages about this person, e.g. Wikipedia, or to accounts this
+    # person has on other websites, e.g. Twitter.
+    embeds_many :links, class_name: 'Popolo::Link'
+
+    # The person's family name.
+    field :family_name, type: String
+    # The person's given name.
+    field :given_name, type: String
+    # An additional name, e.g. a middle name.
+    field :additional_name, type: String
+    # An honorific prefix before the person's name, e.g. "Dr.".
+    field :honorific_prefix, type: String
+    # An honorific suffix after the person's name, e.g. "Jr.".
+    field :honorific_suffix, type: String
+    # The person's email address.
+    field :email, type: String
+    # The person's gender, e.g. "male", "female" or another value.
+    field :gender, type: String
+    # The person's date of birth in ISO 8601:2004 format.
+    field :birth_date, type: String
+    # The person's date of death in ISO 8601:2004 format.
+    field :death_date, type: String
+    # The URL of the person's head shot.
+    field :image, type: String
+    # The person's one-line biography.
+    field :summary, type: String
+    # The person's extended biography.
+    field :biography, type: String
+
+    # @note Add email address validation to match JSON Schema?
+    # @note Add URL validation to match JSON Schema?
+    validates_format_of :birth_date, with: /\A\d{4}(-\d{2}){0,2}\z/, allow_blank: true
+    validates_format_of :death_date, with: /\A\d{4}(-\d{2}){0,2}\z/, allow_blank: true
+  end
+end

data/app/models/popolo/post.rb

@@ -0,0 +1,25 @@
+module Popolo
+  # A position in an organization that exists independently of the person
+  # holding it.
+  class Post
+    include Mongoid::Document
+
+    def self.slug_source
+      :role
+    end
+
+    include Popolo::Sluggable
+    index({slug: 1}, unique: true)
+
+    # An area related to the post, e.g. an electoral riding.
+    belongs_to :area, index: true, class_name: 'Popolo::Area'
+    # The organization in which the post exists.
+    belongs_to :organization, index: true, class_name: 'Popolo::Organization'
+    # The person holding the post.
+    belongs_to :person, index: true, class_name: 'Popolo::Person'
+    # The address at which the post is based.
+    embeds_many :addresses, as: :addressable, class_name: 'Popolo::Address'
+
+    validates_presence_of :organization_id
+  end
+end

data/app/models/popolo/source.rb

@@ -0,0 +1,29 @@
+module Popolo
+  # A source of information.
+  #
+  # Turtle document: @todo move into popoloproject.com
+  #
+  #     <http://example.com/sources/67cc67093475061e3d95369d.ttl>
+  #       rdfs:label "news.google.com";
+  #       dcterms:identifier "67cc67093475061e3d95369d";
+  #       dcterms:modified "2012-01-01T00:00:00Z"^^xsd:dateTime .
+  #
+  # @see http://dublincore.org/documents/dcmi-terms/
+  # @todo Add the ETag to the Turtle document.
+  class Source
+    include Mongoid::Document
+
+    embedded_in :sourceable, polymorphic: true
+
+    # A human-readable unique identifier for the source, e.g. "news.google.com".
+    field :name, type: String
+    # The source's ETag.
+    field :etag, type: String
+    # The source's last modified timestamp.
+    field :last_modified, type: Time
+    # Any additional information about the source.
+    field :extra, type: Hash
+
+    validates_presence_of :name, :last_modified
+  end
+end

data/app/views/popolo/areas/index.html.erb

@@ -0,0 +1 @@
+<%= render partial: 'popolo/areas_or_organizations/index', locals: {collection: @areas, object: @area} %>

data/app/views/popolo/areas/show.html.erb

@@ -0,0 +1 @@
+<%= render partial: 'popolo/areas_or_organizations/show', locals: {object: @area} %>

data/app/views/popolo/areas_or_organizations/_index.html.erb

@@ -0,0 +1,31 @@
+<% if object %>
+<nav>
+  <ul class="breadcrumb">
+    <li><%= link_to resource_collection_name.capitalize, collection_path %> <span class="divider">/</span></li>
+  <% ancestors = object.ancestors %>
+  <% ancestors.each_with_index do |ancestor,index| %>
+    <li>
+      <%= link_to ancestor.name, nested_resources_path(ancestors[0..index]) %>
+      <span class="divider">/</span>
+    </li>
+  <% end %>
+    <li class="active"><%= object.name %></li>
+  </ul>
+</nav>
+<% end %>
+
+<% unless collection.empty? %>
+  <% groups = collection.asc(:sort_name).group_by(&:classification) %>
+  <% groups.each do |classification,documents| %>
+<section>
+  <header>
+    <h1><%= t(classification, scope: [:popolo, resource_collection_name, :classifications]) %></h1>
+  </header>
+  <ul>
+    <% documents.each do |document| %>
+    <li><%= link_to document.name, nested_resources_path([object, document].compact) %></li>
+    <% end %>
+  </ul>
+</section>
+  <% end %>
+<% end %>

data/app/views/popolo/areas_or_organizations/_show.html.erb

@@ -0,0 +1,30 @@
+<nav>
+  <ul class="breadcrumb">
+    <li><%= link_to resource_collection_name.capitalize, collection_path %> <span class="divider">/</span></li>
+<% ancestors = object.ancestors %>
+<% ancestors.each_with_index do |ancestor,index| %>
+    <li>
+      <%= link_to ancestor.name, nested_resource_path(ancestors[0..index]) %>
+      <span class="divider">/</span>
+    </li>
+<% end %>
+    <li class="active"><%= object.name %></li>
+  </ul>
+</nav>
+
+<% collection = object.children %>
+<% unless collection.empty? %>
+  <% groups = collection.asc(:sort_name).group_by(&:classification) %>
+  <% groups.each do |classification,documents| %>
+<section>
+  <header>
+    <h1><%= t(classification, scope: [:popolo, resource_collection_name, :classifications]) %></h1>
+  </header>
+  <ul>
+    <% documents.each do |document| %>
+    <li><%= link_to document.name, nested_resource_path([object, document]) %></li>
+    <% end %>
+  </ul>
+</section>
+  <% end %>
+<% end %>

data/app/views/popolo/organizations/index.html.erb

@@ -0,0 +1 @@
+<%= render partial: 'popolo/areas_or_organizations/index', locals: {collection: @organizations, object: @organization} %>

data/app/views/popolo/organizations/show.html.erb

@@ -0,0 +1 @@
+<%= render partial: 'popolo/areas_or_organizations/show', locals: {object: @organization} %>