Starting a new Website
- Start a new website
- Project Directory Structure
- Building & Previewing
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.
When you initiate a new project workspace, Tapestry will generate a basic workspace folder structure including the files
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.
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.
_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.
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
Once complete you will gain access to the following gulp tasks:
By default gulp will execute these in order and you will notice within your workspaces source folder the folders:
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.
To build your Tapestry website you execute the build command within the
$ 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
$ tapestry build --env=development
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 : / [Thu Mar 23 15:42:41 2017] 127.0.0.1:53119 : /img/staticgen.gif [Thu Mar 23 15:43:01 2017] 127.0.0.1:53145 : /documentation
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.