effective_work_experience 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 9a876f18790cdca6bc9e13228ec0be8b643e4167e1e348cfaf00f09c9376f79f
+  data.tar.gz: c08a8257f216cb33f27760b729526b76d854a6d4f7d71ec32c21af581f78c358
+SHA512:
+  metadata.gz: 7c4aa51ef471a77a677dfb382e4a4c190336903557b827d3b9839c93f075ad2c856b8d281692f0efbe8d6291d5c99fd797d77cf840dd8e71048ebb0104fbd597
+  data.tar.gz: '0788634767708d121ce06edadf1cfefd9c5150b4cfed0ae5e0e354143a3f4446b0891a0115ccf3b45c98911c426223ca0cda33af45d782c60b738e85f1128723'

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2026 Code and Effect 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,188 @@
+# Effective Work Experience
+
+Interns record their work experience hours and projects, and mentors review them.
+
+Interns record their hours each month against a set of work experience subcategories, and record the projects they worked on. Every few months they submit a summary of that period, which is reviewed by their mentor. A work experience report totals everything to date against the minimum hours of each category.
+
+## Getting Started
+
+This requires Rails 6+ and Twitter Bootstrap 4 and just works with Devise.
+
+Please first install the [effective_datatables](https://github.com/code-and-effect/effective_datatables) gem.
+
+Please download and install the [Twitter Bootstrap4](http://getbootstrap.com)
+
+Add to your Gemfile:
+
+```ruby
+gem 'effective_work_experience'
+```
+
+Run the bundle command to install it:
+
+```console
+bundle install
+```
+
+Then run the generator:
+
+```ruby
+rails generate effective_work_experience:install
+```
+
+The generator will install an initializer which describes all configuration options and creates a database migration.
+
+Then migrate the database:
+
+```ruby
+rake db:migrate
+```
+
+## Models
+
+- `Effective::WorkExperienceCategory` — the top level grouping, with a minimum hours target
+- `Effective::WorkExperienceSubcategory` — belongs to a category. Hours are recorded against these.
+- `Effective::WorkExperienceRecord` — one intern's hours for one month
+- `Effective::WorkExperienceEntry` — one row of a record. Five weeks of hours for one subcategory.
+- `Effective::WorkExperienceProject` — one project an intern worked on
+- `Effective::WorkExperienceSummary` — one period, submitted by the intern and reviewed by their mentor
+- `Effective::WorkExperienceOutsideMentor` — a mentor without an account, stored as freeform fields
+- `Effective::WorkExperienceReport` — an ActiveModel report of everything to date
+
+The work experience summary is the only swappable class. Mark your own with `effective_work_experience_summary`:
+
+```ruby
+module Bcsla
+  class WorkExperienceSummary < ApplicationRecord
+    effective_work_experience_summary
+  end
+end
+```
+
+and configure it:
+
+```ruby
+config.work_experience_summary_class_name = 'Bcsla::WorkExperienceSummary'
+```
+
+## User
+
+Add the following to your User model:
+
+```ruby
+effective_work_experience_user
+```
+
+This requires a `work_experience_mentor_id` column on your users table, and adds:
+
+- `work_experience_mentor` — the user who reviews my work experience summaries
+- `work_experience_mentees` — the interns I am a mentor for
+- `work_experience_outside_mentor` — my mentor when they don't have an account. A `has_one`.
+- `work_experience_records`, `work_experience_entries`, `work_experience_projects`, `work_experience_summaries`, `mentee_work_experience_summaries`
+- the `work_experience_hours`, `work_experience_hours_by_year` and `work_experience_total_hours_to_date` calculations
+
+An intern with an outside mentor has no `work_experience_mentor`, so their summaries are reviewed automatically on submit.
+
+The summary's `user`, `mentor` and `supervisor` are polymorphic. A summary assigns its mentor from the user's `work_experience_mentor`, and its supervisor from the user's `supervisor` when your User model defines one.
+
+Render the mentor fields from your own admin user form:
+
+```haml
+= render('effective/work_experience/user_fields', f: f)
+```
+
+This is the `work_experience_mentor` select plus an `f.has_many` builder for the one outside mentor.
+
+## Dashboard
+
+Render the dashboard partials from your own dashboard:
+
+```haml
+- if current_user.work_experience_intern?
+  = render 'effective/work_experience/dashboard_intern'
+
+- if current_user.work_experience_mentor?
+  = render 'effective/work_experience/dashboard_mentor'
+```
+
+## Configuration
+
+All configuration options are documented in the `config/initializers/effective_work_experience.rb` initializer.
+
+## Authorization
+
+All authorization checks are handled via the effective_resources gem found in the `config/initializers/effective_resources.rb` file.
+
+## Permissions
+
+The permissions you actually want to define are as follows (using CanCan):
+
+```ruby
+if user.persisted?
+  can([:index, :show, :new, :create], Effective::WorkExperienceRecord) { |record| record.user == user }
+  can([:edit, :update], Effective::WorkExperienceRecord) { |record| !record.backdated? && !record.was_reviewed? }
+  can(:destroy, Effective::WorkExperienceRecord) { |record| !record.backdated? && !record.was_submitted? }
+
+  can(crud, Effective::WorkExperienceProject) { |project| project.user == user }
+
+  can([:new, :create], EffectiveWorkExperience.WorkExperienceSummary) { |summary| summary.user == user }
+  can(:destroy, EffectiveWorkExperience.WorkExperienceSummary) { |summary| summary.user == user && summary.draft? }
+
+  can([:show, :index], EffectiveWorkExperience.WorkExperienceSummary) do |summary|
+    summary.user == user || (summary.mentor == user && summary.was_submitted?)
+  end
+
+  can(:update, EffectiveWorkExperience.WorkExperienceSummary) do |summary|
+    (summary.user == user && !summary.was_submitted?) || (summary.mentor == user && summary.was_submitted?)
+  end
+
+  can(:show, Effective::WorkExperienceReport) { |report| report.user == user || report.mentor == user }
+
+  if user.work_experience_mentor?
+    can(:index, EffectiveWorkExperienceReportsReviewDatatable)
+  end
+end
+
+if user.admin?
+  can :admin, :effective_work_experience
+
+  can([:index, :edit, :update], Effective::WorkExperienceCategory)
+  can([:index, :edit, :update], Effective::WorkExperienceSubcategory)
+  can(crud - [:show], Effective::WorkExperienceProject)
+  can(crud - [:show], Effective::WorkExperienceRecord)
+  can(crud, Effective::WorkExperienceReport)
+  can(crud, EffectiveWorkExperience.WorkExperienceSummary)
+  can(:index, Admin::EffectiveWorkExperienceReportsDatatable)
+end
+```
+
+Add a link to the admin menu:
+
+```haml
+- if can? :admin, :effective_work_experience
+  = nav_link_to Effective::WorkExperienceRecord, effective_work_experience.admin_work_experience_records_path
+  = nav_link_to Effective::WorkExperienceProject, effective_work_experience.admin_work_experience_projects_path
+  = nav_link_to EffectiveWorkExperience.WorkExperienceSummary, effective_work_experience.admin_work_experience_summaries_path
+  = nav_link_to Effective::WorkExperienceReport, effective_work_experience.admin_work_experience_reports_path
+```
+
+## License
+
+MIT License. Copyright [Code and Effect Inc.](http://www.codeandeffect.com/)
+
+## Testing
+
+Run tests by:
+
+```ruby
+rails test
+```
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Bonus points for test coverage
+6. Create new Pull Request

data/Rakefile

@@ -0,0 +1,18 @@
+require "bundler/setup"
+
+APP_RAKEFILE = File.expand_path("test/dummy/Rakefile", __dir__)
+load "rails/tasks/engine.rake"
+
+load "rails/tasks/statistics.rake"
+
+require "bundler/gem_tasks"
+
+require "rake/testtask"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+task default: :test

data/app/assets/config/effective_work_experience_manifest.js

@@ -0,0 +1,3 @@
+//= link_directory ../javascripts .js
+//= link_directory ../stylesheets .css
+//= link_tree ../images

data/app/assets/javascripts/effective_work_experience.js

@@ -0,0 +1 @@
+//= require_tree ./effective_work_experience

data/app/assets/stylesheets/effective_work_experience/base.scss

@@ -0,0 +1,7 @@
+.work-experience-summary {
+  .resource-buttons { margin-top: 1rem; }
+}
+
+.table-valign-middle {
+  td, th { vertical-align: middle; }
+}

data/app/assets/stylesheets/effective_work_experience.scss

@@ -0,0 +1 @@
+@import 'effective_work_experience/base';

data/app/controllers/admin/work_experience_categories_controller.rb

@@ -0,0 +1,19 @@
+module Admin
+  class WorkExperienceCategoriesController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_work_experience) }
+
+    include Effective::CrudController
+
+    resource_scope -> { Effective::WorkExperienceCategory.deep.all }
+    datatable -> { EffectiveResources.best('Admin::EffectiveWorkExperienceCategoriesDatatable').new }
+
+    private
+
+    def permitted_params
+      model = (params.key?(:effective_work_experience_category) ? :effective_work_experience_category : :work_experience_category)
+      params.require(model).permit!
+    end
+
+  end
+end

data/app/controllers/admin/work_experience_projects_controller.rb

@@ -0,0 +1,19 @@
+module Admin
+  class WorkExperienceProjectsController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_work_experience) }
+
+    include Effective::CrudController
+
+    resource_scope -> { Effective::WorkExperienceProject.deep.all }
+    datatable -> { EffectiveResources.best('Admin::EffectiveWorkExperienceProjectsDatatable').new }
+
+    private
+
+    def permitted_params
+      model = (params.key?(:effective_work_experience_project) ? :effective_work_experience_project : :work_experience_project)
+      params.require(model).permit!
+    end
+
+  end
+end

