wontomedia 0.0.1

data/app/controllers/items_controller.rb

@@ -0,0 +1,365 @@
+#--
+# WontoMedia - a wontology web application
+# Copyright (C) 2010 - Glen E. Ivey
+#    www.wontology.com
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License version
+# 3 as published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program in the file COPYING and/or LICENSE.  If not,
+# see <http://www.gnu.org/licenses/>.
+#++
+
+
+#### I've got no idea why this 'require' is necessary.  Without it, all
+# the unit tests pass, but the ItemHelper.nouns call below fails when
+# run in production.  Even more odd, if run in 'development' (so that
+# each Ruby file is reloaded at each request, this 'require' only has
+# to be present for the _first_ request serviced after the server
+# starts.  It can be deleted, this file reloaded, and then ItemHelper
+# references will work normally.  Go figure. -- gei 2010/2/24
+require Rails.root.join( 'lib', 'helpers', 'item_helper')
+require 'yaml'
+
+# See also the matching model Item
+class ItemsController < ApplicationController
+  # GET /
+  def home
+    @nouns = ItemHelper.nouns
+    render :layout => "home"
+  end
+
+  # GET /items
+  #
+  # Note that +index+ is capable of rendering in multiple
+  # formats. <tt>/items</tt> and <tt>/items.html</tt> yield a
+  # human-readable page in HTML markup.  <tt>/items.yaml</tt> renders
+  # all fields from all Items in the database as YAML-format text,
+  # with no additional prose or links intended for users.
+  def index
+    @items = Item.all.reverse
+    @not_in_use_hash = {}
+    @items.each do |item|
+      @not_in_use_hash[item.id] =
+        Connection.all( :conditions =>
+          [ "subject_id = ? OR predicate_id = ? OR obj_id = ?",
+            item.id, item.id, item.id ]).
+          empty?
+    end
+
+    respond_to do |wants|
+      wants.html
+      wants.yaml do
+        render :text =>
+          @items.reject { |item|
+            (item.flags & Item::DATA_IS_UNALTERABLE) != 0 }.
+          to_yaml
+      end
+    end
+  end
+
+  # GET /items/new
+  def new
+    @this_is_non_information_page = true
+    @item = Item.new
+  end
+
+  # GET /items/new-pop
+  #
+  # This operation is intended to provide a version of
+  # <tt>/items/new</tt> suitable for Ajax fetching fromm and display
+  # in a pop-up <tt><div></tt> in an already-rendered page.  Correct
+  # operation of the page fragment rendered by this action depends on
+  # the surrounding page having already loaded the form's JavaScript
+  # and style dependencies.  Implementing this behavior depends on the
+  # <tt>popup_flag</tt> field passed between Items +actions+ and
+  # +views+; see their source for additional details.
+  def newpop
+    @item = Item.new
+    @type = params[:type]
+    render :layout => "popup"
+  end
+
+  # POST /items
+  def create
+    type_string = params[:item][:sti_type]
+    params[:item].delete :sti_type # don't mass-assign protected blah, blah
+    @item = ItemHelper.new_typed_item(type_string, params[:item])
+    @popup_flag = true if params[:popup_flag]
+
+    if @item.nil?
+      flash.now[:error] =
+'Could not create. Item must have a type of either "Category" or "Individual".'
+      @item = Item.new(params[:item]) # keep info already entered
+      @item.sti_type = type_string
+      @this_is_non_information_page = true
+      render :action => (@popup_flag ? "newpop" : "new" )
+    elsif @item.name =~ /[:.]/ || !@item.save
+      @item.errors.add :name, "cannot contain a period (.) or a colon (:)."
+      @this_is_non_information_page = true
+      render :action => (@popup_flag ? "newpop" : "new" )
+    else
+      if @popup_flag
+        @connection_list = []; @item_hash = {}; @connection_hash = {}
+        flash.now[:notice] = 'Item was successfully created.'
+        render :action => "show", :layout => "popup"
+      else
+        flash[:notice] = 'Item was successfully created.'
+        redirect_to item_path(@item)
+      end
+    end
+  end
+
+  # GET /items/1
+  #
+  # Note that +show+ is capable of rendering in multiple
+  # formats. <tt>/items/1</tt> and <tt>/items/1.html</tt> yield a
+  # human-readable page in HTML markup.  <tt>/items/1.json</tt>
+  # renders all fields from the specified Item as JSON-format text,
+  # with no additional prose or links intended for users.  In the JSON
+  # case, only information about the specific Item requested is
+  # returned.  When a full web page is generated, information is
+  # included about all other Items which are involved in Connections
+  # that directly reference the requested Item.
+  def show
+    begin
+      @item = Item.find(params[:id])
+    rescue
+      render :file => "#{RAILS_ROOT}/public/404.html", :status => 404
+      return
+    end
+
+    if request.format.json?
+      # huge kludge for testability.  Need to ensure that we don't respond
+      # so quickly (e.g., in setups where client and server are on the same
+      # system) that the JavaScript and acceptance tests can't see the
+      # "request in progress" state of the page/system.
+      if (RAILS_ENV == 'test')
+        Kernel.sleep(0.75)
+      end
+
+      render :json => @item
+      return
+    end
+
+    used_as_subj = Connection.all( :conditions =>
+      [ "subject_id = ?", @item.id ])
+    used_as_pred = Connection.all( :conditions =>
+      [ "predicate_id = ?", @item.id ])
+    used_as_obj  = Connection.all( :conditions =>
+      [ "obj_id = ?", @item.id ])
+
+    @item_hash = {}
+    @connection_hash = {}
+    [ used_as_subj, used_as_pred, used_as_obj ].each do |connection_array|
+      connection_array.each do |connection|
+        unless @connection_hash.has_key? connection.id
+          @connection_hash[connection.id] = connection
+          [ connection.subject, connection.predicate, connection.obj ].
+            each do |item|
+            unless @item_hash.has_key? item.id
+              @item_hash[item.id] = item
+            end
+          end
+        end
+      end
+    end
+
+      # now that we've got all the connections to display, order and group them
+    # @connection_list should be an array of arrays, each internal array is
+    # a "section" of the display page, containing .id's of connections
+    @connection_list = []
+
+    value_id = Item.find_by_name("value_relationship").id
+    spo_id   = Item.find_by_name("sub_property_of").id
+
+    # first group, all connections *from* this item with value-type predicates
+    connections = []
+    connections_to_delete = []
+    used_as_subj.each do |connection|
+      if TrippleNavigation.check_properties(
+          :does => connection.predicate_id, :via => spo_id,
+          :inherit_from => value_id )
+        connections << connection.id
+        connections_to_delete << connection
+      end
+    end
+    used_as_subj -= connections_to_delete # done incrementally, breaks iterator
+    unless connections.empty?
+      @connection_list << connections
+    end
+
+
+    # next N groups: 1 group for connections *from* this item with >1 of
+    #   same pred.
+    #figure out which predicates occur >1, how many they occur, sort & group
+    pred_counts = {}
+    connection_using_pred = {}
+    used_as_subj.each do |connection|
+      if pred_counts[connection.predicate_id].nil?
+        pred_counts[connection.predicate_id] = 1
+      else
+        pred_counts[connection.predicate_id] += 1
+      end
+      connection_using_pred[connection.predicate_id] = connection.id
+    end
+    subj_connections = pred_counts.keys
+    subj_connections.sort! { |a,b| pred_counts[b] <=> pred_counts[a] }
+    array_of_singles = []
+    subj_connections.each do |predicate_id|
+      if pred_counts[predicate_id] > 1
+        connections = []
+        used_as_subj.each do |connection|
+            # lazy, more hashes would eliminate rescan
+          if connection.predicate_id == predicate_id
+            connections << connection.id
+          end
+        end
+        unless connections.empty?
+          @connection_list << connections
+        end
+      else
+        array_of_singles << connection_using_pred[predicate_id]
+      end
+    end
+
+    # last group of connections *from* current item:
+    #   all connections w/ used-once pred's
+    unless array_of_singles.empty?
+      @connection_list << array_of_singles
+    end
+
+
+    obj_connections = used_as_obj.map { |connection| connection.id }
+    obj_connections.sort! do |a,b|
+      if @connection_hash[a].predicate_id == @connection_hash[b].predicate_id
+        @connection_hash[a].obj_id <=> @connection_hash[b].obj_id
+      else
+        @connection_hash[a].predicate_id <=> @connection_hash[b].predicate_id
+      end
+    end
+    unless obj_connections.empty?
+      @connection_list << obj_connections
+    end
+
+
+    pred_connections = used_as_pred.map { |connection| connection.id }
+    unless pred_connections.empty?
+      @connection_list << pred_connections
+    end
+  end
+
+  # GET /items/1/edit
+  def edit
+    begin
+      @this_is_non_information_page = true
+      @item = Item.find(params[:id])
+    rescue
+      render :file => "#{RAILS_ROOT}/public/404.html", :status => 404
+      return
+    end
+  end
+
+  # PUT /items/1
+  def update
+    # we want to be agnostic WRT processing item subclasses, so remap
+    # name of incoming parameters if we're actually handling a child
+    params.each do |k,v|
+      if k =~ /_item/
+        params["item"] = v
+      end
+    end
+
+    begin
+      @item = ItemHelper.find_typed_item(params[:id])
+    rescue
+      render :file => "#{RAILS_ROOT}/public/404.html", :status => 404
+      return
+    end
+
+    if (@item.flags & Item::DATA_IS_UNALTERABLE) != 0
+      flash[:error] = 'This Item cannot be altered.'
+      redirect_to item_path(@item)
+    elsif (!params[:item].nil? && !params[:item][:name].nil? &&
+          params[:item][:name] =~ /[:.]/                     )  ||
+        !@item.update_attributes(params[:item])
+      @item.errors.add :name, "cannot contain a period (.) or a colon (:)."
+      @this_is_non_information_page = true
+      render :action => "edit"
+    else
+      flash[:notice] = 'Item was successfully updated.'
+      redirect_to item_path(@item)
+    end
+  end
+
+  # DELETE /items/1
+  def destroy
+    begin
+      @item = Item.find(params[:id])
+    rescue
+      render :file => "#{RAILS_ROOT}/public/404.html", :status => 404
+      return
+    end
+
+    if (@item.flags & Item::DATA_IS_UNALTERABLE) != 0
+      flash[:error] = 'This Item cannot be altered.'
+      redirect_to item_path(@item)
+    elsif !(Connection.all( :conditions =>
+        [ "subject_id = ? OR predicate_id = ? OR obj_id = ?",
+          @item.id, @item.id, @item.id ]).empty?)
+      flash[:error] = 'This Item is in use by 1+ Connections. ' +
+        'Those must be modified or deleted first.'
+      redirect_to item_path(@item)
+    else
+      @item.destroy
+      redirect_to items_url
+    end
+  end
+
+  # GET /items/lookup?name=anItemName
+  #
+  # This operation is similar to an abbreviated +show+.  It always
+  # sends an HTML fragment (not a complete/valid page) to the
+  # requester, either an error message (plus <tt>:status => 404</tt>,
+  # if the requested item doesn't exist) or a string representation of
+  # the Item's +id+ field (plus <tt>:status => 200</tt>).  While this
+  # is technically a RESTful request, it uses a string (rather than a
+  # database ID number as is the default for Rails requests) as the
+  # request parameter, and the parameter is encoded in the query
+  # string portion of the URL (rather than the path portion, in order
+  # to simplify creation of the matching route).
+  #
+  # This request is primarily intended to be used by Ajax code
+  # executing within another page that has already been served by
+  # WontoMedia.
+  def lookup
+    # huge kludge for testability.  Need to ensure that we don't respond
+    # so quickly (e.g., in setups where client and server are on the same
+    # system) that the JavaScript and acceptance tests can't see the
+    # "request in progress" state of the page/system.
+    if (RAILS_ENV == 'test')
+      Kernel.sleep(0.75)
+    end
+
+    begin
+      item = Item.find_by_name(params[:name])
+      if item.nil?
+        render :text => "<p>Didn't find Item</p>\n", :status => 404
+        return
+      end
+      id = item.id
+    rescue
+      render :text => "<p>Didn't find Item</p>\n", :status => 404
+      return
+    end
+
+    render :text => ("<id>" + id.to_s + "</id>\n")
+  end
+end

