Single Pages are just like regular pages in a concrete5 site, with the following important differences:
Like the name implies, single pages are meant to be used one place in a particular site. For example, multiple login pages makes little sense.
Single Pages are not shown in a the page types list, because they are not page types (and they can't be added in more than one spot.)
Your custom code often relies on single pages living in a particular spot, at a particular path.
Single Pages are not, by default, contained within a themes directory. This is because single pages can be used within multiple themes.
Want an example of a single page? The concrete5 login page is a single page, and the perfect one: there's no need to add multiple login pages throughout a site. One will do. Furthermore, since blocks and multiple parts of concrete5 need to point to the login page, we need to rely on it being available at "/login", off the root of your site. Hence the single page, which exists at only one spot, and should not be moved.
The pages within the concrete5 dashboard are another example of single pages. We wouldn't want all the dashboard pages cluttering up our various themes, or our page types selector; however, since single pages are actual concrete5 pages, we can assign permissions to them, change their titles through the CMS, and even add blocks to them. Yes: single pages can contain block areas.
Adding a Single Page
Let's say we're using concrete5 to build a social networking tool, and we need a page that shows the logged-in user information about themselves. We want this page to display as
http://www.yoursite.com/index.php/my_profile/
We've already decided that this should be a single page because this page is very custom, and will have multiple pages pointing to it at its address.
So how does one add this single page?
Create an empty PHP page within the single_pages/ directory at the root of your site. Name it "my_profile.php." Whatever you name this page will be its path in the URL (e.g. "login.php" = http://www.yoursite.com/login"). Typically concrete5 naming conventions should be used here, so if you want to name something with separators in it, using underscores (e.g. "my_profile.php").
Sign in to the concrete5 dashboard, and go to Themes & Page Types > Single Pages. Find the "Add a Single Page" form at the bottom of the list, and enter "my_profile" at the bottom (or whatever the name of your single page.) Do not include ".php" in the field.
If all goes as planned, the page should refresh, and your single page will now be added at the root of your site. You can change its name, change its permissions, and add page attributes to it. The only thing you can't do is change it's handle, because the handle is derived from the filename.
Browse to your single page. You should see a mostly blank page. If you modify your blank PHP file you should see content appear on this page.
Customizing a Single Page's Appearance
Due to the typical business problems that they solve single pages are wrapped by the theme that you're in. This means you don't need to include header or footer information within your single page - it is already present. Single pages are wrapped by the "view.php" template for the current theme.
In a stock concrete5 site, try opening concrete/themes/default/view.php. This is the wrapper for all the single pages within the Plain Yogurt theme. Notice the <?php print $innerContent?> line? That's where all the single page content will be inserted within this template.
Want to change this? You can. If you need more flexible control over a single page within a particular theme, just include a file with the same name as your single page within the theme itself. That entirely file will be used as the single pages template, including the header, footer, etc... It can completely override the single page, too. (So, in our example above, once we have "my_profile" added as a single page, add "my_profile.php" to your active theme. This template will then be used instead of the single page.
Additional Notes
- Single pages do not all need to live at the root. Let's say you want to build out the following single pages, for an e-commerce system:
http://www.yoursite.com/index.php/cart/ http://www.yoursite.com/index.php/cart/shipping/ http://www.yoursite.com/index.php/cart/billing/ http://www.yoursite.com/index.php/cart/checkout/
You're going to need a single page for the cart view, the shipping view, the billing view, and the checkout view. Here's how your filesystem would look:
single_pages/cart/view.php
single_pages/cart/shipping.php
single_pages/cart/billing.php
single_pages/cart/checkout.php
Notice that the first item in our list, view.php, automatically maps to the "/cart" view. If we only wanted the cart/ view, and none of the views beneath it, we could've dispensed with the directory, and just created
single_pages/cart.php
You can use single pages to extend existing concrete5 functionality, like the dashboard. For example, say you want to add another page into the concrete5 dashboard for some custom business forms. You want this form to be available at
http://www.yoursite.com/index.php/dashboard/my_business_forms/
Just add
single_pages/dashboard/my_business_forms.php
And add it through the single pages interface in the dashboard. The new page should show up immediately in the dashboard navigation.
Adding Interactivity
As mentioned, Single Pages are great for those parts of your site that solve custom problems, and will not need to be reused. This is typically because these pages offer some interactivity, whether its a search form, a lengthy multi-step business form, or forms that let you add/edit certain objects.
The keyword here is "form." Single Pages are made for solving complex, interactive problems on your site. Once we have a single page in place, we'll inevitably need to process some form that's contained on it. That's why we have controllers.
See this how-to article for more information about how controllers interact with single pages.