Download the PHP package jrbarnard/proto without Composer

Front end templating framework

This project is made to help rapid development of front end website prototypes with a component based system and a non folder based route structure.

• It helps to speed up development by helping you create, update, move and delete pages. It does this by moving your entire page structure within a json file, then dynamically building your pages per request.
• It helps you split your pages into components using the highly extensible Twig templating language.
• It allows you to reuse templates and components, building the page up on the fly using the attributes you set in the json structure file.
• It dynamically builds navigation based off your structure if you want it, helping to make quick, non-breaking changes in one place as opposed to multiple in a more traditional prototype.
• It's extensible using the built in Extension API. - COMING SOON

Contents

1. Project setup
2. Usage
   • Structure general
   • Creating a template
   • Linking a page to a template
   • Going further with page content
   • Going further with templating
3. Menus
4. Development helpers
   • Clearing cache
   • Development twig functions

Project setup

Composer project install:

1. composer create-project jrbarnard/proto your-project-name --prefer-dist
2. This will run composer install for you. Or:
3. Clone / download the framework into your project directory.
4. Run composer install in the project root, if you don't have composer download here

After either:

3. Run a webserver and point it to the project directory
   • You can either do this by using Wamp, Mamp, Xampp, Vagrant etc.
   • Or by running the utility helper (only available in php 5.4+):
   • In the root

You will then have the example project set up! Take some time to look at the examples, how it's used and any comments.

--

Usage

You are free to use, extend, edit etc however you wish, however the generic usage to get you started is below.

Structure general:

The underlying structure of this tool is the routes you set up in your structure.json file, this is located in the root of the project.

The rough structure is:

Creating a template:

Create a file within the templates directory with a .twig extension, e.g location-detail.twig Most templates will extend a base or set of base templates, at the top of your page, ensure to extend the relevant one.

You can then hook into the extended templates blocks For example, in the example files base.twig it has a block called 'content', to hook into this do:

Linking a page to a template

Now you have a template you can link a page up to it.

• Go to your structure.json file in App/structure.json.

• Add a new page entry (route):

• If you now visit {domain}/new-page in your url you will see the template and text you just added

That's pretty cool, but it gets old real fast when you have multiple pages that would use the same template, but uses different text So you can add multiple pages that share templates:

• Add another couple of page entries (routes):

• Note we've added a new option called content, this specifies page / route specific content to be served along with the template, giving you a tonne of flexibility.

• Now if you reopen your new-template.twig template and replace the text with a twig placeholder:

• Now if you visit {domain}/new-page and {domain}/new-page-2 you will see the same template, but varying content

Going further with page content

You can pass content as json directly to the content attribute of a page in structure.json, however if you have lots of per page content with heavily nested data, it can get very very messy. A better way sometimes would be to seperate out your content to a file and then reference that.

• Create a json file in the content directory

• Go to the relevant page in your structure.json file and replace the content json with a string filename (minus the .json)

Going further with templating

Because this uses Twig for templating, it means you can use all available 'twigness' in your prototype to assist with your development, for full documentation visit: http://twig.sensiolabs.org/

Menus

Built into this are a few helpers to help generate common menus within your twig templates.

Within the example application are implementations of all of them.

For instance, for the top menu, we use the template part: templates/parts/topnav.twig:

It also comes with the following navigation examples:

• Breadcrumbs - templates/parts/breadcrumbs.twig
• Sidenav - templates/parts/sidenav.twig (NB: this only gets the siblings of the current page, you can also pass a number of levels to recursively iterate, like the full menu)
• FullNav / sitemap - templates/parts/fullnav.twig (NB: this doesn't honor the hidden flags you've set within your structure)

If you need further custom ones, you will be able to extend the built in navigation options soon.

Development helpers

To assist with development there are a few utilities and helpers you can use throughout prototyping.

Clearing caches

In order to speed up the load times of the prototype, we cache the twig templates so we don't have to render on every request. This however can cause problems when changing things, by default if you set your environment to dev, it will automatically prevent the twig cache, however if you change this, or you have old twig caches, it may become necessary to clear it.

To do so, go to the command line in the root of the project and run:

Twig dumper

The built in twig dumper is useful, however it isn't exactly easy to use / see the things you're dumping to the screen.

As a development dependency this project uses the symfony dumper and there are a couple of twig functions available to you.

In a twig template do the following:

Accessing variables set in your .env file

Your .env file is for setting environment variables in one central, non committed location.

This allows you to have different settings for general environment settings, third party services etc. depending on the environment where your code is.

For instance if you have an integration with twitter, you may want to have different settings or credentials depending on whether your prototype is currently local or on uat, so you can set these on the environments own .env file and therefore when your prototype boots there it will automatically get those details.

In order to gain access to your .env variables within twig follow the below: