open_rosa 0.1.0

data/examples/rails_integration.rb

@@ -0,0 +1,152 @@
+# frozen_string_literal: true
+
+# Example of how to integrate OpenRosa middleware in a Rails application
+#
+# Add this to your Rails config/application.rb or config/environments/production.rb
+
+# Step 1: Define your forms (perhaps in app/forms/)
+class MySurveyForm < OpenRosa::Form
+  form_id "my_survey"
+  version "1.0.0"
+  name "My Survey"
+  download_url "https://myapp.com/openrosa/forms/my_survey"
+
+  input :name, label: "Name", type: :string, required: true
+  input :age, label: "Age", type: :int
+  select1 :gender, label: "Gender", choices: ["Male", "Female", "Other"]
+
+  # Option A: Form-specific submission handler
+  on_submit do |submission|
+    # Handle submissions for this specific form
+    Survey.create!(
+      instance_id: submission.instance_id,
+      name: submission.data["name"],
+      age: submission.data["age"],
+      gender: submission.data["gender"],
+      submitted_at: submission.metadata[:timeEnd]
+    )
+
+    "Thank you for completing the survey!"
+  end
+end
+
+# Step 2: Add middleware to your Rails application
+# In config/application.rb:
+#
+# module MyApp
+#   class Application < Rails::Application
+#     # ... other config ...
+#
+#     config.middleware.use OpenRosa::Middleware do |config|
+#       config.forms = [MySurveyForm]
+#       config.mount_path = "/openrosa"
+#
+#       # Option B: Global submission handler (for all forms)
+#       config.on_submission do |submission|
+#         # Generic handler for all form submissions
+#         FormSubmission.create!(
+#           form_id: submission.form_id,
+#           instance_id: submission.instance_id,
+#           data: submission.data,
+#           metadata: submission.metadata,
+#           raw_xml: submission.raw_xml
+#         )
+#
+#         # Handle file attachments
+#         submission.attachments.each do |attachment|
+#           # Save to ActiveStorage or file system
+#           record = FormSubmission.find_by(instance_id: submission.instance_id)
+#           record.attachments.attach(
+#             io: StringIO.new(attachment.read),
+#             filename: attachment.filename,
+#             content_type: attachment.content_type
+#           )
+#         end
+#
+#         "Submission received successfully!"
+#       end
+#     end
+#   end
+# end
+
+# Alternative: Use an initializer
+# Create config/initializers/openrosa.rb:
+#
+# Rails.application.config.middleware.use OpenRosa::Middleware do |config|
+#   # Load all form classes from app/forms
+#   config.forms = Dir[Rails.root.join("app/forms/**/*.rb")].map do |file|
+#     require file
+#     # Extract class name from file and constantize
+#     File.basename(file, ".rb").camelize.constantize
+#   end
+#
+#   config.mount_path = "/openrosa"
+#
+#   # Global submission handler
+#   config.on_submission do |submission|
+#     # Process submission...
+#     Rails.logger.info "Received submission for form: #{submission.form_id}"
+#
+#     FormSubmission.create!(
+#       form_id: submission.form_id,
+#       instance_id: submission.instance_id,
+#       payload: submission.data
+#     )
+#   end
+# end
+
+# Step 3: Endpoints will be available at:
+#   GET  /openrosa/formList          - List all forms
+#   GET  /openrosa/forms/:id         - Download specific form XForm XML
+#   HEAD /openrosa/submission        - Pre-flight check for submissions
+#   POST /openrosa/submission        - Receive form submissions
+#
+# These endpoints will properly return XML with OpenRosa headers:
+#   - Content-Type: text/xml; charset=utf-8
+#   - X-OpenRosa-Version: 1.0
+#   - Date: [current date in HTTP format]
+
+# Step 4: (Optional) Add authentication
+# You can add authentication by placing another middleware before OpenRosa:
+#
+# Rails.application.config.middleware.insert_before(
+#   OpenRosa::Middleware,
+#   MyAuthMiddleware
+# )
+#
+# Or use Rails controllers instead for more control:
+# Create app/controllers/openrosa_controller.rb:
+#
+# class OpenrosaController < ApplicationController
+#   before_action :authenticate_user!
+#
+#   def form_list
+#     form_id = params[:formID]
+#     verbose = params[:verbose] == "true"
+#
+#     forms = [MySurveyForm.new]
+#     form_list = OpenRosa::FormList.new(forms, form_id: form_id, verbose: verbose)
+#
+#     render xml: form_list.to_xml, content_type: "text/xml; charset=utf-8"
+#     response.headers["X-OpenRosa-Version"] = "1.0"
+#   end
+#
+#   def form_download
+#     form_class = find_form_class(params[:id])
+#     return head :not_found unless form_class
+#
+#     form = form_class.new
+#     render xml: form.to_xml, content_type: "text/xml; charset=utf-8"
+#     response.headers["X-OpenRosa-Version"] = "1.0"
+#   end
+#
+#   private
+#
+#   def find_form_class(form_id)
+#     [MySurveyForm].find { |fc| fc.new.form_id == form_id }
+#   end
+# end
+#
+# And in config/routes.rb:
+#   get "/openrosa/formList", to: "openrosa#form_list"
+#   get "/openrosa/forms/:id", to: "openrosa#form_download"

