Small Project Walkthrough (Planets)

ryan · November 25, 2011

Lets see if we can get a quick-start tutorial going here. We'll start with something really simple and then work up from there. Tell me when something makes sense and when it doesn't and we'll adjust as we go.

My thought is that we'd make a tutorial that plays on the 'hello world' phrase and lists information about planets in the solar system, starting with Earth. To keep it simple, we'll assume that the basic site profile is installed, as that's what comes with ProcessWire (so there's no need to uninstall anything). But we won't start using any of it's files tat this stage. Instead, we'll start out by creating our own files.

STEP 1 – Create a template file

Create a new file called: /site/templates/planet.php, and copy+paste the following HTML into that file:

<html>
    <head>
        <title>Earth</title>
    </head>
    <body>
       <h1>Earth</h1>
       <h2>Type: Happy planet, Age: Millions of years</h2>
       <p>Earth (or the Earth) is the third planet from the Sun, and the densest and fifth-largest 
       of the eight planets in the Solar System. It is also the largest of the Solar System's  
       four terrestrial planets. It is sometimes referred to as the World, the Blue Planet, 
       or by its Latin name, Terra.</p>
    </body>
</html>

The above is just a plain HTML file with nothing specific to ProcessWire. We will use this as the starting point for our template, and we'll go back and modify it later.

STEP 2 – Add a template to ProcessWire

Login to ProcessWire admin and go to Setup > Templates. This page shows a list of templates currently in the system.
Click the Add New Template button. On the next screen that appears, you'll see it found your "planet" template file.
Check the box next to the planet template and click Add Template. You may ignore any other options that appear on this screen.

STEP 3 – Creating a page using your template

Your planet template is now in the system and ready to use, but it's not being used by any pages. So lets create a page that uses the planet template.

In the ProcessWire admin, click Pages in the top navigation. This is a site map if your page structure. We want to create a new page under the homepage, so click the new link that appears to the right of the home page.
The next screen has 3 inputs: title, name and template. Enter "Earth" for the title, and the name should populate automatically. For the template, select planet. Then click Save.
Now you have created a new page using the template that you added. You are now in the page edit screen and you should see your title field populated with "Earth". Click the View link that appears on this page edit screen. You should see the output of the HTML from step 1. Click the back button in your browser to return to the edit screen.

STEP 4 – Creating a new field

Now you know how to create a template and a page using that template. You could create more pages using the same template if you wanted to. But that wouldn't be particularly useful – this template file is just a static HTML file.

Lets make it dynamic by creating some fields and adding them to it. We are going to create 3 fields to represent the pieces of data that currently appear in our static template. These include the planet's type, age in years, and a brief summary. We will call these fields: planet_type, planet_age and planet_summary.

In ProcessWire admin, click Setup > Fields. This screen shows a list of fields currently in the system, most of which are general purpose fields for the basic profile. For the purposes of this tutorial, we are going to ignore those and create our own.
Click the Add New Field button. On the next screen, enter "planet_type" for the Name, select "text" as the Type, and enter "Planet Type" for the Label. Then click the Save Field button.
Now that your field is saved, you are on the Field Edit screen. At this point, your field is created and ready to be added to your planet template.
Optional:
While editing your field, click the details tab where you'll see a select box for Text Formatters. Select "HTML Entity Encoder" – this ensures that characters like "<", ">" and "&" will be converted to HTML entities and not confused as HTML tags. While not required, it's a good practice for text fields like this. After you've done that, click the Save Field button.

STEP 5 – Creating more new fields

In step 4 we created the planet_type field. Now we want to create the planet_age and planet_summary fields. So in this step, you'll want to do the same thing for the remaining two fields:

Create the planet_age field exactly like you created the planet_type field, but enter "Planet age in years" for the label.
Create the planet_summary field exactly like you created the planet_type field, but chose "textarea" as the Type and enter "Planet summary" for the label.
Note that a "textarea" field is just like a "text" field, except that it can contain multiple lines of text.

STEP 6 – Adding new fields to your template

Now that you've created 3 new fields, you need to add them to your planet template.

In ProcessWire admin, click Setup > Templates > planet. You are now editing your planet template.
In the Fields select box, choose planet_type, then planet_age, then planet_summary. You will see each added to the list. Cick the Save Template button.

STEP 7 – Editing a page using your template

Now that you have new fields added to your template, go back and edit the Earth page you created earlier and populate the new fields that are on it.