data/app/helpers/connections_helper.rb

@@ -0,0 +1,67 @@
+#--
+# WontoMedia - a wontology web application
+# Copyright (C) 2010 - Glen E. Ivey
+#    www.wontology.com
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License version
+# 3 as published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program in the file COPYING and/or LICENSE.  If not,
+# see <http://www.gnu.org/licenses/>.
+#++
+
+
+# Helpers for app/views/connections/* pages
+module ConnectionsHelper
+
+  # This method appends its output directly to the page being built.
+  # It takes a Connection model instance, and generates a set of HTML
+  # links to that connection.  It generates a "Show" link to the
+  # Connection's <tt>connections/show</tt> page.  Unless the
+  # Connection is flagged as <tt>DATA_IS_UNALTERABLE</tt>, it also
+  # generates an "Edit..." link to +con+'s <tt>connections/edit</tt>
+  # page and a "Delete" link that will invoke
+  # <tt>connections/destroy</tt>.  The links are generated with a
+  # "help" icon linking to a popup (see
+  # FormatHelper.link_with_help_icon) _if_ the link being generated is
+  # the first occurrance of that link in the current view.  An instance
+  # variable is created within the current view object to flag the
+  # generation of each type of link.
+  def generate_connection_links(con)
+    concat(
+      link_with_help_icon({
+        :destination => link_to( 'Show', connection_path(con) ),
+        :already_generated => @show_help_icon_used,
+        :help_alt => 'Help show connection',
+        :which_help => 'ConnectionShow' }) )
+    @show_help_icon_used = true
+
+    if (con.flags & Connection::DATA_IS_UNALTERABLE) == 0
+      concat(
+        link_with_help_icon({
+          :destination => link_to(
+            'Edit&hellip;', edit_connection_path(con), :rel => 'nofollow' ),
+          :already_generated => @edit_help_icon_used,
+          :help_alt => 'Help edit connection',
+          :which_help => 'ConnectionEdit' }) )
+      @edit_help_icon_used = true
+
+      concat(
+        link_with_help_icon({
+          :destination => link_to(
+            'Delete', connection_path(con), :rel => 'nofollow',
+            :confirm => 'Are you sure?', :method => :delete ),
+          :already_generated => @delete_help_icon_used,
+          :help_alt => 'Help delete connection',
+          :which_help =>'ConnectionDelete' }) )
+      @delete_help_icon_used = true
+    end
+  end
+end