data/lib/open_rosa/field_context.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  # Helper class for evaluating blocks in group/repeat DSL
+  # This allows for clean nested field definitions within groups and repeats
+  class FieldContext
+    def initialize(fields_array)
+      @fields = fields_array
+    end
+
+    def input(name, options = {})
+      @fields << Fields::Input.new(name, options)
+    end
+
+    def select1(name, options = {})
+      @fields << Fields::Select1.new(name, options)
+    end
+
+    def select(name, options = {})
+      @fields << Fields::Select.new(name, options)
+    end
+
+    def boolean(name, options = {})
+      @fields << Fields::Boolean.new(name, options)
+    end
+
+    def upload(name, options = {})
+      @fields << Fields::Upload.new(name, options)
+    end
+
+    def range(name, options = {})
+      @fields << Fields::Range.new(name, options)
+    end
+
+    def trigger(name, options = {})
+      @fields << Fields::Trigger.new(name, options)
+    end
+
+    def group(name, options = {}, &)
+      nested_fields = []
+      if block_given?
+        context = FieldContext.new(nested_fields)
+        context.instance_eval(&)
+      end
+
+      @fields << Fields::Group.new(name, options.merge(fields: nested_fields))
+    end
+
+    def repeat(name, options = {}, &)
+      nested_fields = []
+      if block_given?
+        context = FieldContext.new(nested_fields)
+        context.instance_eval(&)
+      end
+
+      @fields << Fields::Repeat.new(name, options.merge(fields: nested_fields))
+    end
+  end
+end

data/lib/open_rosa/fields/base.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Base class for all form field types
+    class Base
+      attr_reader :name, :label, :hint, :required, :default
+
+      def initialize(name, options = {})
+        @name = name
+        @label = options[:label]
+        @hint = options[:hint]
+        @required = options.fetch(:required, false)
+        @default = options[:default]
+      end
+    end
+  end
+end

data/lib/open_rosa/fields/boolean.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Boolean field for true/false values
+    # Maps to XForms select1 element with true/false options
+    # Data type: boolean (stored as "true" or "false" strings in XForms)
+    class Boolean < Base
+      attr_reader :appearance
+
+      def initialize(name, options = {})
+        super
+        @appearance = options[:appearance]
+      end
+    end
+  end
+end

data/lib/open_rosa/fields/group.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Group field for logical grouping of fields
+    # Maps to XForms <group> element
+    # Can contain nested fields and supports conditional display
+    class Group < Base
+      attr_reader :fields, :relevant, :appearance
+
+      def initialize(name, options = {})
+        super
+        @fields = options.fetch(:fields, [])
+        @relevant = options[:relevant]
+        @appearance = options[:appearance]
+      end
+    end
+  end
+end

data/lib/open_rosa/fields/input.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Input field for text, numbers, dates, and other basic input types
+    class Input < Base
+      attr_reader :type, :constraint, :constraint_message
+
+      VALID_TYPES = %i[
+        string int decimal date time dateTime
+        geopoint geotrace geoshape barcode binary intent
+      ].freeze
+
+      def initialize(name, options = {})
+        super
+        @type = options.fetch(:type, :string)
+        @constraint = options[:constraint]
+        @constraint_message = options[:constraint_message]
+
+        validate!
+      end
+
+      private
+
+      def validate!
+        return if VALID_TYPES.include?(@type)
+
+        raise ArgumentError, "type must be one of: #{VALID_TYPES.join(", ")}"
+      end
+    end
+  end
+end

