intranet-pictures 0.0.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0ab4f949290d03cad1457928b191456ffd1a7ce7cb2469332ce025978d9a4187
-  data.tar.gz: 046e7c70a389c5b999b1817dd0056a28103c18de56ec888a8248e89d39415ad5
+  metadata.gz: a9d501ee87ce3a72f55276eaed283010fe6290149e51815a52e9f7814921f6ec
+  data.tar.gz: b22160bb395f4a7b1676f4fa844b8e0954f0eb5292152370f6c5b5cd1c60f9ca
 SHA512:
-  metadata.gz: 32bf9cc089a52bc37e47ff5695136ae9ae9ed0d17cabe73966724f38716f504fca3aab26966848aac8ddf028476ad30bf6eee4451ca0d394c1293f642c2ff4ce
-  data.tar.gz: a5910897b5b78444caa328559ca5e594b1fa2d30ef41c8da346177c433069a8749309cca515fbf56ed7adbb177afbdbacf80cae2a1f4fea78576cbd74b06b5cf
+  metadata.gz: 2d82750698f54a3328135679a1adbfeaa3f38cdac2c1e9fe5d870441bf162a35758c942aa131d4c191bea69fb7a8fc01f94a3bfc3f33d2e212a4a581e552adbf
+  data.tar.gz: 31cf32b5245d7b808bcc8714883feede4ef20a8af956bfd0c3cdca95ac9f5e461a32452df4e2f8b6da4a33bf0e54af4c3354157fbe92efd27c2ee059d77c77f3

