Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft: Exploring how Rails examples could be added for each of the components #3538

Draft
wants to merge 26 commits into
base: main
Choose a base branch
from

Conversation

frankieroberto
Copy link
Contributor

This is a proof-of-concept to demonstrate how the GOV.UK Design System website might be updated to include examples of how to use the Ruby on Rails implementations of the components.

This would be especially helpful for developers who may be translating prototypes built using the Nunjucks macros into a production service built using the Ruby on Rails framework.

The Rails implementation currently has documentation on two different websites: GOV.UK Form Builder for Ruby on Rails (for the form-based component) and GOV.UK Components for Ruby on Rails (for those not related to forms). The Ruby implementations were created by developers at the Department for Education, but are now maintained by a cross-government community, and are in widespread use in production services across government (including within GOV.UK Forms).

This proof-of-concept proposes a way of integrating the Rails examples within the GOV.UK Design System website, whilst making it clear that this implementation is community-maintained, and linking out to the existing documentation websites for further details.

The Rails examples don’t have to be all-or-nothing. They can be gradually added for all the examples, and new components could be launched with the Nunjucks examples only, with the Rails ones coming later.

This could be launched a trial to gauge response from Rails developers.

Screenshot

Screenshot of the GOV.UK Design System page for Date input with a 'Ruby on Rails' tab added to the first example, which is open and showing code for the component written using the rails syntax

Things which might need to be considered:

  • How to make it clear that the rails implementation is community-maintained
  • Best way to link out for further details - link to individual pages on the docs websites?
  • The 'How it works' paragraph on each page referencing 2 ways to use the component would need to be updated (and currently this is duplicated across each page)
  • A linter for the Rails examples? Rubocop?
  • Something on the 'Production' page in the 'Get started' section?
  • Are the examples which rely on validations added to activerecord models clear enough?
  • The pagination component relies on the pagy gem - does this need any more explanation?
  • Anything else?

Copy link

netlify bot commented Feb 8, 2024

You can preview this change here:

Built without sensitive environment variables

Name Link
🔨 Latest commit c1e9f11
🔍 Latest deploy log https://app.netlify.com/sites/govuk-design-system-preview/deploys/65c5fcb2c7e5f10008ec2ab8
😎 Deploy Preview https://deploy-preview-3538--govuk-design-system-preview.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify site configuration.

* @param {string} componentName - Name of component
* @returns {string} URL - Link to documentation page
*/
exports.getRailsLink = (componentName) => {
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@peteryates @paulrobertlloyd this seemed like the simplest way to work out which page to link to - but open to other ideas!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Depends how far you want to go with this, but you could create 2 arrays, one for components, and one for form elements, then cycle through them:

const links = {}

const components = ['accordian', 'breadcrumb']
const formElements = ['character-count', 'date-input']
  
for (const component in components) {
  links[component] = `https://govuk-components.netlify.app/components/${component}/`
}

for (const formElement in formElements) {
  links[formElement] = `https://govuk-form-builder.netlify.app/form-elements/${formElement}/`
}

(Top of my head coding, may need tweaking). This way, you only need to update each array and 2 URL paths should any of those aspects change.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It's slightly more complicated as some of the components have the prefix /building-blocks/ or /helpers/ or /introduction/, plus there's a few mismatches (fieldset vs fieldsets) - but something like this could work!

I was initially going to just link to either of the 2 homepages – but I think direct linking to the relevant pages is valuable?

Not sure where we'd link for any Rails examples for the patterns though... Some of the styles (eg Links) need doing too.

@paulrobertlloyd
Copy link
Contributor

Question about nomenclature; these examples (mostly) don’t show Ruby on Rails code, but ERB templates, much as the ‘Nunjucks’ tab isn’t labelled ‘JavaScript’. I wonder if the tabs should be labelled more akin to:

  • HTML
  • Nunjucks (JavaScript)
  • ERB (Ruby)

I also wonder if you need to show the OpenStruct code in the checkboxes/radios/select examples, the link to the documentation should be fine.

@frankieroberto
Copy link
Contributor Author

Question about nomenclature; these examples (mostly) don’t show Ruby on Rails code, but ERB templates, much as the ‘Nunjucks’ tab isn’t labelled ‘JavaScript’. I wonder if the tabs should be labelled more akin to:

  • HTML
  • Nunjucks (JavaScript)
  • ERB (Ruby)

I wondered this too - however the examples do depend on Rails as well as Ruby, I think, and so they can't be used in an alternative Ruby framework like Sinatra.

Could use ERb (Ruby on Rails) but then that’s quite long? I also wonder whether the Nunjucks one would be "Nunjucks (Node.js)`.

Also wonder whether "Ruby on Rails" is more of a recognised term than "ERb" (and possibly the same for Node.js?) - in which case it might make sense to reverse the order?

I also wonder if you need to show the OpenStruct code in the checkboxes/radios/select examples, the link to the documentation should be fine.

I wasn't sure of this either. I was erring on the side of trying to make the examples as comparable to the Nunjucks ones as possible - but not always easy, especially with things like the error messages where the message would be defined elsewhere and not in the template.

@paulrobertlloyd
Copy link
Contributor

paulrobertlloyd commented Feb 9, 2024

Going by their GitHub repo (both owning organisation and description: ‘An easy to use but powerful templating system for Ruby’) ERB is a Ruby thing, not just a Ruby on Rails thing. Stepping out of my comfort zone here though.

@frankieroberto
Copy link
Contributor Author

Going by their GitHub repo (both owning organisation and description: ‘An easy to use but powerful templating system for Ruby’) ERB is a Ruby thing, not just a Ruby on Rails thing. Stepping out of my comfort zone here though.

Yeah, ERb is a Ruby thing - but the examples also depend on Rails, I think (especially for the form ones)? @peteryates?

@peteryates
Copy link
Contributor

Yeah, the components are built with ViewComponent, which describes itself as being

built to integrate seamlessly with Ruby on Rails.

The form builder is heavily tied to Rails stuff too.

Both can be used outside of Rails (in the guides, for example), but it's a bit of an uphill struggle.

@paulrobertlloyd
Copy link
Contributor

Ah, of course! Okay, how about then:

  • HTML
  • Nunjucks (Node.js)
  • ERB (Ruby on Rails)

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

3 participants