data/lib/open_rosa/fields/range.rb

@@ -0,0 +1,34 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Range field for numeric sliders/pickers
+    # Maps to XForms <range> element
+    # Data type: int or decimal
+    class Range < Base
+      attr_reader :start, :end, :step, :type
+
+      VALID_TYPES = %i[int decimal].freeze
+
+      def initialize(name, options = {})
+        super
+        @start = options[:start]
+        @end = options[:end]
+        @step = options.fetch(:step, 1)
+        @type = options.fetch(:type, :int)
+
+        validate!
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "start is required for Range field" if @start.nil?
+        raise ArgumentError, "end is required for Range field" if @end.nil?
+        raise ArgumentError, "start must be less than end" if @start >= @end
+        raise ArgumentError, "step must be greater than 0" if @step <= 0
+        raise ArgumentError, "type must be :int or :decimal" unless VALID_TYPES.include?(@type)
+      end
+    end
+  end
+end

data/lib/open_rosa/fields/repeat.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Repeat field for repeating sections
+    # Maps to XForms <repeat> element
+    # All fields within repeat can occur multiple times
+    class Repeat < Base
+      attr_reader :fields, :count, :appearance, :relevant
+
+      def initialize(name, options = {})
+        super
+        @fields = options.fetch(:fields, [])
+        @count = options[:count]
+        @appearance = options[:appearance]
+        @relevant = options[:relevant]
+      end
+    end
+  end
+end

data/lib/open_rosa/fields/select.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Multiple select field (checkboxes)
+    # Maps to XForms <select> element
+    # Values are stored as space-separated strings in submissions
+    class Select < Base
+      attr_reader :choices, :appearance
+
+      def initialize(name, options = {})
+        super
+        @choices = options[:choices]
+        @appearance = options[:appearance]
+
+        validate!
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "choices is required for Select field" if @choices.nil?
+        raise ArgumentError, "choices must be an Array or Hash" unless @choices.is_a?(Array) || @choices.is_a?(Hash)
+        raise ArgumentError, "choices cannot be empty" if @choices.empty?
+      end
+    end
+  end
+end

data/lib/open_rosa/fields/select1.rb

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Single select field (radio buttons or dropdown)
+    # Maps to XForms <select1> element
+    class Select1 < Base
+      attr_reader :choices, :appearance
+
+      def initialize(name, options = {})
+        super
+        @choices = options[:choices]
+        @appearance = options[:appearance]
+
+        validate!
+      end
+
+      private
+
+      def validate!
+        raise ArgumentError, "choices is required for Select1 field" if @choices.nil?
+        raise ArgumentError, "choices must be an Array or Hash" unless @choices.is_a?(Array) || @choices.is_a?(Hash)
+        raise ArgumentError, "choices cannot be empty" if @choices.empty?
+      end
+    end
+  end
+end

data/lib/open_rosa/fields/trigger.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Trigger field for confirmation buttons/checkboxes
+    # Maps to XForms <trigger> element
+    # Adds "OK" value when confirmed
+    class Trigger < Base
+      attr_reader :appearance
+
+      def initialize(name, options = {})
+        super
+        @appearance = options[:appearance]
+      end
+    end
+  end
+end

data/lib/open_rosa/fields/upload.rb

@@ -0,0 +1,18 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  module Fields
+    # Upload field for file/media uploads
+    # Maps to XForms <upload> element
+    # Data type: binary
+    class Upload < Base
+      attr_reader :mediatype, :max_pixels
+
+      def initialize(name, options = {})
+        super
+        @mediatype = options[:mediatype]
+        @max_pixels = options[:max_pixels]
+      end
+    end
+  end
+end

data/lib/open_rosa/form.rb

