Table of Contents
Table of Contents
PUMA 4.1 is a combination wiki and content management system. By now, you've installed the database and your site/ directory, and are ready to begin creating content. This document will take you on a guided tour through PUMA, including page creation, editing, and uploading files.
PUMA 4.1 uses a new design to make creating, editing, and revamping your site much easier than in previous versions. It includes better user administration, as well. So, let's begin our guided tour.
Table of Contents
To begin, load up the main page.
PUMA's default main page
The base site design is rather sparse, as you can see. PUMA uses a new templating system, smarty, to divide content from presentation. This allows you to more easily change the look and feel of your site without changing the underlying code; see the Advanced section for more information on that.
The main components to the page are the linkbar (1), the page title (2), and the page's location in the site hierarchy (3). The site hierarchy is new to PUMA 4; we'll discuss it in a minute.
Right now, though, we can't do anything, not even edit the main page! This is because we haven't logged in yet. Let's do that now by clicking on 'Login' on the linkbar.
You'll notice that there is a link for users to create their own accounts. This can be changed to only allow administrators to create accounts. See the advanced section for more details.
The default installation has a user, admin, and the password is `password'. Go ahead and log in now.
The Login Page
Once you have logged in, you'll be taken to your user preferences page. From here, we can change the password for the `admin' login. You should do that now by clicking `Change your password' and following the directions there.
Once you've finished with that, go ahead and return to the Home page by clicking 'Main Page' at the top of the page.
You'll notice that we now have a new option on the bottom of the page - `edit'.
The Home Page after logging in
Let's put some content on the Home Page. Click the (edit) link.
This will bring up the PUMA Editor, which acts just like a regular text editor with some PUMA-specific additions. You could also change the page's title here. For now, type in some sample text, and click `Preview Changes', which will show how the text will look on the page. Since this is just an example, go ahead and click `Save Changes'. You'll be returned to the page with a message telling you whether or not the changes were successful.
The Edit Page with a Preview
If you had made some changes, but decided that you didn't like them after all, you could click `Cancel Changes' to leave the editor and return to the page you were editing.
In PUMA, each page must be created and put into the site hierarchy before it can be edited or even linked to. How, then, can we create new pages? PUMA has a set of administrator controls to administer pages, users, and more. Let's go to the page list now by clicking on the `Pages' link.
The page list shows every page in your site. Each page, except the Home Page, has a parent page. To create new pages, simply click on the `new subpage' link on the page you'd like as the parent. This will take you to a page where you can name the new page, which will then be created.
The Page List
Go ahead and create a new subpage of the Home Page now. I've titled mine `About Us'.
Now, we could create new subpages for `About Us', perhaps one for each member of the team, and each of those pages could have many subpages as well. Don't get carried away, though! After a few levels, it becomes much harder to navigate through a site.
You'll notice that there are several other options. (del), of course, deletes the page--and all its subpages! (move) allows you to change the page's parent, moving it around in the hierarchy. (edit) will allow you to edit that page, as you'd expect. (history) shows you how the page looked after each revision, in case you accidentally deleted some content that you wanted to keep.
The Page List with a new Subpage
There are two special links as well: (new forum) and (new reservation). These are PUMA Plugins, and they're special subpages that appear on the page that they're attached to. Each page may have only one (or none) of each plugin. Go ahead and click (new forum) for the home page. You'll see it show up in the page list. If we return to the home page, there's now a 'forum' section at the bottom.
You'll also notice that there's a link to `About Us', underneath the page's title. This is part of PUMA's built-in navigation system; all pages have links to their immediate children (excluding Plugins) and all their ancestors (parent, parent's parent, etc). Going to the `About Us' page shows this.
About us links to its parent, home page
Users can create posts to discuss a page that contains a forum by clicking on the `New Post' link in the forums section, and can reply to other users' posts. Administrators can determine what permissions are required to read or post to the forum by using the `Change Permissions' form at the bottom. They can also delete all posts in a forum, or delete specific posts.
The home page with a forum on it
With reservations, you can make a new page describing an event, and then invite users to come. Users can enter their contact information (which they will need to confirm via email), and administrators can view (and delete!) the list of users who have reserved and confirmed, as well as add new reservations themselves, confirm users and resend the user's reservation confirmation email.
Users can enter their own information with the reservations plugin.
Administrators can review the reservations list
Puma's newest plugin, the eBook plugin, is a little different from the others. The eBook plugin takes a series of pages, and, based on their heirarchy, returns a book-like interface, including page turners that occur at the top of the page. Let's take a look at how it works.
A page with an ebook.
First things first. We need to create a page that will serve as the portal to the ebook. This is just a regular page, so go ahead and create a subpage of the main page.
Next, click on the ebook plugin icon: 
. This will automatically create an ebook page.
Now, because the ebook plugin looks at all the pages below an ebook page to create the ebook, we need to put something underneath the ebook page for the plugin to work. Create a new page below the ebook page as usual, with a title, perhaps "Chapter 1".
Note
The plugin will always travel to the lowest possible 'leaf' in the page 'tree', displaying only the content of that page, so you should spend some time thinking about how you want to organize your eBook. If, for example, you want each chapter to be a page, then simply having pages below the ebook with titles 'Chapter 1', 'Chapter 2', etc. and the contents of the chapters will work fine. On the other hand, if you want to divide the chapters into sections, then you'd need to leave the content of the page 'Chapter 1' blank, and fill in the pages below it.To show the plugin's capability, we'll create a page beneath 'Chapter 1' and give it some content. Go ahead and do it now. I've named my page "Beginnings". Create another page underneath 'Chapter 1', create a 'Chapter 2' and create a page beneath it. You can see my ebook below.
An ebook.
When we navigate to the page that contains the ebook, in this case the poorly-named 'asd', we can navigate around the pages using the page turners. We can go to the beginning of the next chapter by using the page turners around 'Chapter 1', and when we reach the end of Chapter 1's subpages, we can go straight to the first of the subpages beneath Chapter 2.
The order of the subpages determines their order of presentation in the ebook. You can move a page up or down using the up and down arrows in the actions list.
An ebook page, with page turners.
Note
Although you can create ebooks (and reservations, etc) beneath pages in ebooks, they won't show up as ebooks; in fact, they won't show up at all! However, Puma's ebook plugin currently supports forums for each page of an ebook. You don't have to create these forums using the page list; ebook pages will contain a link to create one if the forum hasn't already been created, or the forum itself if it exists.The last feature of the ebooks plugin to demonstrate is the 'Table of Contents'. The ebook plugin will automatically generate a table of contents if you create a page named 'Table of Contents' (note the capitalization; this must be exact). It's not necessary to put anything on this page; it will generate the contents of its parent page; in this case, the ebook. You could put it beneath a chapter to provide a table of contents for the chapter, as well.
A table of contents.
Now, lets take a look at some of the extra features in the editor. Click (edit) on the home page again. In addition to having what you would expect to find--italics, bold, left justification, etc.--PUMA's editor has built-in functions to help you add resources, such as pictures, and find pages and insert links to them.
First, let's try out the PagePicker.
Click on the `PagePicker' link. 
The page picker lists all pages that currently exist - with a short excerpt from the page - and will automatically insert the correct link for you. Note that in this example, we only have two choices: the `About Us' page or the `Home Page'.
The PagePicker dialog
Click on `About Us', which will automatically fill in the rest of the options for you. We can change what the link text will look like in the next box. Let's change it to just `About'. We can now click on `OK' to insert the link, or cancel to exit out. Click OK.
When we save the page, the link will be there, correctly pointing to the page that we want. Of course, since `About Us' is a child of the home page, this wasn't strictly necessary, but it can be useful to place links in context on the page.
Note
PUMA's pages are stored internally by the page id (you may have noticed this in your browser's address bar already). This means that you can rename pages, change their position in the hierarchy, and even have pages with the same title without worrying about a name conflict or broken links!The editor also has a built-in character map and international keyboard. 
They function fairly standardly, and will not be discussed further here.
The Character Map
Suppose that we wanted to add a picture to the home page (or any other page, for that matter). How could we do that? We use the ResourceUploader and the ResourcePicker. 
Click on the ResourceUploader first.
The `Nickname' is a short name to describe the resource--which can be nearly any type of file, not just an image--that you are uploading. Multiple files can have the same nickname; it is solely for your use. The `Description' is for a better description. You can click browse to pick out your file on the disk. When you're ready, click `Upload' to upload the file. If the upload is successful, you will get a message saying so.
The Resource Uploader Dialog
You can upload more files or click `Cancel' to return to the editor.
Let's insert the image we just uploaded. Click on the ResourcePicker. The Resource Picker will find all resources associated with a particular page so you can attach them to the page. Images are displayed in the page itself; others are linked.
You can select the resource you want from the dropdown.
The Resource Picker Dialog
The description will automatically change based on which resource you have chosen. Select the desired resource, and click OK. The ResourcePicker inserts the appropriate code into the editor.
Go ahead and save the changes to see the result. As you can see, the image has been inserted.
The page now has the chosen resource!
Finally, we should log out of PUMA for security. Click on the `admin' link in the linkbar to go to the user preferences page. From there, click log out.
Table of Contents
PUMA now uses a templating system, Smarty, to handle page display. Smarty templates consist of a combination of HTML and pseudo-PHP code.
You can get a feel of how these templates are used by looking in the (puma)/contrib/smarty/templates directory. In general, you shouldn't change any templates besides the (admin-)header.html, and (admin-)footer.html, because the other templates provide important navigation links.
The best way to change your site's look is to style it using CSS, or "cascading style sheets". Nearly every part of PUMA's default templates contains a class type that you can use to change the look of your site.
Any new templates or CSS files that you use should be put into your (puma)/site/ directory. PUMA will search there for templates first, and then, if any are not found, check the default templates directory.
When you're logged in to an account with administrator privileges, you'll see a toolbar at the top. Click on `Users' to bring up the user list.
The userlist
Here, you can review all the users, and perform various tasks, such as changing the user's email address and confirm their account.
Note
Don't remove the admin or anonymous users! They are installed by default and PUMA needs them to function properly.You can also create a new user by clicking on "create new user". This link gives you more control over creating a user than non-admins. You can set their initial permissions level, password, and even whether they've confirmed their email address. (This is useful for creating a non-admin account to use for everyday page editing).
Table of Contents
Puma's plugin architecture is straightforward. When Puma retrieves a page, it checks the page_type of that page's children. If one (or more) of the child pages' page_type is NOT `html', then Puma attempts to include `/path/to/puma/plugins/{page_type}.inc'. If this file is not found, Puma throws an error, but if it is found, then Puma attempts to run the function `plugin_{page_type}', and then assigns the return value of the function to the Smarty variable {page_type}.
plugin_{page_type} is passed three variables: the $REQUEST array, the Page object for the child page, and the current User object. Global variables (such as configuration values) can be accessed as usual using the `global' statement
So, for example, suppose we had a plugin `webcomic' that displayed a daily webcomic. If we had a page, perhaps the title of the webcomic (``Puma Adventures''), then when we navigated to ``Puma Adventures'', the following would happen:
First, Puma loads and stores the ``P.A.'' page, containing a description of the comic.
Next, Puma checks ``P.A."'s subpages for plugin pages. It finds three pages: one with page_type `html', one with `forum' and one with `webcomic'.
Puma tries to include `/path/to/puma/plugins/webcomic.inc', and it runs the function `plugin_webcomic', storing the result in the Smarty variable `webcomic'.
Then, Puma tries to include `/path/to/puma/plugins/forum.inc', and it runs the function `plugin_forum', storing the result in the Smarty variable `forum'.
Note
Puma loads the plugins in the order that the pages are retrieved from the database. This is, in principle, unordered for plugin pages, so your plugin should not rely on any other plugin running before or after it.
At this point, Puma hands everything off to Smarty. For your plugin to show up when viewing the page, you need to add it to your site/templates/page.view.html file.
Puma is under development, and more information can be found at pumacms.com
You can also follow along in the creation of a plugin: Plugins by Example: the eBook Plugin