In ProcessWire admin, click Pages at the top, then click the Earth page, and click the edit button that appears to the right of it.
You are now editing the Earth page you created earlier. You should see the new fields you added, waiting for text.
Enter "Terrestrial planet" for Planet Type
Enter "4.54 billion" for Planet Age in Years
Paste in the text below for Planet Summary and then click Save.
Earth (or the Earth) is the third planet from the Sun, and the densest and fifth-largest of the eight planets in the Solar System. It is also the largest of the Solar System's four terrestrial planets. It is sometimes referred to as the World, the Blue Planet, or by its Latin name, Terra.

STEP 8 – Outputting dynamic data in your template file

While still in the page editor from step 7, click the "View" link to see your page. Note that it still says "Happy planet" for type (rather than "Terrestrial planet") and "Millions of years" rather than "4.54 billion years". That's because the page is still being rendered with just the static data in it. We need to update the template file so that it recognizes the fields we added and outputs the values of those fields.

Edit /site/templates/planet.php and replace the static text in there with tags like this, replacing field_name with the name of the field:

<?php echo $page->field_name; ?>

If supported by your server, you may also use this shorter format which some people find easier to look at and faster to enter:

<?=$page->field_name?>

Here is the /site/templates/planet.php file updated to output the content of the page using tags like the above:

<html>
    <head>
        <title><?php echo $page->title; ?></title>
    </head>
    <body>
       <h1><?php echo $page->title; ?></h1>
       <h2>Type: <?php echo $page->planet_type; ?>, Age: <?php echo $page->planet_age; ?> years</h2>
       <p><?php echo $page->planet_summary; ?></p>
    </body>
</html>

After making these changes, save your planet.php template file. Now view your Earth page again. You should see it properly outputting all of the content you entered on the page, including "Terrestrial planet" for Type and "4.54 billion years" for age. Any changes you make from this point forward should be reflected in the output.

STEP 9 – Creating more pages, reusing your template

For this last step, we'll create another page (for Jupiter) using the same template just to demonstrate how a template may be reused.

In ProcessWire Admin, click Pages and then click the new link to the right of the home page.
Enter "Jupiter" as the Title and select "planet" for the Template. Click Save.
Now that you are editing the Jupiter page, enter "Gas giant" for Type, enter "4.5 billion" for Age in Years, and copy+paste the following for Planet Summary:
Jupiter is the fifth planet from the Sun and the largest planet within the Solar System.[13] It is a gas giant with mass one-thousandth that of the Sun but is two and a half times the mass of all the other planets in our Solar System combined. Jupiter is classified as a gas giant along with Saturn, Uranus and Neptune. Together, these four planets are sometimes referred to as the Jovian or outer planets.
Click the Publish button and then View the page. You should now see your planet template being used to output the information for Jupiter rather than Earth.

CONCLUSION

In the above, we covered the basics of how to develop in ProcessWire, including the following:

Creating templates and their associated template files
Creating basic text fields and adding them to templates
Creating and editing pages that use your templates
Outputting the values of fields in template files

If all of this makes sense so far, I thought we'd follow up next with a tutorial to take this further:

Adding and outputting photos for each planet
Creating navigation that lists all the other planets that have pages in the system

…and we'd keep building upon the tutorial from there. If you all think this tutorial is helpful, then perhaps this can be a draft for a real tutorial we'll put on the site, so all of your help is appreciated in making this as good as it can be.

Biscuit · November 25, 2011

As for the Twitter module. Did you take a look at the screencast in this topic: http://processwire.com/talk/index.php/topic,281.0.html ?

Much of the time I'm at a location where I can't watch videos. I did watch a few posted to YouTube about ProcessWire...and found they either repeated simple steps over and over, or went too fast for me to figure anything out.

If you want the module to show in your sidebar, you can call the module using the following code into the sidebar section of the tempate. (in the default example section, this is in the head.inc file.):

$page->renderTweets("/url/to/page/you/just/created/")

Yep, I saw that in the comments of the module (though the example needs a semi-colon at the end).. Tried it, and it didn't work for me. Perhaps I should list all steps taken before asking questions in the forums, to save time.

Biscuit · November 25, 2011

Lets see if we can get a quick-start tutorial going here. We'll start with something really simple and then work up from there. Tell me when something makes sense and when it doesn't and we'll adjust as we go.

My thought is that we'd make a tutorial that plays on the 'hello world' phrase and lists information about planets in the solar system, starting with Earth. To keep it simple, we'll assume that the basic site profile is installed, as that's what comes with ProcessWire (so there's no need to uninstall anything). But we won't start using any of it's files tat this stage. Instead, we'll start out by creating our own files.

