se-n-se

Description

Source code and generators for http://www.se-n-se.eu/

Working on the source code

If you want to do some work on the website, you MUST read all this documentation!

Prerequisites

git of course ;-) (The best way to install git on Windows is by installing the GitHub client for windows. The shell that comes with it is also great for all your command prompt commands, like grunt update etc.)
node.js and npm
grunt-cli and bower. The easiest way to install both and throw in the fantastic yeoman as well is by issuing the following command in your command prompt or shell npm install -g yo

Getting started

Clone this repository:
- On Linux or OSX: git clone git@github.com:comweb/se-n-se.git
- On Windows: git clone https://github.com/comweb/se-n-se.git
Go into your local working directory: cd se-n-se
Run the first initialisation task:
- On Linux or OSX: bin/init
- On Windows: bin/init.bat

Foundations

Our HTML and CSS uses the following conventions and tools.

HTML5

We use valid, semantic HTML5. For a list of tags and their uses, consult the MDN HTML5 element list

CSS 3

We use valid CSS3. Check the MDN CSS reference.

For the organisation of our CSS we follow the SMACSS principles. Make sure to read the Categorizing CSS Rules chapter.

Frameworks and libraries

To make our lives a little bit easier we use Bootstrap and jQuery.

Naming conventions

No special characters or accents in names.
Folders and file names use underscores: _.
Class names, tags etc. use hyphens -.
Javascript variables use camelCase.

Technologies and tools

Grunt

Our build system makes extensive use of grunt, the javascript task runner. Grunt helps us build a complete website that we can publish from our source files. We have defined a number of tasks. Run these commands from your shell in the top folder of this project.

build: Build the website in our build directory (this is the default task). grunt build or grunt
dist: Build and minify the website in the dist directory. The contents of this directory can then be transfered to the server. grunt dist
update: Update the necessary packages. You must run this task every time that package.json or bower.json are changed. grunt update
watch: Leave this task running to automatically update the build whenever a source file is saved. If you have the LiveReload extensions installed and activated for your browser, your browser will automatically refresh every time a file is updated as well (no more F5 or cmd+R). To make sure that you have all files in your build folder, always run grunt build before running grunt watch

Handlebars

The templates we use are created with handlebars. Handlebars files are normal HTML with some special functions put between {{ }}.

Markdown

Markdown is an easy-to-read, easy-to-write plain text format that is easily converted to HTML. Use this handy cheat sheet for the syntax.

YAML front matter

YAML is a human friendly data serialization standard. Read this short introduction.

Our markdown and handlebars files can have variables or properties at the front. They are defined in the YAML format. They should be put between --- before any other conten. Like this:

---
YAML
---

Folder structure

bin: contains initialisation scripts that will set you up to work on the source code.
bower_components: the folder where bower installs its packages, like bootstrap and jquery.
build: this is where the generated version of the website is created when running grunt build or grunt. It is not minified and it it is intended for testing purposes only.
dist: this is where the generated and minified version of the website is created when running grunt dist.The contents of this folder are to be put on the webserver.
layouts: contains handlebars layout files. These will be wrapped around a content file.
node_modules: this is where node/npm installs its packages.
partials: this is where pieces of content are kept that can be reused within other pages or layouts. These files can be in markdown (.md) or handlebars (.hbs) format.
public: this is where static files like stylesheets and images are stored. This folder is copied integrally within the build folder.
src: contains the source files for our html pages. Every file in this folder will generate an html file in the build folder. These files can be in markdown (.md) or handlebars (.hbs) format.
.gitignore: list of files that git will not put in source control.
bower.json: packages that bower should install.
Gruntfile.js: this is where the magic happens. It contains all the jobs that are needed to generate the actual website from the source files.
package.json: packages that npm should install.

The files

src/index.hbs

This is the main source file for the index.html homepage of the website. It includes a number of partials to keep the file down to a convenient size: navigation, welkom and se-n-se.

Every domein also has its own partial: administratie_en_handel.hbs, gezondheid_en_maatschappij.hbs, kunst.hbs and techniek_en_wetenschap.hbs.

Because it is unique, this page specifies its own layout. It does not need an external layout file.

partials/domeinen/*.hbs

administratie_en_handel.hbs, gezondheid_en_maatschappij.hbs, kunst.hbs and techniek_en_wetenschap.hbs

The domeinen partials aggregate the opleidingen that match it. Each domein has its own section with an article for each opleiding. This article contains the title, the summary and a link to the homepage for the opleiding.

src/opleidingen/**/*.md

The contents for the opleidingen pages. These are formatted as markdown with YAML Front Matter. The front matter must contain the following properties:

url: this is a bit of a hack, but this property must contain the url of the resulting html page: "opleidingen/<domein>/<filename>.html". STRING
title: the title of the page or the name of the opleiding. STRING
tags an array that contains at least one string with the hyphenated name of the domein. ARRAY of STRINGS
scholen: an array that contains a list of strings with the names of the scholen that have the opleiding. The strings should match the base filenames of the partials in partials/scholen: underscored and without file extension. ARRAY of STRINGS
summary: the first part of the text. It must be a little bit like a teaser. This is the text that is used on the homepage and also the first part of the text that is used on the page for the opleiding itself. STRING

The content is in markdown. The title and the first paragraph should not be part of the markdown. They are already included in the YAML front matter.

The first heading level should be h2. h1 is reserved for the page title.

partials/scholen/*.hbs

These files contain the addresses of the scholen and the dates and times of their infomomenten. The format used is html with the h-card microformat for the address and the h-event microformat for the infomoment.

layouts/opleidingspagina.hbs

This is the layout for the opleidingspagina's. It uses the content and properties specified in the src/opleidingen/**/*.md files.

lars-derichter / se-n-se