data/app/controllers/admin/work_experience_records_controller.rb

@@ -0,0 +1,19 @@
+module Admin
+  class WorkExperienceRecordsController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_work_experience) }
+
+    include Effective::CrudController
+
+    resource_scope -> { Effective::WorkExperienceRecord.deep.all }
+    datatable -> { EffectiveResources.best('Admin::EffectiveWorkExperienceRecordsDatatable').new }
+
+    private
+
+    def permitted_params
+      model = (params.key?(:effective_work_experience_record) ? :effective_work_experience_record : :work_experience_record)
+      params.require(model).permit!
+    end
+
+  end
+end

data/app/controllers/admin/work_experience_reports_controller.rb

@@ -0,0 +1,21 @@
+module Admin
+  class WorkExperienceReportsController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_work_experience) }
+
+    include Effective::CrudController
+
+    resource_scope -> { Effective::WorkExperienceReport }
+    datatable -> { EffectiveResources.best('Admin::EffectiveWorkExperienceReportsDatatable').new }
+
+    def show
+      @user = current_user.class.find(params[:id])
+      @work_experience_report = resource_scope.new(user: @user)
+
+      @page_title = "#{EffectiveResources.et(@work_experience_report)} for #{@user}"
+
+      EffectiveResources.authorize!(self, :show, @work_experience_report)
+    end
+
+  end
+end

