Quickstart Guide

• Welcome
  • Installing Tapestry
  • Scaffold your first website
  • Project Structure
• Building & Previewing
  • Preview with PHP
  • Preview with Gulp Task

Welcome

This documentation aims to be a comprehensive guide to Tapestry; here we'll cover topics such as Installing Tapestry, starting your first website and Deploying.

Installing Tapestry

There are multiple methods of installing Tapestry, the preferred method of installing Tapestry is to download the .phar archive available from the projects github releases page here and placing it into your PATH.

Once downloaded unzip the tapestry-x.x.x.zip and place the tapestry.phar and (if on windows) tapestry.bin files in to a folder that is within your %PATH%. If completed successfully typing where tapestry on widows or which tapestry on linux will return the location path for where you have installed Tapestry.

To test that you have successfully installed Tapestry you can run tapestry --version in your terminal and you should see something similar to Tapestry version 1.0.10, environment local in return.

Scaffold your first website

Tapestry comes with a basic project scaffold built in, to initiate your first Tapestry project run:

$ tapestry init my-first-website

Tapestry will create the folder my-first-website within the current working directory and scaffold into it the default project directory structure.

The default project scaffold, for convenience comes with Laravel Elixir bundled in; before we continue you will need to run npm install to install it. For more information on the defined gulp tasks that come with Laravel Elixir, click here.

Project Structure

You should now within the my-first-website folder see the following generated file structure:

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

More details on the default Tapestry project structure can be found here.

Tapestry is “blog aware” out of the box so the majority of the default scaffold files are to do with displaying a collection of blog posts; you can find out more about creating your content here.

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.