data/lib/intranet/pictures/json_db_provider.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+require 'json'
+require 'mimemagic'
+
+module Intranet
+  module Pictures
+    # Provides pictures data and pictures groups listings from a database file in JSON format.
+    #
+    # === Structure of the JSON database
+    # See the example below.
+    #
+    # The title of the pictures gallery is indicated in +title+
+    #
+    # Pictures are described individually as a hash in the +pictures+ array. The mandatory keys in
+    # this hash are:
+    # * +id+ : unique identifier of the picture
+    # * +uri+ : location of the picture, relative to the JSON file
+    # * +title+ : description of the picture
+    # * +datetime+ : date and time of the picture, as a string in ISO8601 format
+    # * +height+ and +width+ : size in pixels of the picture
+    #
+    # Pictures are meant to be grouped in various group types (event, city, region/country, ...).
+    # Each group type is defined as an entry in the +groups+ hash and consists of a set of groups,
+    # each of them described by a hash with the following keys:
+    # * +id+ : unique identifier of the group, mandatory
+    # * +title+ : human-readable group name, mandatory
+    # * +brief+ : optional short text associated to the group name
+    # * +uri+ : optional group thumbnail, relative to the JSON file
+    #
+    # Each image is associated to at most one group in each group type by by a a "foreign key"
+    # constraint of the type *picture*.+group_type+ = *group*.+id+.
+    # @example Structure of the JSON database (not all mandatory are present for readability)
+    #   {
+    #     "title": "gallery title",
+    #     "groups": {
+    #       "event": [
+    #         { "id": "party", "title": "...", "brief": "...", "uri": "party.jpg", ... },
+    #         { ... }
+    #       ],
+    #       "city": [
+    #         { "id": "houston", "title": "...", "uri": "houston.png", ... },
+    #         { ... }
+    #       ]
+    #     },
+    #     "pictures": [
+    #       { "uri": "dir/pic0.jpg", "datetime": "...", "event": "party", "city": "houston", ... },
+    #       { ... }
+    #     ]
+    #   }
+    class JsonDbProvider
+      # Initializes a new pictures data provider.
+      # @param json_file [String] The path to the JSON database file.
+      def initialize(json_file)
+        @json_dir = File.dirname(json_file) # also works for URLs
+        @json_file = json_file
+        @json_time = Time.at(0)
+        load_json
+      end
+
+      # Returns the pictures gallery title.
+      # @return [String] The gallery title.
+      # @raise KeyError If no title is defined in JSON file.
+      def title
+        load_json
+        @json.fetch('title').to_s
+      end
+
+      # Returns the list of available group types.
+      # @return [Array<String>] The available group types.
+      # @raise KeyError If no group type is defined in JSON file.
+      def group_types
+        load_json
+        @json.fetch('groups').keys
+      end
+
+      # Returns the list of the groups satisfying the following conditions:
+      # * the group is of the given +type+, and
+      # * at least one picture belonging to that group matches the +selector+.
+      # Results are returned ordered by *group*.+sort_by+ in ascending order if +asc+, and in
+      # descending order otherwise.
+      # @param type [String] The group type.
+      # @param selector [Hash<String,String>] The pictures selector, interpreted as a logical AND
+      #                                       combination of all key/value pairs provided.
+      # @param sort_by [String] The group field to sort the results by, or nil if results should be
+      #                         returned without particular sorting.
+      # @param asc [Boolean] True to sort returned groups in ascending order, False to sort in
+      #                      descending order.
+      # @return [Array<Hash{'id'=>String, 'title'=>String, ...}>] The selected groups.
+      # @raise KeyError If JSON file is malformed, if +type+ does not match an existing group type,
+      #                 or if +sort_by+ is not an existing group field.
+      def list_groups(type, selector = {}, sort_by = nil, asc = true)
+        load_json
+        groups = select_groups(type, selector).map { |g| g.except('uri') }
+        groups.sort_by! { |g| g.fetch(sort_by) } unless sort_by.nil?
+        groups.reverse! unless asc
+        groups
+      end
+
+      # Returns the list of the pictures matching +selector+.
+      # Results are returned ordered by *picture*.+sort_by+ in ascending order if +asc+, and in
+      # descending order otherwise.
+      # @param selector [Hash<String,String>] The pictures selector, interpreted as a logical AND
+      #                                       combination of all key/value pairs provided.
+      # @param sort_by [String] The picture field to sort the results by, or nil if results should
+      #                         be returned without particular sorting.
+      # @param asc [Boolean] True to sort returned pictures in ascending order, False to sort in
+      #                      descending order.
+      # @return [Array<Hash{'id'=>String, 'title'=>String, 'datetime'=>String, 'height'=>Integer,
+      #  'width'=>Integer, ...}>] The selected pictures.
+      # @raise KeyError If JSON file is malformed, or if +sort_by+ is not an existing picture field.
+      def list_pictures(selector = {}, sort_by = nil, asc = true)
+        load_json
+        pics = select_pictures(selector).map { |p| p.except('uri') }
+        pics.sort_by! { |p| p.fetch(sort_by) } unless sort_by.nil?
+        pics.reverse! unless asc
+        pics
+      end
+
+      # Returns the picture file matching +selector+.
+      # @param selector [Hash<String,String>] The picture selector, which should return exactly one
+      #                                       picture.
+      # @return [String, Blob] The MIME type of the picture, and the picture file content.
+      # @raise KeyError If JSON file is malformed, if selector does not match exactly one picture,
+      #                 or if the *picture*.+uri+ does not refer to an existing image file.
+      def picture(selector = {})
+        load_json
+        pic = select_pictures(selector)
+        raise KeyError unless pic.size == 1
+
+        path = File.join(@json_dir, pic.first.fetch('uri'))
+        open_image_file(path)
+      end
+
+      # Returns the thumbnail picture of the group satisfying the following conditions:
+      # * the group is of the given +type+, and
+      # * at least one picture belonging to that group matches the +selector+.
+      # @param type [String] The group type.
+      # @param selector [Hash<String,String>] The pictures selector, interpreted as a logical AND
+      #                                       combination of all key/value pairs provided. The
+      #                                       selector should return exactly one group.
+      # @return [String, Blob] The MIME type of the picture, and the picture file content. Nil may
+      #                        be returned if no thumbnail is available for that group.
+      # @raise KeyError If JSON file is malformed, if selector does not match exactly one group,
+      #                 or if the *group*.+uri+ does not refer to an existing image file.
+      def group_thumbnail(type, selector = {})
+        load_json
+        group = select_groups(type, selector)
+        raise KeyError unless group.size == 1
+        return nil if group.first['uri'].nil?
+
+        path = File.join(@json_dir, group.first.fetch('uri'))
+        open_image_file(path)
+      end
+
+      private
+
+      # (Re)load the JSON file if modified on disk
+      def load_json
+        mtime = File.mtime(@json_file)
+        return unless @json_time < File.mtime(@json_file)
+
+        @json = JSON.parse(File.read(@json_file))
+        @json_time = mtime
+      end
+
+      def open_image_file(path)
+        mime_type = MimeMagic.by_path(path).type
+        raise KeyError unless mime_type.start_with?('image/')
+
+        [MimeMagic.by_path(path).type, File.read(path)]
+      rescue Errno::ENOENT
+        raise KeyError
+      end
+
+      def picture_match?(picture, selector)
+        selector.all? { |k, v| picture.fetch(k) == v }
+      rescue KeyError
+        false
+      end
+
+      def select_groups(type, selector)
+        return @json.fetch('groups').fetch(type) if selector.empty? # optimization
+
+        groups_id = @json.fetch('pictures').map do |p|
+          p.fetch(type) if picture_match?(p, selector)
+        end.uniq.compact
+        @json.fetch('groups').fetch(type).select { |g| groups_id.include?(g.fetch('id')) }
+      end
+
+      def select_pictures(selector)
+        @json.fetch('pictures').select { |p| picture_match?(p, selector) }
+      end
+    end
+  end
+end

data/lib/intranet/pictures/responder.rb