data/app/controllers/admin/work_experience_subcategories_controller.rb

@@ -0,0 +1,19 @@
+module Admin
+  class WorkExperienceSubcategoriesController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_work_experience) }
+
+    include Effective::CrudController
+
+    resource_scope -> { Effective::WorkExperienceSubcategory.deep.all }
+    datatable -> { EffectiveResources.best('Admin::EffectiveWorkExperienceSubcategoriesDatatable').new }
+
+    private
+
+    def permitted_params
+      model = (params.key?(:effective_work_experience_subcategory) ? :effective_work_experience_subcategory : :work_experience_subcategory)
+      params.require(model).permit!
+    end
+
+  end
+end

data/app/controllers/admin/work_experience_summaries_controller.rb

@@ -0,0 +1,19 @@
+module Admin
+  class WorkExperienceSummariesController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+    before_action { EffectiveResources.authorize!(self, :admin, :effective_work_experience) }
+
+    include Effective::CrudController
+
+    resource_scope -> { EffectiveWorkExperience.WorkExperienceSummary.deep.all }
+    datatable -> { EffectiveResources.best('Admin::EffectiveWorkExperienceSummariesDatatable').new }
+
+    private
+
+    def permitted_params
+      model = (params.key?(:effective_work_experience_summary) ? :effective_work_experience_summary : :work_experience_summary)
+      params.require(model).permit!
+    end
+
+  end
+end