"Hello World" always works for me *grins* This looks awesome Ryan, I appreciate it, especially on a holiday weekend. I saw the Quick Start (in process) on the site yesterday (yeah, I promised myself I'd take this weekend off...we see how that went), though I'm not seeing it now/can't find it now.

Taking this tutorial for a spin now, thanks!

Biscuit · November 25, 2011

If all of this makes sense so far, I thought we'd follow up next with a tutorial to take this further:

Adding and outputting photos for each planet

Creating navigation that lists all the other planets that have pages in the system

…and we'd keep building upon the tutorial from there. If you all think this tutorial is helpful, then perhaps this can be a draft for a real tutorial we'll put on the site, so all of your help is appreciated in making this as good as it can be.

That was excellent, THANK YOU! Steps 4+ were where I was stuck on. And yes, you were right...now that I see how it works, it *is* far easier than I was making it out to be.

Thanks so much for taking the time to answer my questions! Now I'm off to tackle the navigation.

formmailer · November 26, 2011

Yep, I saw that in the comments of the module (though the example needs a semi-colon at the end)..

You're right. Fixed that in my post.

ryan · November 26, 2011

Thanks so much for taking the time to answer my questions! Now I'm off to tackle the navigation.

Great! Glad that was helpful. I'm thinking we'll have to setup a tutorials board here, as the request for tutorials has come up quite a lot, so would like to do more and more of these.

PedroCandeias · January 17, 2012

Thanks for the walkthrough. It really helped to grok the most basic aspects of ProcessWire. That said, I'm having trouble choosing the next tutorial. The other topics seem to focus on very specific aspects, there's none that flows naturally from this one. Maybe I should just read the docs instead.

diogo · January 17, 2012

You should, the docs are great. I printed them, and had a very nice time reading in the sun

ryan · January 17, 2012

I do need to make a follow-up tutorial, and am planning on it.

I think the best next-step in the documentation would be to read these, in this order:

http://processwire.com/api/templates/

http://processwire.com/api/selectors/

http://processwire.com/api/variables/pages/

http://processwire.com/api/variables/page/

PedroCandeias · January 17, 2012

Great, thanks for the tip!

DaveP · February 10, 2012

I am struggling with the easiest things! My initial problem is how do I get a 'clean' ProcessWire installation to start a project?

If there isn't (and there doesn't seem to be) a download without example data, what do I need to delete, and in what order (in both the admin backend and the /site/ folder)?

I am sure ProcessWire is right for at least one project I have in the pipeline, but (and this is surely down to me) I'm finding the learning curve very steep initially.

ryan · February 10, 2012

The default profile is meant as a clean starting point, though it's also not completely blank. For me, it is at least a much better starting point than nothing, but i know others may prefer something even less. In ProcessWire, you can't have a completely blank stating point because some built-in pages need templates and fields (like admin, home and 404). But here's how you can get to a more blank state:

1. Open the 'trash' page in the page list, then click 'move' to drag these 4 pages to the trash:

/about/

/templates/

/sitemap/

/search/

Then empty the trash. This will leave you with just your homepage, 404 page, admin, and trash … all of which are required in any PW installation.

2. Now you want to go to Setup > Templates. Delete the 'sitemap' and 'search' templates, unless you want to keep either one of them. Edit the 'basic-page' and 'home' templates and remove all the fields except for 'title'. Save.

3. Go to Setup > Fields, and delete all the non-system fields except for 'title'.

4. Delete all the files in /site/templates/ except for admin.php and home.php.

Following that, you are starting from the most blank state possible in ProcessWire. Now start creating your own templates and fields, and note that you'll very likely be re-creating the fields you just deleted --they are fields that tend to be needed on most sites. That's why I think it's a little better to start with the included profile and rename/replace things as you go--it saves time.

DaveP · February 13, 2012

That's great, thanks Ryan.

It's just me being set in my ways and having my own naming style for fields and page elements (includes and such) - that I have got used to from using more basic frameworks like CodeIgniter and such.

<edit>Followed Ryan's instructions, and there was a bit more deleting to do in Admin > Pages before it would let me delete Search, but now I'm where I (mistakenly? :- ) wanted to be.</edit>

ryan · February 13, 2012

It's okay to rename things too. Renaming a field is pretty straightforward, as you can do that right on it's main edit screen. Renaming a template can be done from the 'advanced' tab of the template editor. Renaming a page is done from the 'settings' tab of a page.

