Project Setup

• 2014-05-09 -- Made a few updates [sk]

Directory Structure

+ build                     # automatically generated output (don't modify directly)
              + data                      # external data (yml)
              + extensions                # middleman extensions (ruby code)
              + helpers                   # middleman helpers (ruby code)
              + source                    # development directory
                  + assets
                      + css                   # general stylesheets (according to SMACSS)
                          + helpers           # your mixins and helpers
                          + vendor            # third party stylesheets (convert to .scss)
                      + fonts                 # web fonts
                      + img                   # images for css (no content images)
                      + js                    # main javascript
                          + app               # application code
                              + components        # component related javascript
                              + plugins       # plugins unrelated to components
                              plugins.js      # require plugins
                          + lib               # your own shared code
                          + vendor            # third party libraries, frameworks, plugins
                          main.js             # the main javascript file
                  + components                # define your components
                      + {component_topic}    # components are organized in topics
                          + {component_name}  # separate directory for every component
                              _component_name.scss
                              _component_name.haml
                              component_name.html.haml
                  + docs                  # documentation (in markdown)
                  + layouts               # layout files
                  + pages             # pages illustrating site-templates
              

Middleman can't handle partials with dashes in their name when a collection is applied on them. For consistency reasons we should use underscores instead of dashes.

Development Index

There is a sitemap on the index page listing all HTML that gets built. It uses the frontmatter of middleman and needs a few settings.

---
              title: A 01 Home (obligatory)
              desc: Template for the homepage
              ticket: 2345
              ---
              

The title reflects the filename in lowercase and uses underscores for spaces: a_01_home.html

You can increase the number of categories anytime when needed.

To hide a page from the sitemap use:

---
              hide_from_index: true
              ---
              

Helpers

Because we don't want to spoil our templates with too much logic we extract it into helpers whenever needed. Don't forget to restart the middleman server after modifying helper methods.

Pages

Pages are templates as listed in the concept. We should use a naming that can be matched to the design pages.

Components

We adopt the SMACSS concept of components and extend it to units consisting of HTML(HAML), CSS(SCSS) and Javascript. This allows the team members to work separately on their components.

Directory and files are named according to the css-class of the component.

+ components
                  + teasers
                      + mega_teaser
                          mega_teaser.html.haml
                          _mega_teaser.haml
                          _mega_teaser.scss
              
              + js
                  + components
                      + teasers
                          MegaTeaser.js
              

The HTML fragment gets built like a normal page and needs to be named accordingly (no underscore at the beginning and html extension). It's used to demonstrate/illustrate the component and uses the styleguide layout.

Sub-components are stored within the components directory.

Use a special CSS-class to attach javascript to components (.js-teaser). This helps separating function and form.

Add meta information to your component:

---
              title: Main Stage
              desc: Top stage of the overview pages
              ticket: PRJ-2342
              ---
              

Asset Management

We don't use sprockets or bower for asset management.

• in Javascript we use requirejs
• in SCSS we use @import

Javascript

Components are the only Classes that should follow a certain structure. They have to provide two instance methods init and destroy. It's best practice to have them extend the BaseModule class. Please refer to sample code.

GIT

• When commiting work you did on a Ticket, write a reference to the ticket in your commit description. use the keyword: "refs" (ex: refs #3671)
• prefix remote branches with your name shortcut: e.g. "sk-mobile-nav", "gba-form-styling"
• delete a remote branch once it's merged into the master and you see its task as fulfilled
• always push your local branches to remote (at least if you're working on it for more than just an hour or so)

Release notes

When we change markup of a component or page that's been delivered to the backend, we want to let people know of it. We therefore add a note to the frontmatter describing the change. Be as specific as you can be with a few lines of text!

The frontmatter of a page or component will look like this:

---
              title: Main Stage
              desc: Top stage of the overview pages
              notes:
                - "2019-05-01 -- Change class ```component--header``` to ```component--title```"
                - "2019-05-01 -- PRJ-2342 Add attribute ```role="main"``` to wrapping container"
              ---
              

The syntax is YYYY-MM-DD -- [Ticket Nr], markdown text.

All notes will be collected and rendered in /docs/releasenotes.html.