data/app/controllers/effective/work_experience_projects_controller.rb

@@ -0,0 +1,17 @@
+module Effective
+  class WorkExperienceProjectsController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+
+    include Effective::CrudController
+
+    resource_scope -> { Effective::WorkExperienceProject.deep.where(user: current_user) }
+
+    private
+
+    def permitted_params
+      model = (params.key?(:effective_work_experience_project) ? :effective_work_experience_project : :work_experience_project)
+      params.require(model).except(:user_id, :user_type).permit!
+    end
+
+  end
+end

data/app/controllers/effective/work_experience_records_controller.rb

@@ -0,0 +1,17 @@
+module Effective
+  class WorkExperienceRecordsController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+
+    include Effective::CrudController
+
+    resource_scope -> { Effective::WorkExperienceRecord.deep.where(user: current_user) }
+
+    private
+
+    def permitted_params
+      model = (params.key?(:effective_work_experience_record) ? :effective_work_experience_record : :work_experience_record)
+      params.require(model).except(:user_id, :user_type).permit!
+    end
+
+  end
+end

data/app/controllers/effective/work_experience_reports_controller.rb

@@ -0,0 +1,19 @@
+module Effective
+  class WorkExperienceReportsController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+
+    include Effective::CrudController
+
+    resource_scope -> { Effective::WorkExperienceReport }
+
+    def show
+      @user = current_user.class.find(params[:id])
+      @work_experience_report = resource_scope.new(user: @user)
+
+      @page_title = "#{EffectiveResources.et(@work_experience_report)} for #{@user}"
+
+      EffectiveResources.authorize!(self, :show, @work_experience_report)
+    end
+
+  end
+end

data/app/controllers/effective/work_experience_summaries_controller.rb

@@ -0,0 +1,17 @@
+module Effective
+  class WorkExperienceSummariesController < ApplicationController
+    before_action(:authenticate_user!) if defined?(Devise)
+
+    include Effective::WizardController
+
+    resource_scope -> {
+      collection = EffectiveWorkExperience.WorkExperienceSummary.deep
+      collection.where(user: current_user).or(collection.where(mentor: current_user))
+    }
+
+    def build_wizard_resource
+      resource_scope.new(user: current_user)
+    end
+
+  end
+end

data/app/datatables/admin/effective_work_experience_categories_datatable.rb

@@ -0,0 +1,22 @@
+module Admin
+  class EffectiveWorkExperienceCategoriesDatatable < Effective::Datatable
+    datatable do
+      order :position
+
+      col :updated_at, visible: false
+      col :created_at, visible: false
+      col :id, visible: false
+
+      reorder :position
+      col :title
+      col :minimum_hours
+
+      actions_col
+    end
+
+    collection do
+      Effective::WorkExperienceCategory.deep.all
+    end
+
+  end
+end

data/app/datatables/admin/effective_work_experience_projects_datatable.rb

@@ -0,0 +1,24 @@
+module Admin
+  class EffectiveWorkExperienceProjectsDatatable < Effective::Datatable
+    datatable do
+      order :updated_at
+
+      col :updated_at, visible: false
+      col :created_at, visible: false
+      col :id, visible: false
+
+      col :user, label: 'Intern'
+      col :start_on
+      col :end_on
+      col :name
+      col :description
+
+      actions_col
+    end
+
+    collection do
+      Effective::WorkExperienceProject.deep.all
+    end
+
+  end
+end

data/app/datatables/admin/effective_work_experience_records_datatable.rb