@@ -0,0 +1,247 @@
+# frozen_string_literal: true
+
+require 'intranet/abstract_responder'
+require 'intranet/core/haml_wrapper'
+require 'intranet/core/locales'
+require 'json'
+require_relative 'version'
+
+module Intranet
+  module Pictures
+    # The responder for the Pictures monitor module of the Intranet.
+    class Responder < AbstractResponder
+      include Core::HamlWrapper # 'inherits' from methods of HamlWrapper
+
+      # Returns the name of the module.
+      # @return [String] The name of the module.
+      def self.module_name
+        NAME
+      end
+
+      # The version of the module, according to semantic versionning.
+      # @return [String] The version of the module.
+      def self.module_version
+        VERSION
+      end
+
+      # The homepage of the module.
+      # @return [String] The homepage URL of the module.
+      def self.module_homepage
+        HOMEPAGE_URL
+      end
+
+      # Initializes a new Pictures responder instance.
+      # @param provider [#title,#group_types,#list_groups,#group_thumbnail,#list_pictures,#picture]
+      #  The pictures provider.
+      # @see Intranet::Pictures::JsonDbProvider The specification of the provider, and in particular
+      #  the minimal mandatory elements that must be returned by the operations.
+      # @param recents [Array<Hash{group_type:String, sort_by:String, asc:Boolean, limit:Integer}>]
+      #  The description of the recent pictures album to be displayed on the module home page (all
+      #  keys except +group_type+ may be omitted).
+      # @param home_groups [Array<Hash{group_type:String, sort_by:String, asc:Boolean,
+      #  browse:String, browse_sort_by:String, browse_asc:Boolean}>]
+      #  The description of the groups to be displayed on the module home page. All groups of the
+      #  +group_type+ will be displayed and link to a page showing all groups of the +browse+ type.
+      # @param in_menu [Boolean] Whether the module instance should be displayed in the main
+      #                          navigation menu or not.
+      def initialize(provider, recents = [], home_groups = [], in_menu = true)
+        @provider = provider
+        @recents = recents
+        @in_menu = in_menu
+        @home_groups = home_groups
+      end
+
+      # Specifies if the responder instance should be displayed in the main navigation menu or not.
+      # @return [Boolean] True if the responder instance should be added to the main navigation
+      #                   menu, False otherwise.
+      def in_menu?
+        @in_menu
+      end
+
+      # Specifies the absolute path to the resources directory for that module.
+      # @return [String] The absolute path to the resources directory for the module.
+      def resources_dir
+        File.absolute_path(File.join('..', 'resources'), __dir__)
+      end
+
+      # Generates the HTML content associated to the given +path+ and +query+.
+      # === REST API Description:
+      # * Read-only access to pictures listings under */api/pictures* using +GET+ method, response
+      #   is in JSON format with the following structure:
+      #     [
+      #       { "id": "...", "height": 480, "width": 640, "title": "...", "datetime": "...", ... },
+      #       { ... }
+      #     ]
+      # * Read-only access to groups listings under */api/groups/*+group_type+ using +GET+ method,
+      #   response is in JSON format with the following structure:
+      #     [
+      #       { "id": "...", "title": "...", ... },
+      #       { ... }
+      #     ]
+      # @param path [String] The requested URI, relative to that module root URI.
+      # @param query [Hash<String,String>] The URI variable/value pairs, if any.
+      # @return [Integer, String, String] The HTTP return code, the MIME type and the answer body.
+      def generate_page(path, query)
+        case path
+        when %r{^/index\.html$} then serve_home
+        when %r{^/browse_\w+\.html$}
+          serve_groups(path.gsub(%r{^/browse_(\w+)\.html$}, '\\1'), query)
+        when %r{^/api/} then serve_api(path.gsub(%r{^/api}, ''), query)
+        else super(path, query)
+        end
+      end
+
+      # The title of the Pictures module, as displayed on the web page.
+      # @return [String] The title of the Pictures module web page.
+      def title
+        @provider.title
+      end
+
+      # Provides the list of Cascade Style Sheets (CSS) dependencies for this module.
+      # @return [Array<String>] The list of CSS dependencies.
+      def css_dependencies
+        super + ['design/style.css',
+                 'design/photoswipe/photoswipe.css',
+                 'design/photoswipe/default-skin/default-skin.css']
+      end
+
+      # Provides the list of Javascript files (JS) dependencies for this module.
+      # @return [Array<String>] The list of JS dependencies.
+      def js_dependencies
+        super + ['design/jpictures.js',
+                 'design/photoswipe/photoswipe.min.js',
+                 'design/photoswipe/photoswipe-ui-default.min.js']
+      end
+
+      private
+
+      # Extract a selector from the given +query+.
+      # @return [Hash<String,String>] The picture or group selector.
+      def selector(query)
+        query.except('sort_by', 'sort_order')
+      end
+
+      # Extract the sort criteria from the given +query+.
+      # @return [String] The key to use to sort pictures or groups, or nil if no sort order is
+      #                  specified in +query+.
+      def sort_by(query)
+        query.fetch('sort_by')
+      rescue KeyError
+        nil
+      end
+
+      # Extract the sort order from the given +query+.
+      # @return [Boolean] False if the pictures or groups should be sorted in descending order,
+      #                   True otherwise.
+      # @raise KeyError If the query requests an invalid sort order.
+      def sort_order(query)
+        return false if query['sort_order'] == 'desc'
+        return true if query['sort_order'].nil? || query['sort_order'] == 'asc'
+
+        raise KeyError # incorrect value for 'sort_order'
+      end
+
+      ##########################################################################
+      ###            Servicing of the HTML "display-able" content            ###
+      ##########################################################################
+
+      def active_filters(query)
+        selector(query).map do |k, v|
+          { k => @provider.list_groups(k, { k => v }).first.fetch('title') }
+        rescue KeyError
+          { k => v }
+        end.reduce({}, :merge)
+      end
+
+      def recent_groups
+        @recents.map do |recent|
+          groups = @provider.list_groups(recent[:group_type], {}, recent[:sort_by], recent[:asc])
+          see_more_url = ''
+          if recent[:limit].to_i.positive?
+            groups = groups.first(recent[:limit])
+            see_more_url = "browse_#{recent[:group_type]}.html?sort_by=#{recent[:sort_by]}"
+            see_more_url += '&sort_order=desc' unless recent[:asc]
+          end
+          { group_type: recent[:group_type], groups: groups, see_more_url: see_more_url }
+        end
+      end
+
+      def all_groups
+        @home_groups.map do |section|
+          groups = @provider.list_groups(section[:group_type], {}, section[:sort_by], section[:asc])
+          url_prefix = "browse_#{section[:browse]}.html?sort_by=#{section[:browse_sort_by]}"
+          url_prefix += '&sort_order=desc' unless section[:browse_asc]
+          { group_type: section[:group_type], groups: groups, url_prefix: url_prefix }
+        end
+      end
+
+      def make_nav(group_type = nil, query = {})
+        h = { I18n.t('nav.home') => '/index.html', I18n.t('pictures.menu') => nil, title => nil }
+        unless group_type.nil?
+          h[title] = 'index.html'
+          extra_key = I18n.t("pictures.nav.#{group_type}")
+          filters = active_filters(query).values
+          extra_key += " (#{filters.join(', ')})" unless filters.empty?
+          h.store(extra_key, nil)
+        end
+        h
+      end
+
+      def gallery_url(group_type, group_id, filters = {})
+        filters.store(group_type, group_id)
+        filters.store('sort_by', 'datetime')
+        filters.map { |k, v| [k, v].join('=') }.join('&')
+      end
+
+      def serve_home
+        content = to_markup('pictures_home', nav: make_nav)
+        [206, 'text/html', { content: content, title: title }]
+      rescue KeyError
+        [404, '', '']
+      end
+
+      def serve_groups(type, query)
+        groups = @provider.list_groups(type, selector(query), sort_by(query), sort_order(query))
+        content = to_markup('pictures_browse', nav: make_nav(type, query), group_type: type,
+                                               filters: selector(query), groups: groups)
+        [206, 'text/html', { content: content, title: title }]
+      rescue KeyError
+        [404, '', '']
+      end
+
+      ##########################################################################
+      ###        Servicing of the REST API (raw JSON data & pictures)        ###
+      ##########################################################################
+
+      def api_list_groups(path, query)
+        group_type = path.split('/')[2].to_s
+        @provider.list_groups(group_type, selector(query), sort_by(query), sort_order(query))
+      end
+
+      def api_group_thumbnail(path, query)
+        group_type = path.split('/')[2].to_s
+        pic = @provider.group_thumbnail(group_type, selector(query))
+        if pic.nil?
+          pic = ['image/jpeg', File.read(File.join(resources_dir, 'www', 'group_thumbnail.jpg'))]
+        end
+        pic
+      end
+
+      def api_list_pictures(query)
+        @provider.list_pictures(selector(query), sort_by(query), sort_order(query))
+      end
+
+      def serve_api(path, query)
+        case path
+        when %r{^/groups/} then [200, 'application/json', api_list_groups(path, query).to_json]
+        when %r{^/group/} then [200, api_group_thumbnail(path, query)].flatten
+        when %r{^/pictures$} then [200, 'application/json', api_list_pictures(query).to_json]
+        when %r{^/picture$} then [200, @provider.picture(query)].flatten
+        else [404, '', '']
+        end
+      rescue KeyError
+        [404, '', '']
+      end
+    end
+  end
+end