Partial structure defined

[sjmog]

OK gang, what do we think? Please read this before checking code

Recap of the main reasoning:

1. Non-developers can use an easy-to-use DSL to build pages using set molecules
2. Developers rarely have to CSS
3. It's suitable for moving to a form-based, then later drag-and-drop-based, interface builder.

   Top Level

Non-developers can build interfaces using a very easy syntax. Here is an example (the 'meet our grads' block) from homepage.erb:

<!-- BEGIN grads -->

<%= partial "components/molecules/media-component--with-slider", locals: {
    leader: "Meet",
    title: "Our Grads",
    body_copy: "We&rsquo;ve graduated over 300 beginners into their dream jobs as junior developers. Some were looking for a career change, others to define themselves.",
    cta: {
      text: "Read Grad Stories",
      link: "/graduates",
      type: "horizontal"
    },
    slider_content: [
      {
        content_type: "image",
        src: "images/test-assets/test-grad.png",
        orientation: "portrait",
        alt: "A test graduate, looking at the camera.",
        caption: "Firstname Lastname\nCohort of 2015\nNow a Junior Developer at CompanyName"
      },
      {
        content_type: "image",
        src: "http://placehold.it/400x600&text=400x600",
        orientation: "portrait",
        alt: "A gray box with the text '400x600'",
        caption: "Othername Lastname\nCohort of 2015\nNow a Junior Developer at OtherCompanyName"
      }
    ]
  } %>

<!-- END grads -->

Molecule partials are very specific. When a user renders a partial called media-component--with-slider, they know exactly what they're getting, and there is a standard set of attributes for them to fill in.

Bottom level

Developers can build new molecules using atoms. These atoms are very generic. Here is the cta-block atom, which renders any number of Calls to Action (buttons) in a supplied configuration:

<% # Includes any number of _cta quarks %>
<% component ||= "cta-block" %>

<div class="<%= component_classes locals.fetch(:parent, nil), component, locals.fetch(:modifiers, []) %>">

  <% ctas.each do | cta | %>
    <%= partial "components/quarks/cta", locals: {
      parent: component,
      text: cta[:text],
      link: cta[:link],
      modifiers: cta[:modifiers]
    } %>
  <% end %>

</div>

Any component (except molecule components) is rendered by including two main attributes:

1. The component's parent (a string), and
2. Any modifiers (an array of strings).

So, to render the cta-block above:

<!-- this will render the 'cta-block' atom, with a single 'cta' quark inside -->
<%= partial "components/atoms/cta-block", locals: {
  parent: "media-component__section", # If the parent is a media-component__section
  modifiers: ["left"], # Or any other modifiers
  # the following is an array of cta quarks (only one, here)
  ctas: [
    { 
      text: cta.fetch(:text, "Untitled"),
      link: cta.fetch(:link, "#"),
      modifiers: [cta.fetch(:type, "horizontal")]
    }
  ]
} %>

If you provide a parent and a modifiers array, the builder will include the correct BEM classes for you (see the ComponentClassesHelper in lib). If you don't include these, the BEM helper will still work and you will render the most generic form of a component.

Atom and Quark partials are very generic. They accept a wide range of (sensibly-named) attributes, and my next task will be to document them.

Between Molecules and other Components

Molecule partials (go check out components/molecules/_media-component--with-slider.erb) should:

1. Translate between the top-level, 'non-dev' attributes (which are concrete and easy to understand), and the more abstract component attributes detailed above, and
2. Provide defaults should a 'non-dev' forget to include an attribute when building a page.

OK, I think that's enough. If there's anything here that doesn't make sense, please grab me. As Roi will testify, this is easier to get your head round than it might seem, and it hits each point of the main reasoning well.

[leoallen85]

We've discussed and are all happy (as is Arfa) , although we're going to change the names to atoms -> groups -> templates. Me, Roi and Steve are going to work renaming and adding documentation and generally start turning this into something we can prototype for the beta site.

Awesome work Sam thanks for getting this done

[spike01]

I'm just being nitpicky with my comments! Otherwise I actually quite like where this is going.