Starting a new Website

• Start a new website
• Project Directory Structure
  • The source folder
  • Defined Gulp tasks
• Building & Previewing
  • Preview with PHP
  • Preview with Gulp Task

Start a new website

The quickest way of starting a new website with Tapestry is via the init command which scaffolds out a default project directory structure for you.

If you have Tapestry installed globally you can simply run:

$ tapestry init example-website

Tapestry will create the folder example-website and scaffold into it the default project directory structure. You will then need to run npm install to get the bundled gulp tasks.

Project Directory Structure

When you initiate a new project workspace, Tapestry will generate a basic workspace folder structure including the files package.json and gulpfile.js; the generated folder structure as of Tapestry 1.0.6 looks like the following:

webroot/
├── source/
|   ├── _assets/
|   |   ├── img
|   |   ├── js
|   |   └── less
|   ├── _blog/
|   |   └── 2016-01-01-hello-world.md
|   ├── _templates/
|   |   └── default.phtml
|   ├── _views/
|   |   └── blog.phtml
|   └── index.phtml
├── .gitignore
├── config.php
├── gulpfile.js
├── kernel.php
└── package.json

This generated workspace makes some assumptions on how you develop websites, namely that you use npm to install your web packages and the gulp task runner for executing tasks; more information on the tasks provided by the default gulpfile can be found here.

The source folder

Any folder prefixed with an underscore is by default ignored by Tapestry; while they are ignored by the main gathering process, custom content types defined within your workspace configuration are able to tell Tapestry how to use ignored folders; e.g _blog is a special folder configured and used by the default blog content type.

The folders _template and _views are special folders that contain your templates; it wouldn't make much sense for Tapestry to render these straight out to html so they are prefixed with an underscore.

The default behavior of Tapestry is to take any text file found within the source folder and attempt to generate html from its content. Binary files such as images are copied from source to the build directory with no additional processing.

Defined Gulp tasks

To aid in quickly getting started with using Tapestry the default workspace is generated with both a gulpfile.js and a package.json. To use the bundled gulp task runner for development you need to first install its node_modules via executing npm install.

Once complete you will gain access to the following gulp tasks:

• less
• imagemin
• browserfy
• exec
• browserSync

By default gulp will execute these in order and you will notice within your workspaces source folder the folders: css, js and img appear - these will contain the generated css, js and images.

There is also a watch task defined which will watch your workspaces source folder for any changes and execute the appropriate tasks; one additional benefit of this is the use of browserSync to display your changes in your browser. Running the watch task will prompt gulp to package up the assets found in the _assets folder and then open the generated website in chrome; each time you change a source file the relevant files will be re-generated and that browser window updated. This makes developing websites much easier as the task runner automates several tasks.

Building & Previewing

To build your Tapestry website you execute the build command within the my-first-website folder:

$ tapestry build

This will build the files found in the source directory and output them to the build_local, local is the default environment for Tapestry and the build command accepts a --env argument with which you can define the environment, e.g the following will output to build_development:

$ tapestry build --env=development

Previewing with PHP

In the interest of keeping Tapestry light, previewing your website with PHP is handled directly by PHP itself, this is done via the following command:

$ php -S 127.0.0.1:3000 -t build_local

PHP will then serve up the static pages at http://127.0.0.1:3000 while providing output akin to the below in to your console:

PHP 5.6.24 Development Server started at Thu Mar 23 15:42:36 2017
Listening on http://127.0.0.1:3000
Document root is F:\build_local
Press Ctrl-C to quit.
[Thu Mar 23 15:42:41 2017] 127.0.0.1:53118 [200]: /
[Thu Mar 23 15:42:41 2017] 127.0.0.1:53119 [200]: /img/staticgen.gif
[Thu Mar 23 15:43:01 2017] 127.0.0.1:53145 [200]: /documentation

Previewing with Gulp Task

The default project scaffold comes with Laravel Elixir, this provides out of the box tasks for less, imagemin, browserify and browserSync. Install via npm install and then gulp watch to preview your site.

browserSync will open a new browser window/tab automatically and reload the page every time a change is noticed. I have noticed one distinct bug with the file watcher on Windows in that it will not notice if you add a new file to the watched path - in that case I personally execute tapestry build in a separate terminal.