data/app/helpers/format_helper.rb

@@ -0,0 +1,154 @@
+#--
+# WontoMedia - a wontology web application
+# Copyright (C) 2010 - Glen E. Ivey
+#    www.wontology.com
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU Affero General Public License version
+# 3 as published by the Free Software Foundation.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU Affero General Public License for more details.
+#
+# You should have received a copy of the GNU Affero General Public License
+# along with this program in the file COPYING and/or LICENSE.  If not,
+# see <http://www.gnu.org/licenses/>.
+#++
+
+
+# This module contains a collection of page- and model-independent
+# formatting methods.  All return a string suitable for including
+# directly in a page.
+module FormatHelper
+
+  # This method takes in a string, and returns a version of it
+  # excluding any sub-strings enclosed in parentheticals.  Nested and
+  # multiple parentheticals are supported.  This method is intended to
+  # support the WontoMedia behavior where sometimes an Item.title
+  # string is displayed in its entirety, and sometimes it is
+  # abbreviated (for space) by stripping any parentheticals it contains.
+  def filter_parenthetical(title_in)
+    local_copy = title_in
+    begin
+      title_out = local_copy
+      local_copy = local_copy.sub(/\s*\([^()]*\)/, "")
+    end until local_copy == title_out
+    title_out
+  end
+
+  # This method is used to wrap long strings that don't contain spaces
+  # (which would allow the browser to wrap them), such as an
+  # <tt>Item.name</tt> string.  The +len+ parameter is a length in
+  # _characters_, and the default is tuned to produce reasonably good
+  # results in the table in the items/index page.  The return value is
+  # an HTML snippet including a marker to indicate that wrapping has
+  # occurred.
+  #--
+  # TODO: It would be better if wrapping were done
+  # dynamically in JavaScript as the page is resized, as sometimes
+  # wrapping the string statically doesn't produce a really great
+  # result.  Of course, to really do it right, we'd rewrap any time
+  # the page width is adjusted, and use the actual width of the text
+  # (rather than character count) as the basis for wrapping.
+  def wrap_item_name(name, len = 30)
+    wrapped = ''
+    [ len, len*2, len*3, len*4 ].each do |wrap_at|
+      wrapped += name[wrap_at - len, len].to_s
+      if name.length > wrap_at
+        wrapped += '<span class="wrapper"> &gt;&gt;&gt;</span><br />'
+      end
+    end
+    wrapped
+  end
+
+  # This method generates an HTML snipet for an icon that will cause a
+  # pop-up help box to be displayed when clicked.  This helper is tied
+  # very tightly to WontoMedia's style sheet, included JavaScript
+  # libraries, and image assets.  The parameters are used as follows:
+  #
+  # [alt] This string is used as the 'alt' attribute for the <img> tag that is generated, and allows each help image/link generated by this helper to have unique alt text that describes the kind of help the link points to.
+  # [target] This string specifies the source of the help page that should be rendered into the popup <iframe>.  A complete URL is created by appending the value of +target+ to the configuration value <tt>WontoMedia.popup_url_prefix</tt> from the file <tt>config/initializers/wontomedia.rb</tt>.
+  # [text] The content of this string, if any, is placed immediately _before_ the popup help icon (the <img> tag) that this helper generates.  This text is not part of the link that will cause the help popup to be opened.  When present, the value is packaged along with the help icon in a <span> with the <tt>nowrap</tt> style.  This will prevent the browser from separating the help icon from the label that precedes it due to text wrapping.  If this argument is <tt>nil</tt>, then no span is generated.  An empty string will produce a span with no content aside from the generated link.
+  def popup_help_icon( alt, target, text = nil )
+    content = ''
+    if text
+      content += '<span style="white-space: nowrap;">' + text
+    end
+    content += link_to(
+      (
+        image_tag( 'help_icon.png', :alt=>alt, :class=>'image-in-text' ) +
+        '<span class="tip">Help</span>'
+      ),
+      WontoMedia.popup_url_prefix + target, :tabindex => '0',
+      :class => 'iframeBox linkhastip' )
+    if text
+      content += '</span>'
+    end
+    content
+  end
+
+  # This method wraps a block of text in HTML markup that provides it
+  # with a (CSS-based) 'tooltip'-like popup on mouse-over.  The
+  # arguments are:
+  #
+  # [text] The text string to wrap and make sensitive to mouse-over.  It may contain additional HTML markup, but cannot contain outbound links (e.g., <tt><a href=...></tt>).
+  # [tip] The content for the popup 'tooltip'.  This may also contain HTML markup, but links should be avoided because of both usability considerations (moving the mouse within the tooltip can be challenging because it could go away if the cursors path strays outside the union of the text's and tip's bounding boxes) and the fact that some browsers will confuse links in the tooltip with the dummy link tag that this helper creates.
+  # [id] This helper creates a <tt><span></tt> tag around the supplied +text+.  If +id+ is non-+nil+, its value will be used to create an +id+ attribute for the span.
+  def text_with_tooltip( text, tip, id = nil )
+    span = id.nil? ? '<span>' : "<span id='#{id}'>"
+    inner = "#{span}#{text}</span>" +
+      "<span class='tip' style='white-space: nowrap;'>#{tip}</span>"
+    link_to inner, "#", :class=>'texthastip', :tabindex=>'0'
+  end
+
+  # This method creates a link wraped in HTML markup that provides it
+  # with a (CSS-based) 'tooltip'-like popup on mouse-over.  The
+  # arguments are:
+  #
+  # [text] The content for the link (anchor tag) generated.  It may be any HTML string that would be valid within a link.
+  # [tip] The content for the popup 'tooltip'.  This may also contain HTML markup, but links should be avoided because of both usability considerations (moving the mouse within the tooltip can be challenging because it could go away if the cursors path strays outside the union of the text's and tip's bounding boxes) and the fact that some browsers will confuse links in the tooltip with the link that causes the tooltip to be displayed.
+  # [href] The value of this argument will be used to generate the +href+ attribute of the link created.  It is passed directly to Rails' <tt>link_to</tt> helper, so any string, or Rails object or route that can be converted to a URL can be used.
+  # [id] This helper creates a <tt><span></tt> tag around the content of the +text+ argument.  If +id+ is non-+nil+, its value will be used to create an +id+ attribute for the span.
+  def link_with_tooltip( text, tip, href, id = nil )
+    span = id.nil? ? '<span>' : "<span id='#{id}'>"
+    inner = "#{span}#{text}</span>" +
+      "<span class='tip' style='white-space: nowrap;'>#{tip}</span>"
+    link_to inner, href, :class=>'linkhastip', :tabindex=>'0'
+  end
+
+  # This helper constructs a text link optionally followed by an image
+  # link which, when clicked, will open a popup box in the window
+  # populated by a page from the installation's help wiki.  The markup
+  # generated ensures that word-wrap in the browser will not separate
+  # the help icon from the link that precedes it.  The helper's
+  # parameters are packaged in a single hash argument.  The symbols
+  # used to index the argument hash are:
+  #
+  # [:destination] The value in the hash associated with <tt>:destination</tt> should be a complete HTML link, such as the return value from the Rails' helper <tt>link_to</tt>.
+  # [:already_generated] The value in the hash associated with <tt>:already_generated</tt> will be evaluated as a boolean to determine whether a popup help icon (image link) should be generated by this call to link_with_help_icon.  When it evaluates to false/nil (including simply not being present in the argument hash at all), HTML for a help icon _is_ generated/returned.
+  # [:help_alt] The string in the hash associated with <tt>:help_alt</tt> will be used as the value for the +alt+ attribute of the anchor tag for the help icon/link (if generated).  (The +alt+ tag, if any, for <tt>:destination</tt> should be incorporated in the link's markup before it is passed to this helper.)
+  # [:which_help] The string in the hash associated with <tt>:which_help</tt> is used as a component in the URL to the desired page from the installation's help wiki.  It is combined with the installation's popup_url_prefix configuration value (see popup_help_icon) after being prefixed with <tt>Help:Popup/</tt>.  That is, this helper assumes that within the help wiki, the content for all help displayed in a popup box in the page is stored as a <em>sub-page</em> of the help wiki's page +Popup+ within the wiki's namespace +Help+.
+  # [:text] The _optional_ value in the hash associated with <tt>:text</tt> will, if present, be included in the generated HTML between the content of <tt>:destination</tt> and the generated help icon.  See the +text+ argument to popup_help_icon.
+  def link_with_help_icon( params )
+    help_link = ''
+    unless params[:already_generated]
+      unless params.has_key?(:help_alt)
+        raise ArgumentError, "Missing :help_alt entry from parameter hash"
+      end
+      unless params.has_key?(:which_help)
+        raise ArgumentError, "Missing :which_help entry from parameter hash"
+      end
+
+      help_link = popup_help_icon params[:help_alt],
+        ("Help:Popup/" + params[:which_help]), params[:text]
+    end
+
+    unless params.has_key?(:destination)
+      raise ArgumentError, "Missing :destination entry from parameter hash"
+    end
+    return content_tag( 'span', params[:destination] + help_link,
+      :style => "white-space: nowrap;" ) + " "
+  end
+end