@@ -0,0 +1,37 @@
+module Admin
+  class EffectiveWorkExperienceRecordsDatatable < Effective::Datatable
+    datatable do
+      order :updated_at
+
+      col :updated_at, visible: false
+      col :created_at, visible: false
+      col :id, visible: false
+
+      col :user, label: 'Intern'
+
+      col(:month) do |work_experience_record|
+        work_experience_record.month&.strftime('%F') || 'Backdated'
+      end
+
+      col(:total_hours, label: 'Hours') do |work_experience_record|
+        work_experience_hours_to_s(work_experience_record.total_hours)
+      end.aggregate do |work_experience_records|
+        total = work_experience_records.sum { |work_experience_record| work_experience_record.total_hours }
+        work_experience_hours_to_s(total)
+      end
+
+      col :status, visible: false
+      col :submitted_at, visible: false
+      col :reviewed_at, visible: false
+
+      aggregate :total
+
+      actions_col
+    end
+
+    collection do
+      Effective::WorkExperienceRecord.deep.all
+    end
+
+  end
+end

data/app/datatables/admin/effective_work_experience_reports_datatable.rb

@@ -0,0 +1,34 @@
+module Admin
+  class EffectiveWorkExperienceReportsDatatable < Effective::Datatable
+    datatable do
+      col :user, label: 'Intern'
+      col :mentor
+
+      col(:total_hours, label: 'Total hours to date', as: :decimal) do |hours|
+        work_experience_hours_to_s(hours)
+      end
+
+      actions_col(actions: []) do |user|
+        dropdown_link_to('Show', effective_work_experience.admin_work_experience_report_path(user))
+      end
+    end
+
+    collection do
+      user_klass = current_user.class
+
+      work_experience_records = Effective::WorkExperienceRecord.where(user_type: user_klass.name)
+
+      users = user_klass.deep_work_experience.where(id: work_experience_records.select(:user_id))
+
+      users.map do |user|
+        [
+          user,
+          user.work_experience_mentor,
+          user.work_experience_total_hours_to_date(month: Time.zone.now.end_of_year),
+          user
+        ]
+      end
+    end
+
+  end
+end

data/app/datatables/admin/effective_work_experience_subcategories_datatable.rb

@@ -0,0 +1,24 @@
+module Admin
+  class EffectiveWorkExperienceSubcategoriesDatatable < Effective::Datatable
+    datatable do
+      reorder :position
+
+      col :updated_at, visible: false
+      col :created_at, visible: false
+      col :id, visible: false
+
+      col :position
+      col :work_experience_category, search: { collection: Effective::WorkExperienceCategory.sorted.all }
+      col :title
+      col :minimum_hours
+      col :body
+
+      actions_col
+    end
+
+    collection do
+      Effective::WorkExperienceSubcategory.deep.all
+    end
+
+  end
+end

data/app/datatables/admin/effective_work_experience_summaries_datatable.rb

@@ -0,0 +1,57 @@
+module Admin
+  class EffectiveWorkExperienceSummariesDatatable < Effective::Datatable
+    filters do
+      scope :all
+      scope :draft
+      scope :submitted
+      scope :reviewed
+    end
+
+    datatable do
+      order :updated_at
+
+      col :updated_at, visible: false
+      col :created_at, visible: false
+      col :id, visible: false
+
+      col :start_on, search: work_experience_summary_start_on_collection()
+      col :end_on, visible: false
+      col :period
+      col :status
+
+      col :user, label: 'Intern'
+      col :mentor
+      col :supervisor, visible: false
+
+      col(:total_hours) do |work_experience_summary|
+        work_experience_hours_to_s(work_experience_summary.total_hours)
+      end
+
+      col(:total_hours_to_date, as: :decimal) do |work_experience_summary|
+        work_experience_hours_to_s(work_experience_summary.total_hours_to_date)
+      end
+
+      col(:submitted_at, label: 'Submitted') do |work_experience_summary|
+        work_experience_summary.submitted_at&.strftime('%F')
+      end
+
+      col(:reviewed_at, label: 'Reviewed', as: :date) do |work_experience_summary|
+        work_experience_summary.reviewed_at&.strftime('%F')
+      end
+
+      col :recommendation, visible: false
+      col :comments
+
+      col :status_steps, visible: false
+      col :wizard_steps, visible: false
+      col :token, visible: false
+
+      actions_col
+    end
+
+    collection do
+      EffectiveWorkExperience.WorkExperienceSummary.deep.all
+    end
+
+  end
+end