{"id":13852069,"url":"https://github.com/alphagov/govuk_admin_template","last_synced_at":"2025-05-08T22:50:39.064Z","repository":{"id":17013012,"uuid":"19776412","full_name":"alphagov/govuk_admin_template","owner":"alphagov","description":"[Deprecated] Styles, scripts and templates for building GOV.UK backend admin apps","archived":false,"fork":false,"pushed_at":"2025-02-21T14:33:37.000Z","size":1800,"stargazers_count":20,"open_issues_count":1,"forks_count":10,"subscribers_count":71,"default_branch":"main","last_synced_at":"2025-04-28T23:08:53.828Z","etag":null,"topics":["gem","govuk"],"latest_commit_sha":null,"homepage":"","language":"JavaScript","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/alphagov.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2014-05-14T11:08:38.000Z","updated_at":"2024-11-28T09:41:38.000Z","dependencies_parsed_at":"2023-02-17T04:31:12.869Z","dependency_job_id":"bba5fe01-952c-4267-963c-03d08f71327e","html_url":"https://github.com/alphagov/govuk_admin_template","commit_stats":{"total_commits":424,"total_committers":42,"mean_commits":"10.095238095238095","dds":0.5518867924528301,"last_synced_commit":"01331e892454bd0e3b6d782df0aabea4ad95379f"},"previous_names":[],"tags_count":78,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fgovuk_admin_template","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fgovuk_admin_template/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fgovuk_admin_template/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/alphagov%2Fgovuk_admin_template/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/alphagov","download_url":"https://codeload.github.com/alphagov/govuk_admin_template/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253160827,"owners_count":21863624,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","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":["gem","govuk"],"created_at":"2024-08-04T22:00:57.805Z","updated_at":"2025-05-08T22:50:39.043Z","avatar_url":"https://github.com/alphagov.png","language":"JavaScript","readme":"# GOV.UK Admin Template (DEPRECATED)\n\n\u003e **NOTE**: This project is deprecated. New GOV.UK admin applications should be built using the [layout component in govuk_publishing_components](https://govuk-publishing-components.herokuapp.com/component-guide/layout_for_admin). Projects outside of GDS can use the [GOV.UK Design System](https://design-system.service.gov.uk/) directly to build interfaces.\n\n---\n\nStyles, scripts and templates wrapped up in a gem for getting up and running with [Bootstrap 3.4](https://getbootstrap.com/docs/3.4/) based backend admin apps.\n\nThis gem provides (via a Rails engine):\n* jQuery\n* Bootstrap 3 standard styles and javascript — including HTML5 and respond.js shims necessary for IE \u003c= IE8\n* An admin layout with header and footer\n* A [lightweight javascript framework](JAVASCRIPT.md)\n* Admin design patterns available from `/style-guide` (when routes are mounted)\n* [CSS helpers and SASS variables](CSS.md) for the admin theme\n* GOV.UK user friendly date formats\n* Google Analytics tracking code (Universal Analytics), using the \"GOV.UK apps\" profile\n\n[Apps using this gem](https://github.com/search?q=govuk_admin_template+user%3Aalphagov+path%3AGemfile.lock) include:\n* [Contacts admin](https://github.com/alphagov/contacts-admin)\n* [Content tagger](https://github.com/alphagov/content-tagger)\n* [Maslow](https://github.com/alphagov/maslow)\n* [Publisher](https://github.com/alphagov/publisher)\n* [Search admin](https://github.com/alphagov/search-admin)\n* [Service manual publisher](https://github.com/alphagov/service-manual-publisher)\n* [Short URL manager](https://github.com/alphagov/short-url-manager)\n* [Specialist publisher](https://github.com/alphagov/specialist-publisher)\n* [Support](https://github.com/alphagov/support)\n* [Transition](https://github.com/alphagov/transition)\n\n## Usage\n\nFirstly, include the gem in your Gemfile, pinned to the appropriate version and run `bundle`:\n\n```ruby\n# Gemfile\ngem 'govuk_admin_template', '~\u003e 6.8'\n```\n\nAt the top of `application.scss` include the styles (this provides all the mixins and variables from the gem as well as from bootstrap — [bootstrap mixins](https://github.com/twbs/bootstrap-sass/blob/v3.4.1/assets/stylesheets/bootstrap/_mixins.scss)):\n```css\n/* application.scss */\n@import 'govuk_admin_template';\n```\n\nIn `application.html.erb` after any content blocks you want to include, render the base template:\n```erb\n# views/layouts/application.html.rb\n\u003c%= render template: 'layouts/govuk_admin_template' %\u003e\n```\n\nThe [base template](app/views/layouts/govuk_admin_template.html.erb) includes:\n* Javascript and non-Javascript classes\n* Mobile friendly viewport\n* Bootstrap and jQuery javascript\n* IE HTML5 and respondjs shims, and HTML classes\n* header HTML\n* footer HTML\n\nYou will also need to include your styles and javascripts:\n\n```erb\n# views/layouts/application.html.rb\n\u003c% content_for :head do %\u003e\n  \u003c%= stylesheet_link_tag \"application\", media: \"all\" %\u003e\n  \u003c%= javascript_include_tag 'application' %\u003e\n\u003c% end %\u003e\n```\n\nNote that `jquery` and `jquery_ujs` are already imported by `govuk_admin_template`,\nso you should remove them from your `app/assets/javascripts/application.js`. This may\ncause your jasmine tests to fail, so you'll need to include `assets/govuk-admin-template.js`\nin your `spec/support/jasmine-browser.json` like this:\n\n```json\n\"srcFiles\": [\n  \"govuk-admin-template-*.js\",\n  \"application-*.js\"\n]\n```\n\nIt is recommended that the style guide is also made available within your app at the route `/style-guide`. Add this to your `config/routes.rb` file:\n\n```ruby\n# config/routes.rb\nif Rails.env.development?\n  mount GovukAdminTemplate::Engine, at: \"/style-guide\"\nend\n```\n\nThe gem source includes a [dummy app](spec/dummy) configured to behave like an app using the gem. If you have the gem checked out it can be run from the `spec/dummy` directory using `rails s`.\n\nFor Javascript usage, available modules and writing modules, see the [Javascript guide](JAVASCRIPT.md).\n\n### Configuration\n\nYou can configure the gem with a config block in an initializer:\n\n```ruby\n# config/initializers/govuk_admin_template.rb\nGovukAdminTemplate.configure do |c|\n  c.app_title = \"My Publisher\"\n  c.show_flash = true\n  c.show_signout = true\n  c.disable_google_analytics = false\nend\n```\n\n### Forms\n\nSome GOV.UK admin apps use the [Simple\nForm](https://github.com/plataformatec/simple_form) library for writing form\nmarkup. This repo contains a recommended configuration in\n`lib/govuk_admin_template/simple_form.rb`.\n\nTo use this configuration:\n\n0. Add `simple_form` to your Gemfile.\n0. Add an initializer in `config/initializers/simple_form.rb` containing the\n   following:\n\n```ruby\nSimpleForm.setup do |config|\n  GovukAdminTemplate.setup_simple_form(config)\nend\n```\n\nThis gem also provides an i18n file in `config/locales/simple_form.en.yml`.\nThis removes the need for this file to be present in the host project unless\nspecific customisations are required.\n\n### Content blocks\n\nThe gem [uses nested layouts](https://guides.rubyonrails.org/layouts_and_rendering.html#using-nested-layouts) for customisation.\n\n`content_for`     | Description\n---------------   | -------------\n`:app_title`      | Name of your admin application\n`:app_home_path`  | Path to the home page of your application, defaults to `root_path`\n`:content`        | Main content\n`:head`           | HTML to include in the `\u003chead\u003e` of your application\n`:page_title`     | Page title\n`:navbar_items`   | A set of HTML list items (`\u003cli\u003e`) forming the primary navigation\n`:navbar_right`   | Text to the right of the nav bar. Logged in user, sign out link, etc\n`:footer_top` (optional) | Footer content before copyright text\n`:footer_version` (optional) | Text indicating the release, eg commit SHA\n`:body_start` (optional) | Just after the `\u003cbody\u003e` tag\n`:body_end` (optional) | Just before the `\u003c/body\u003e` tag\n`:full_width` (optional, boolean) | Expand content to edges of screen.\n`:navbar` (optional) | Custom navbar content, overrides default navbar\n\nExample navbar_items:\n```erb\n# views/layouts/application.html.rb\n\u003c% content_for :navbar_items do %\u003e\n  \u003cli\u003e\n    \u003ca href=\"#\"\u003enavbar_item\u003c/a\u003e\n  \u003c/li\u003e\n\u003c% end %\u003e\n```\n\n### Date formats\n\nThe [gem includes](lib/govuk_admin_template/engine.rb) date and time formats which match the recommended styles for [dates](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style#dates) and [times](https://www.gov.uk/guidance/style-guide/a-to-z-of-gov-uk-style#times).\n\n```ruby\n# 1 January 2013\ndate.to_fs(:govuk_date)\n\n# 1:15pm, 1 January 2013\ntime.to_fs(:govuk_date)\n\n# 1 Jan 2013\ndate.to_fs(:govuk_date_short)\n\n# 1:15pm, 1 Jan 2013\ntime.to_fs(:govuk_date_short)\n\n# 1:15pm\ntime.to_fs(:govuk_time)\n```\n\n### Environment indicators\n\nThe gem includes default styles for development, integration and production. This includes a coloured environment label, a coloured strip beneath the main navigation and a coloured favicon. They are based on two variables that are set at deploy time (if they aren’t set no indicator will be shown).\n\nThe following should be set within an initializer:\n\n```ruby\n# used for the classname and favicon\nGovukAdminTemplate.environment_style = [integration|production|development]\n\n# used for the human readable label\nGovukAdminTemplate.environment_label = [Integration|Staging|Production|Development]\n```\n\n## Flash messages\n\nTurn on flash messages in the config:\n\n```ruby\n# config/initializers/govuk_admin_template.rb\nGovukAdminTemplate.configure do |c|\n  c.show_flash = true\nend\n```\n\nUse like this:\n\n```ruby\n# app/controllers/my_controller.rb\nclass MyController \u003c ApplicationController\n  def create\n    if thing.save\n      flash[:success] = \"Your thing has been created!\"\n    else\n      flash[:danger] = \"Sorry, it did not work.\"\n    end\n\n    redirect_to :back\n  end\nend\n```\n\nWe support `:success`, `:info`, `:warning` and `:danger`:\n\n![Flash types](docs/flash-types.png)\n\nYou can register your types to allow them to be used as arguments\nto `redirect_to`.\n\n```ruby\n# app/controllers/application_controller.rb\nclass ApplicationController \u003c ActionController::Base\n  add_flash_types :success, :info, :warning, :danger\nend\n\n# Now this works:\nredirect_to :back, success: \"Well done!\"\nredirect_to :back, danger: \"This didn't work.\"\n```\n\n## Development\n\n1. Clone the repository\n2. Run `bundle install`\n3. Run `yarn install`\n\nThe source files are in the [app](app) directory. Unlike other GOVUK frontend gems, there is no compile step. The app directory is included in the gem and hooked in as a Rails engine.\n\nWhile developing it may be helpful to see how the gem will render. The dummy app at [spec/dummy](spec/dummy) is configured to act like an application using the gem and can be started from that directory using `rails s`. Changes will show immediately. The tests also run against this app.\n\nThe dummy app’s rake tasks have been loaded into the gem’s task list under the namespace `app` for convenience – e.g. `bundle exec rake app:assets:precompile`\n\n### Running tests\n\nThe default rake task runs all tests:\n```\nbundle exec rake\n```\n\nLayout and nested layouts are tested using RSpec and Capybara:\n```\nbundle exec rake spec\n```\n\nJavascript is tested using Jasmine and [jasmine-browser-runner](https://jasmine.github.io/setup/browser.html). Tests can be run either in the browser or on the command line:\n```sh\n# browser\nyarn run jasmine:browser\n\n# command line\nyarn run jasmine:ci\n```\n\n### Testing against different Rails versions\n\nThe CI pipeline is configured to test this gem against multiple versions of Rails.\n\nEach Rails version has a corresponding Gemfile located in the [gemfiles](gemfiles/) directory. And the CI pipeline defines a [matrix of Gemfiles](https://github.com/alphagov/govuk_admin_template/blob/8f53865fa3d33f741642783f9bfcaefc201c3751/.github/workflows/ci.yml#L13) to test against.\n\nIt's also possible to run tests against multiple Rails versions locally.\n\n1. Run `export BUNDLE_GEMFILE=\"gemfiles/rails_X.gemfile\"` where `X` is the version to test against.\n  This tells Bundler which Gemfile to use.\n2. Run `bundle install` and then `bundle exec rake` as usual.\n\n## Publishing\n\nVersion bumps will automatically update RubyGems.org.\n\n## Licence\n\n[MIT License](LICENCE)\n\n","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphagov%2Fgovuk_admin_template","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Falphagov%2Fgovuk_admin_template","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Falphagov%2Fgovuk_admin_template/lists"}