hazdev-template/docs/embedding.md

Template for HazDev web sites.

Embedding the hazdev-template in another project
================================================


<pre><code>npm install grunt-connect-rewrite --save-dev
npm install hazdev-template --save-dev</code></pre>


## Gruntfile configuration

NOTE: Plus (+) characters are added to the beginning of lines to highlight lines
being added to the gruntfile, but are not part of the content that should be
added.

Configure php include path, by updating the mountPHP middleware function:

<pre><code>var mountPHP = function (dir, options) {<strong>
+  options = options || {
+    '.php': 'php-cgi',
+    'env': {
+      'PHPRC': process.cwd() + '/node_modules/hazdev-template/dist/conf/php.ini'
+    }
+  };</strong>
  return gateway(require('path').resolve(dir), options);
};
</code></pre>

### NOTE: This overrides the default php configuration
This may include custom extensions or other PHP settings, these should be
re-added to the php.ini file that is loaded from the template.
For example, to add the PDO Sqlite and init_curl extensions:
<pre><code>
  extension_dir = C:\php55\ext
  extension = php_pdo_sqlite.dll
  extension = php_curl.dll
</code></pre>

#### Configure grunt-connect-rewrite module:

In each grunt task that uses connect, add configureRewriteRules task before any
connect:

<pre><code>grunt.registerTask('default', [
    'clean:dist',
    'compass:dev',<strong>
+   'configureRewriteRules',</strong>
    'connect:test',
    'connect:dev',
    'open:test',
    'open:dev',
    'watch'
]);
</code></pre>

At top of Gruntfile, add this:

<pre><code><strong>+ var rewriteRulesSnippet = require('grunt-connect-rewrite/lib/utils').rewriteRequest;</strong>
</code></pre>


In the connect section, add a rules property to configure template rewrites; add
the rewriteRulesSnippet middleware and mount the node_modules folder

<pre><code>connect: {
    options: {
            hostname: 'localhost'
    },<strong>
+   rules: [
+           {
+                   from: '^/theme/(.*)$',
+                   to: '/hazdev-template/src/htdocs/$1'
+           }
+   ],</strong>
    dev: {
            options: {
                    base: '<%= app.src %>/htdocs',
                    port: 8080,
                    middleware: function (connect, options) {
                            return [
                                    lrSnippet,
                                    mountFolder(connect, '.tmp'),
                                    mountPHP(options.base),
                                    mountFolder(connect, options.base),<strong>
+                                   rewriteRulesSnippet,
+                                   mountFolder(connect, 'node_modules')</strong>
                            ];
                    }
            }
    }
 }
</code></pre>


## Site configuration

See [Site Configuration](siteConfiguration.md) for information on configuring a
template theme and site.  The effective DOCUMENT_ROOT is often `src/htdocs`, for
`_config.inc.php`, but may vary.