{"id":16184895,"url":"https://github.com/freesteph/watchdog","last_synced_at":"2026-02-01T02:02:11.936Z","repository":{"id":40142807,"uuid":"256281119","full_name":"freesteph/watchdog","owner":"freesteph","description":"The Watchdog Widget Engine","archived":false,"fork":false,"pushed_at":"2023-01-20T22:39:23.000Z","size":176,"stargazers_count":1,"open_issues_count":12,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-10-10T23:24:03.294Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/freesteph.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"MIT-LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2020-04-16T17:16:35.000Z","updated_at":"2022-02-22T08:00:03.000Z","dependencies_parsed_at":"2023-02-12T06:15:48.291Z","dependency_job_id":null,"html_url":"https://github.com/freesteph/watchdog","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/freesteph/watchdog","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freesteph%2Fwatchdog","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freesteph%2Fwatchdog/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freesteph%2Fwatchdog/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freesteph%2Fwatchdog/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/freesteph","download_url":"https://codeload.github.com/freesteph/watchdog/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/freesteph%2Fwatchdog/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28964423,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-01T01:25:30.373Z","status":"online","status_checked_at":"2026-02-01T02:00:08.102Z","response_time":56,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-10T07:12:31.503Z","updated_at":"2026-02-01T02:02:11.920Z","avatar_url":"https://github.com/freesteph.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Watchdog\nWatchdog is a Rails engine designed to read and present widgets, which\nare simple charts with extra metadata.\n\n![screenshot of Watchdog](https://github.com/freesteph/watchdog/raw/master/app/assets/images/screenshot.png)\n\nIt reads a YAML file in `config/widgets.yml` and will render them onto\nthe page. You only need to define your widgets configuration and write\nthe matching controllers action to provide data for them.\n\nExample:\n\nIn your `config/widgets.yml` file:\n\n```yaml\nwidgets:\n  -\n    id: unanswered_tickets\n    title: 'Unanswered tickets'\n    subtitle: 'This week'\n    type: 'pie'\n    group: 'zendesk'\n    refresh_rate: 10\n```\n\nthen in your `app/controller/zendesk_controller.rb`:\n\n```ruby\nclass Watchdog::ZendeskController \u003c ApplicationController\n  def unanswered_tickets\n    render json: [[3, 2], [8, 2]]\n  end\nend\n```\n\nAnd that's it! Read further for detailed instructions.\n\n## Dummy app\n\nIf you just want to get a feel of how Watchdog works, just:\n\n1. clone the repo;\n2. run `bundle install`\n3. step into the `test/dummy/` directory;\n4. run `yarn`;\n3. run `bundle exec rails s`;\n5. navigate to `http://localhost:3000/watchdog/widgets`.\n\n## Installation\nAdd this line to your application's Gemfile:\n\n```ruby\ngem 'watchdog'\n```\n\nAnd then execute:\n```bash\n$ bundle\n```\n\nOr install it yourself as:\n```bash\n$ gem install watchdog\n```\n\n## Dependencies\n\nThe engine currently supports Rails 6 and above. It requires\n[`govuk-frontend`](https://github.com/alphagov/govuk-frontend/blob/master/docs/installation/installing-with-npm.md) to be loaded and available.\n\n## Usage\n\n### Mount the engine\n\nIn your `config/routes.rb`, add this line:\n\n```ruby\nmount Watchdog::Engine, at: '/watchdog'\n```\n\n`/watchdog` is purely arbitrary here, but we'll assume that namespace\nfor the rest of this guide.\n\n### Link the assets\n\nIn your `app/assets/config/manifest.js`, add the Watchdog bundle:\n\n```js\n//= link watchdog_manifest.js\n```\n\nIn a SASS file of your choice (ours is\n`app/assets/stylesheets/core.css.scss`), import the Watchdog\nstylesheet:\n\n```css\n@import 'watchdog/application';\n```\n\nSince Watchdog relies on `govuk-frontend` styling, make sure it is\nsetup and loaded before our import line.\n\n### Setup widgets\n\nAdd a YAML file in `config/widgets.yml`. It should contain an array of\nwidgets under a `widgets` key like this:\n\n```yaml\nwidgets:\n  -\n    id: unanswered_tickets\n    title: 'Unanswered tickets'\n    subtitle: 'This week'\n    type: 'pie'\n    group: 'zendesk'\n    refresh_rate: 10\n  -\n    id: answered_tickets\n    title: 'Answered tickets'\n    subtitle: 'This week'\n    type: 'line'\n    group: 'zendesk'\n    style: 'wide'\n```\n\nWatchdog will automatically pick up these when you start your app, so\nmake sure you restart your app if you operate any changes in it.\n\n### Setup actions\n\nEvery widget needs a data source, and that data source is inferred by\nWatchdog: it looks for a controller named after the widget's `group`\nproperty, then calls the action matching the widget's `id` property.\n\nIn the sample YAML file above, the first widget will look for a\n`ZendeskController` and try to call `unanswered_tickets` on it to get\ndata. So go ahead and write a controller for it:\n\n```ruby\nclass Watchdog::ZendeskController \u003c ApplicationController\n  def unanswered_tickets\n    render json: [[2, 3], [3, 4], [4, 5]]\n  end\nend\n```\n\nDon't forget to declare your controller within the `Watchdog::`\nnamespace.\n\nThe controller infering is done with Rails's own inflector so you\ncould have an `antique_road_show` group that would map to\n`Watchdog::AntiqueRoadShowController`.\n\n### Contemplate widgets\nThat's it! Navigate to `localhost:3000/watchdog/widgets` to see the\nresult.\n\nNote that how you provide data to your widgets is entirely up to you.\n\n## Widget properties\n\nEach widget in the YAML config file can sport the following\nproperties:\n\n| name         | type   | required? | description                                                                                                                       |\n|--------------|--------|-----------|-----------------------------------------------------------------------------------------------------------------------------------|\n| **id**       | string | X         | Identifier. Requires a matching action defined on the relevant controller.                                                        |\n| **group**    | string | X         | Group this widget belongs to. Indicates which controller to look for.                                                             |\n| **type**     | string | X         | a type of chart to render. See the [Chartkick documentation](https://github.com/ankane/chartkick#charts) for the available types. |\n| title        | string |           | a title for your widget.                                                                                                          |\n| subtitle     | string |           | a subtitle for your widget.                                                                                                       |\n| refresh_rate | number |           | how often should the widget fetch and re-render data, in seconds. By default, it will not refresh automatically.                  |\n| style        | string |           | an optional space-separated list of CSS classes to apply to your widget. Current option is 'wide'.                                |\n\n\n## License\nThe gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreesteph%2Fwatchdog","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffreesteph%2Fwatchdog","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffreesteph%2Fwatchdog/lists"}