2016: customized date-place styling.

[libreplanet-static.git] / 2016 / README.md

LibrePlanet 2016
================

This is the static HTML site for LibrePlanet 2016.  Read on for
instructions on how to setup your development environment.

The repository has a master (development) branch and a stable
(live) branch. To work on it, you'll edit your checkout of the
master branch until you are satisfied, push it to the master
branch on the Web server (<http://wiki-dev0.libreplanet.org>),
make sure it works well and make sure it works well. Then
you'll copy it over to your checkout of the stable branch,
then push that to the stable branch on the Web server
(<http://libreplanet.org>).

Setting Up Apache
-----------------

Apache is required in order to replicate the appearance of the website
on the live and staging servers on your machine. If you don't want to
install Apache, you can still work on the site, you just won't be able
to see what it looks like until you push to the remote.

Modifying Apache's configuration files and running its executables
typically requires root access.  So, you will most likely need to run
the commands below as the root user using `sudo`.

### Enable server-side include module

```
a2enmod include
```

If this doesn't work, you may not have Apache installed. Install the
package apache2 from your package manager.

### Create virtual host

Create a new file called libreplanet (libreplanet.conf for Apache 2.4) in `/etc/apache2/sites-available` with the following contents:

```
<VirtualHost *:80>
    ServerName lp2016.libreplanet.org
	DocumentRoot /path/to/libreplanet-static

	<Directory />
		Options FollowSymLinks
		AllowOverride All
    </Directory>
	<Directory /path/to/libreplanet-static>
		Options Indexes FollowSymLinks MultiViews
        Options +Includes
        XBitHack on
		AllowOverride All
		Order allow,deny
		# Directive needed in Apache 2.4
		allow from all
	</Directory>

	ErrorLog ${APACHE_LOG_DIR}/error.log
	LogLevel warn
	CustomLog ${APACHE_LOG_DIR}/access.log combined
</VirtualHost>
```

Replace all instances of `/path/to/libreplanet-static` with the full path to the root directory of your local
git repository.

### Enable virtual host

```
a2ensite your-virtual-host
```

Replace `your-virtual-host` with the name of virtual host file you made (in this case, libreplanet).

### Restart Apache

```
service apache2 restart
```

### Edit your hosts file

Edit your system's `/etc/hosts` file and add the following to the bottom:

```
127.0.0.1 lp2016.libreplanet.org
```

### Test

Visit <http://lp2016.libreplanet.org/2016> in your web browser.  If
everything is configured properly, you will see the LibrePlanet 2016
site, complete with header, sidebar, and footer.

Creating a New Page
-------------------

### Boilerplate

Add the following to your new page (it should remain commented out, as that is the syntax for SSI):

```
<!--#include virtual="/server/2016/header.html"-->
<!--#include virtual="/server/2016/banner.html"-->
<!--#include virtual="/server/2016/sidebar.html"-->
<!--#include virtual="/server/2016/footer.html"-->
<!--#include virtual="/server/2016/close.html"-->
```

This will include the header, banner, sidebar, footer and closing tags
saving you from duplicating HTML.

If JS is needed for a page, then create a file, containing the JS
includes, in `/server/2016/` & use SSI to include it in the page.

Use `/server/2016/boilerplate.html` to start a new page.

### Add Your Markup

Add HTML markup in-between the sidebar and footer includes.

### Enable SSI

Files that contain include directives must be marked as executable
otherwise Apache will not parse them.  The directive `XBitHack on`
enables this behavior.

To mark a file as executable, run:

```
chmod +x foo.html
```

Replace `foo.html` with the desired file name.

Schedule Markup
---------------

### Program Day

    <article id="DAY-program" class="program-day"> <!-- DAY program start -->
      <header class="program-day-header">
        <hgroup>
          <h2>Saturday, March DD
            <a class="btn btn-default btn-xs" role="button"
               data-toggle="collapse" aria-expanded="false"
               aria-controls="DAY-timeslots"
               href="#DAY-timeslots">
              &#x2193;
            </a>
          </h2>
        </hgroup>
      </header>
      <div class="collapse in" id="DAY-timeslots"> <!-- DAY-timeslots start -->
        <!-- Time slots come here. See next section (Time slot) -->
      </div> <!-- DAY-timeslots end -->
    </article>

Replace `DAY` by the day of the program (`sat` / `sun`).

### Time slot

#### sessions

        <article id="DAY-tsM" class="program-timeslot"> <!-- DAY-tsM start -->
          <header class="program-timeslot-header">
            <hgroup>
              <h2>TIME - Timeslot Description
                <a class="btn btn-default btn-xs" role="button"
                        data-toggle="collapse" aria-expanded="false"
                        aria-controls="DAY-tsM-sessions"
                        href="#DAY-tsM-sessions">
                  &#x2193;
                </a>
              </h2>
            </hgroup>
          </header>
          <div class="collapse in"
               id="DAY-tsM-sessions"> <!-- DAY-tsM-sessions start -->
             <!-- Sessions come here. See next section (Session). -->
          </div> <!-- DAY-tsM-sessions end -->
        </article> <!-- DAY-tsM end -->

Replace `DAY` by the day of the program (`sat`/`sun`) and `M` by time
slot number.

#### break

        <article id="DAY-ts-bM"
                 class="program-timeslot-break"> <!-- DAY-ts-bM start -->
          <header class="program-timeslot-break-header">
            <hgroup>
              <h2>TIME: Break</h2>
            </hgroup>
          </header>
        </article> <!-- DAY-ts-bM end -->

Replace `DAY` by the day of the program (`sat`/`sun`) and `M` by break
number.

### Session

            <section id="DAY-tsM-sN"
                     class="program-session"> <!-- DAY-tsM-sN start -->
              <header class="program-session-header">
                <h2>Session Heading</h2>
              </header>
              <!-- Session "always visible" Content -->
              <button class="btn btn-default btn-xs" role="button"
                      data-toggle="collapse" aria-expanded="false"
                      aria-controls="DAY-tsM-sN-collapse"
                      data-target="#DAY-tsM-sN-collapse">
                Details
              </button>
              <div class="collapse in" id="DAY-tsM-sN-collapse">
                <!-- Session Collapsible Content  -->
              </div>
            </section> <!-- DAY-tsM-sN end -->

Replace `DAY` by the day of the program (`sat`/`sun`), `M` by the time slot number and `N` by the session number.

Deploying to Staging/Live Servers
---------------------------------

A system of git hooks automates deployment to the staging and live
servers.  When you push to the `master` branch, the site is deployed
to <http://wiki-dev0.libreplanet.org/2016>.  When you push to the
`stable` branch, the site is deployed to <http://libreplanet.org>.

When you're happy with the state of the master branch and want to
deploy live, do the following:

```
git checkout stable
git merge master
git push
```

This merges the master branch with the stable branch, updates the
remote repository on the git server, and triggers a deploy to
<http://libreplanet.org>.

CSS and JavaScript
------------------

This site is built with:

* [Bootstrap 3.3.5](https://github.com/twbs/bootstrap/releases/download/v3.3.5/bootstrap-3.3.5-dist.zip)
* [jQuery 1.11.1](http://code.jquery.com/jquery-1.11.3.js)