@@ -0,0 +1,146 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  # Base class for defining OpenRosa forms with a clean DSL
+  class Form
+    class << self
+      include FormDSL
+
+      def form_id(id = nil)
+        if id
+          @form_id = id
+        else
+          @form_id
+        end
+      end
+
+      def version(ver = nil)
+        if ver
+          @version = ver
+        else
+          @version
+        end
+      end
+
+      def name(form_name = nil)
+        if form_name
+          @name = form_name
+        else
+          @name
+        end
+      end
+
+      def description_text(text = nil)
+        if text
+          @description_text = text
+        else
+          @description_text
+        end
+      end
+
+      def description_url(url = nil)
+        if url
+          @description_url = url
+        else
+          @description_url
+        end
+      end
+
+      def download_url(url = nil)
+        if url
+          @download_url = url
+        else
+          @download_url
+        end
+      end
+
+      def manifest_url(url = nil)
+        if url
+          @manifest_url = url
+        else
+          @manifest_url
+        end
+      end
+
+      # Calculates MD5 hash of the form's XForm XML content
+      # Returns format: "md5:abc123..."
+      def form_hash
+        require "digest"
+        xml = to_xml
+        hash = Digest::MD5.hexdigest(xml)
+        "md5:#{hash}"
+      end
+
+      # Generates XForm XML from the form definition
+      # Returns the complete XForm XML as a string
+      def to_xml
+        XForm.new(self).to_xml
+      end
+
+      # Define a handler for form submissions
+      #
+      # @yield [submission] The parsed submission
+      # @yieldparam submission [Submission] The submission object
+      # @yieldreturn [String, nil] Optional success message
+      #
+      # Example:
+      #   class MyForm < OpenRosa::Form
+      #     on_submit do |submission|
+      #       MyModel.create!(data: submission.data)
+      #       "Thanks for submitting!"
+      #     end
+      #   end
+      def on_submit(&block)
+        @submission_handler = block
+      end
+
+      # Handle a submission (called by middleware)
+      #
+      # @param submission [Submission] The parsed submission
+      # @return [String, nil] Success message or nil
+      def handle_submission(submission)
+        @submission_handler&.call(submission)
+      end
+    end
+
+    def form_id
+      self.class.form_id
+    end
+
+    def version
+      self.class.version
+    end
+
+    def name
+      self.class.name
+    end
+
+    def description_text
+      self.class.description_text
+    end
+
+    def description_url
+      self.class.description_url
+    end
+
+    def download_url
+      self.class.download_url
+    end
+
+    def manifest_url
+      self.class.manifest_url
+    end
+
+    def form_hash
+      self.class.form_hash
+    end
+
+    def fields
+      self.class.fields
+    end
+
+    def to_xml
+      self.class.to_xml
+    end
+  end
+end

data/lib/open_rosa/form_dsl.rb

@@ -0,0 +1,70 @@
+# frozen_string_literal: true
+
+module OpenRosa
+  # DSL methods for defining form fields
+  module FormDSL
+    # Returns array of all fields defined in this form
+    def fields
+      @fields ||= []
+    end
+
+    # DSL method to add an input field
+    def input(name, options = {})
+      fields << Fields::Input.new(name, options)
+    end
+
+    # DSL method to add a select1 field (single select)
+    def select1(name, options = {})
+      fields << Fields::Select1.new(name, options)
+    end
+
+    # DSL method to add a select field (multiple select)
+    def select(name, options = {})
+      fields << Fields::Select.new(name, options)
+    end
+
+    # DSL method to add a boolean field
+    def boolean(name, options = {})
+      fields << Fields::Boolean.new(name, options)
+    end
+
+    # DSL method to add an upload field
+    def upload(name, options = {})
+      fields << Fields::Upload.new(name, options)
+    end
+
+    # DSL method to add a range field
+    def range(name, options = {})
+      fields << Fields::Range.new(name, options)
+    end
+
+    # DSL method to add a trigger field
+    def trigger(name, options = {})
+      fields << Fields::Trigger.new(name, options)
+    end
+
+    # DSL method to add a group field with nested fields
+    def group(name, options = {}, &)
+      # Create a temporary context to collect nested fields
+      nested_fields = []
+      if block_given?
+        context = FieldContext.new(nested_fields)
+        context.instance_eval(&)
+      end
+
+      fields << Fields::Group.new(name, options.merge(fields: nested_fields))
+    end
+
+    # DSL method to add a repeat field with nested fields
+    def repeat(name, options = {}, &)
+      # Create a temporary context to collect nested fields
+      nested_fields = []
+      if block_given?
+        context = FieldContext.new(nested_fields)
+        context.instance_eval(&)
+      end
+
+      fields << Fields::Repeat.new(name, options.merge(fields: nested_fields))
+    end
+  end
+end