DaveP · February 14, 2012

Once I got over the hurdle of looking for complexity that wasn't there it's all starting to become really rather obvious.

Several times today I have sat looking at the browser just amazed at how easy ProcessWire makes things. Most of the time, the API is so intuitive that I've guessed the correct call!

In just a few hours I have the skeleton of a site, with a page hierarchy several levels deep, and it all just works!

Ryan, you're a genius!

ryan · February 15, 2012

Thanks DaveP-- Glad that you got up and running and are enjoying using ProcessWire! Your compliments made my day, especially what you said about "looking for complexity that wasn't there". I think we're all conditioned to look for complexity in CMSs because most of them are pretty darn complicated once you get beyond doing basic things.

If a CMS were a car, you'd have to know how to tune the engine, bleed the brakes and adjust the spark plugs before you could drive it. With ProcessWire we're trying to put you in the drivers seat rather than under the hood. Take development tasks that would be complex and make them a lot easier.

Ryan, you're a genius!

If you saw how many iterations all of this stuff has been through, you might say I'm a bit slow. Part of the reason ProcessWire is here is because I wasn't smart enough to be able to figure out how to get things done with the other CMSs.

97s · February 17, 2012

Hello everyone!

First, I just want to thank you for processwire and all your hard work.

I have a quick question that I figured would be ok to ask here, since its sort of a starter place for most people learning processwire like myself.

What is the recommended way to develop for a real project for processwire. So I usually develop locally then port everything to my server, but processwire is a bit different in that fact. It seems I just need to develop templates, stylesheets, js, and images locally. Then once I have all that together start working on the live server, as the fields and such don't carry over directly when I upload the files.

Is this pretty much how everyone else is developing with processwire? Or is there a better way?

Thanks!

-Joe

diogo · February 17, 2012

Hi 97s! Welcome to PW

Fields and such are on the database, while the other things you mentioned are files.

You can install PW locally, and then export your database and copy all the files to server without forgetting the .htaccess. All you have to do is check your permissions again, and change the database info on the config.php file. At least this is what I did until now.

You can also use the ProfileExporter module. But I never used it for this.

Soma · February 17, 2012

What diogo said pretty much sums it up. It's quite simple and works.

In many projects I work directly/remote on the server, most of the time it's a subdomain like dev.domain.com, once ready to go live it's just a matter of transfering or switching dns. There's no "best" way, its always individual to the one developing. I also have a setup on projects, where I can transfer files and DB using shell and rsync from live to dev install and vis versa. It can be handy if you want to do major tasks on the site and don't want to break live site.

apeisa · February 17, 2012

With every software that alters database tables (like PW, Drupal etc) there is always the problem when deploying from dev to live. Initial migrate is easy, since you can just export whole database (or use exporter module), but after that it gets trickier. If you add code to your development version - that is easy one, but if you add fields/templates or change their settings then you need to add those same changes to your live site also.

I think current "best practice" is just redo your changes manually, before updating your code. Mostly those are minor changes so not a huge problem. Ryan is also planning for a tool to import & export whole templates and their fields easily, which should make bigger changes also easier.

97s · February 18, 2012

Thanks for the awesome replies.

I pretty much am going to stick to just building a static html/css/js site, then once I have that how I like it, I will move to a dev.yaddayadda.com remote server for building templates and fields, cause it just doesn't make sense to redo things twice.

I was just wondering if there was something I was missing that might have made it quicker, since processwire is so awesome.

It appears this forums are equally as awesome as well!

Thanks for the help.

statestreet · February 21, 2012

An idea for part two of the planets tutorial:

Planet type could be a great place to introduce relational page fields. This might also help cement the idea of just what a page can be in ProcessWire.

ryan · February 22, 2012

Planet type could be a great place to introduce relational page fields. This might also help cement the idea of just what a page can be in ProcessWire.

Good idea, I will plan to do that.

simkamsan · March 26, 2012

Dear Ryan,

Thank you very much for this CMS, it really make me wonder that it is difference from other CMS that easy to custom filed after i read and learn from you.

Thanks for work hard, I love this CMS maybe my next project will move to processwire.

Andy

ryan · March 27, 2012

Welcome to the forums Andy and thanks!

Sign In

Small Project Walkthrough (Planets)

Recommended Posts

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Link to comment

Share on other sites

Create an account or sign in to comment

Create an account

Sign in

Recently Browsing 0 members