2017 © Pedro Peláez
 

symfony-bundle static-site-bundle

CocurBuildBundle

image

braincrafted/static-site-bundle

CocurBuildBundle

  • Tuesday, January 7, 2014
  • by florianeckerstorfer
  • Repository
  • 3 Watchers
  • 4 Stars
  • 40 Installations
  • PHP
  • 0 Dependents
  • 0 Suggesters
  • 0 Forks
  • 1 Open issues
  • 1 Versions
  • 0 % Grown

The README.md

CocurBuildBundle

Static site generator bundle for Symfony2. Early development release., (*1)

Build Status, (*2)

Table of Contents

  1. Motivation
  2. Installation
  3. Configuration
    1. Generators
      1. File Generator
      2. Directory Generator
      3. JSON Generator
      4. CSV Generator
      5. YAML Generator
      6. Front-matter Generator
  4. Usage
  5. Author
  6. License

Motivation

The documentation for BraincraftedBootstrapBundle is a Symfony2 project, because it is used to test and demonstrate the bundles features. I no longer wanted to maintain (and pay for) another Symfony2 project on my server and instead move it to Github Pages. CocurBuildBundle creates static HTML pages from Symfony2 controllers., (*3)

Installation

You can install CocurBuildBundle using Composer. Add to your composer.json:, (*4)

{
    "require": {
        "cocur/build-bundle": "dev-master"
    }
}

You also have to add the bundle to your AppKernel.php:, (*5)

// app/AppKernel.php

class AppKernel extends Kernel
{
    public function registerBundles()
    {
        $bundles = array(
            // ...
            new Cocur\Bundle\BuildBundle\CocurBuildBundle(),
        );

        // ...

        return $bundles;
    }

    // ...
}

Configuration

  • enable_assetic: When this option is true the assetic:dump command is executed when building the site. If the option is not defined it will be activated if AsseticBundle is installed.
  • build_directory: The directory where the built site is saved.
  • base_url: The base URL of the static site. Useful when the HTML is not saved in the root directory. Most commands have an option to override this on an individual basis.
  • index_name: If a route doesn't contain a filename this value is appended to the route. The default value is index.html.

The default configuration looks like this:, (*6)

# app/config/config.yml
cocur_build:
    build_directory: "%kernel.root_dir%/../build/site"
    base_url: ''
    index_name: index.html
    generators: ~

Generators

If an action requires parameters you can use generators to load the parameters from various sources. The bundle comes with four default generators:, (*7)

  • File generator: Every line in a file is a parameter; can only be used with actions that require a single parameter
  • Directory generator: The name of every file or directory in a given directory is a parameter; can only be used with actions that require a single parameter
  • JSON generator: A file that contains an array of objects; each object represents the parameters for an action; can be used with actions that require multiple parameters
  • CSV generator: A file where each row contains the parameters of an action; must contain a header row that includes the parameter names; can be used for actions that require multiple parameters

Generators can be configured in your apps config.yml on a per-route basis., (*8)

File Generator

Parameters are generated from a file., (*9)

Required options:, (*10)

  • filename
  • parameter

In the following example we have a route acme_demo_page with the path /p/{page} and we want to generate the page parameter from a file called data.txt., (*11)

# app/config/config.yml

cocur_build:
    generators:
        page:
            route: acme_demo_page
            generator: cocur_build.file_generator
            options:
                filename: "%kernel.root_dir%/../data.txt"
                parameter: page

We require now the data.txt file that contains one parameter per line., (*12)

products
about
contact

CocurBuildBundle will render the following pages:, (*13)

  • /p/products
  • /p/about
  • /p/contact

Directory Generator

Parameters are generated from the names of files in a directory., (*14)

Required options:, (*15)

  • directory_name
  • parameter

In this example we have a route acme_demo_article with the path /article/{slug} and we want to render the page for every file in a directory., (*16)

# app/config/config.yml

cocur_build:
    generators:
        article:
            route: acme_demo_article
            generator: cocur_build.directory_generator
            options:
                directory_name: "%kernel.root_dir%/../articles"
                parameter: slug

The directory articles/ contains the following files:, (*17)

articles/
    ⊢ 2013-12-03-bootstrap-bundle-2-0.md
    ⊢ 2013-12-04-cocur-bundle-0-1.md

CocurBuildBundle will render the following pages:, (*18)

  • article/2013-12-03-bootstrap-bundle-2-0
  • article/2013-12-04-cocur-bundle-0-1

JSON Generator

Parameters are generated from a JSON file., (*19)

Required options:, (*20)

  • filename

Optional options:, (*21)

  • parameters: Only use these parameters to generate pages

Let's consider a route acme_demo_categorypage with the path /page/{category}/{page}. We require two parameters category and page that we want to generate from a JSON file called data.json., (*22)

# app/config/config.yml

cocur_build:
    generators:
        categorypage:
            route: acme_demo_categorypage
            generator: cocur_build.json_generator
            options:
                filename: "%kernel.root_dir%/../data.json"

The JSON file data.json has to contain an array where each element is an object with a category and a page property:, (*23)

[
    { "category": "foo", "page": "bar" },
    { "category": "foo", "page": "baz" }
]

CocurBuildBundle will render the following pages:, (*24)

  • /pages/foo/bar
  • /pages/foo/baz

CSV Generator

Parameters are generated from a CSV file., (*25)

Required options:, (*26)

  • filename

Optional options:, (*27)

  • delimiter (default value is ,)
  • enclosure (default value is ")
  • escape (default value is \)
  • parameters: Only use these parameters to generate pages

Now we want to render the route acme_demo_person with the pattern /person/{name}/{age}/{city} using a CSV file persons.csv., (*28)

# app/config/config.yml

cocur_build:
    generators:
        person:
            route: acme_demo_person
            generator: cocur_build.csv_generator
            options:
                filename: "%kernel.root_dir%/../persons.csv"

The CSV file has to contain three columns and a header row containing name, age and city., (*29)

"name", "age", "city"
"Florian", "27", "Vienna"
"Daniela", "22", "Vienna"

CocurBuildBundle will render the following pages:, (*30)

  • /person/Florian/27/Vienna
  • /person/Daniela/22/Vienna

YAML Generator

Parameters are generated from a YAML file., (*31)

Required options:, (*32)

  • filename

Optional options:, (*33)

  • parameters: Only use these parameters to generate pages

If we want to render the route acme_demo_person with the pattern /person/{name}/{age}/{city} we can also use a YAML file persons.yaml., (*34)

# app/config/config.yml

cocur_build:
    generators:
        person:
            route: acme_demo_person
            generator: cocur_build.yaml_generator
            options:
                filename: "%kernel.root_dir%/../persons.yml"

The YAML file persons.yml has to contain a list element for every person with a named property for every parameter., (*35)

-
    name: Florian
    age: 27
    city: Vienna
-
    name: Daniela
    age: 22
    city: Vienna

CocurBuildBundle will render the following pages:, (*36)

  • /person/Florian/27/Vienna
  • /person/Daniela/22/Vienna

Front-matter Generator

Parameters are generated from the front-matter of files in a directory., (*37)

Required options:, (*38)

  • directory_name

Optional options:, (*39)

  • parameters: Only use these parameters to generate pages

In this example we have a route acme_demo_article with the path /article/{category}/{slug} and we want to render the page for every file in a directory., (*40)

# app/config/config.yml

cocur_build:
    generators:
        article:
            route: acme_demo_article
            generator: cocur_build.front_matter_generator
            options:
                directory_name: "%kernel.root_dir%/../articles"

For example, the file articles/2013-12-03-bootstrap-bundle-2-0.md could look like:, (*41)

---
category: dev
slug: bootstrap-bundle-2-0
---
This is the rest of the file. Just some text.

CocurBuildBundle will render the following page:, (*42)

  • article/dev/bootstrap-bundle-2-0

Usage

The build command is the main command offered by CocurBuildBundle. It renders all pages and dumps the assets into the build directory., (*43)

$ php app/console cocur:build

The HTML code will be saved in the directory configured with cocur_build.build_directory., (*44)

Note: CocurBuildBundle can handle actions with parameters if a generator is configured for these routes., (*45)

When you use the build command, CocurBuildBundle uses the Symfony2 kernel to simulate a request to a page. The kernel is booted in the environment the command is invoked. If you want to build the pages for production, you need to build them in the prod environment., (*46)

$ php app/console cocur:build -e prod

If cocur:build is called in the prod environment the cache is cleared before the rendering., (*47)

You can remove all files from the build directory by using the clean command, (*48)

$ php app/console cocur:clean

Author

License

This bundle is licensed under the MIT license. For more information see the LICENSE file., (*49)

Bitdeli Badge, (*50)

The Versions

07/01 2014

dev-master

9999999-dev

CocurBuildBundle

  Sources   Download

MIT

The Requires

 

The Development Requires

by Florian Eckerstorfer

static site