Single Pages
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.
Read on for information on controllers.
Comments:
So... looks like a Single Page is the best route. However I can't seem to get this work and I've searched for examples and don't see any.
I have a site where there is a registration system and a blog. Addresses are "site.com/blog/ and site.com/registration" respectively.
I created a blank blog.php file and put it in the single pages folder and added it per the instructions, but I am missing the next step. How do I get the contents of "site.com/blog" to load into the "single page" "blog.php" that I added to the site. Right now it is blank (my view does have the "print $innerContent" command.
I am hoping this is another simple syntax thing,.
Is there any way to customize the login page without rewriting the login controller to go to another page? I thought at first that the login page was getting wrapper'd by view.php in the Plain Yogurt theme, but then realized that it's going through the core theme. Can we change which theme wraps the single page in this case?
/config/site_theme_paths.php
it is very very confusing please can you help me and tell me how to proceed ???, thank you..
I am working on a website that will have a splash page with a map. From this map you can choose your destination and every destination will be slightly different form each other. so my logic says the splash page should be a Single page since it will be use just once. any ideas on this?
you could just treat the home page of your site as this landing page and let people directly link to deep pages if they wanted to.
Alas, not all goes as planned.
I am using a theme built from scratch. When I try to access a single page newly added by following steps 1. and 2., I get this error:
Warning: include(/srv/http-vhosts.d/my-site/www/themes/my_theme/view.php) [function.include]: failed to open stream: Nie ma takiego pliku ani katalogu in /srv/http-vhosts.d/my-site/www/concrete/libraries/view.php on line 738
Warning: include() [function.include]: Failed opening '/srv/http-vhosts.d/my_site/www/themes/my_theme/view.php' for inclusion (include_path='.:/usr/share/pear:/srv/http-vhosts.d/my-site/www/libraries/3rdparty:/srv/http-vhosts.d/my-site/www/concrete/config/../libraries/3rdparty') in /srv/http-vhosts.d/my-site/www/concrete/libraries/view.php on line 738
It seems that suddenly a file named "view.php" is expected in my theme's directory, however the theme is otherwise perfectly functional w/o this file. What should this file contain or how do I convince concrete5 NOT to require it?
http://www.concrete5.org/help/faq/view-php-in-theme/
I was able to set the theme name for each page in config/site_theme_paths.php but I think this not the proper solution.
Any thoughts?
http://www.concrete5.org/help/building_with_concrete5/developers/themes/specifying_themes_by_path/
but I don't understand why single_pages should refer to a different theme!
in it, but when opening it i just see a blank page. No errors, nothing. Any hint of what i'm doing wrong will be appreciated.
