template_********() info/samples

template_include()

template_includes()s do like they sound: they include something ;) Specifically, template_include() will get the identified file from either /templates/your_template/ or /templates/ and use any specified parameters as 'default' for anything in the included file that uses those particular params. Think "sidebar, footer" and you're close pretty close to how template_include is generally used.

template_includes()s make it easier to build your web your way by off-loading big chunks of code to a more-focused file, which are (of course) fully customizable. You can let the generic versions of various files in /templates/ do their thing, or copy one to your /templates/your_template/ folder and customize it as you see fit.

There are no $params to chase through template_include() because Quam Plures can't know what params the included file might need. The thing is though that if you include a file that uses $params for whatever reason, you can pass those values through template_includes().

You can also include your own custom file. Simply add the properly formatted template_include() tag to the appropriate file (usually a main or an incl) and add the actual file to your /templates/your_template/ folder.

When template_includes()s play nice they include files that close any html tags they open. You should make your template_includes play nice by writing included files that play nice :)

We have a handful of 'stock' files to make building your own template a little easier.

To customize any of these simply copy them from the /templates/ folder to your /templates/your_template/ folder and create something awesome. QP always looks in /templates/your_template/ first then /templates/ if it didn't find the file you are including.

To a custom file simply create the file and use template_include( 'your_file' ) to include it. The name can be whatever you want; "dot inc dot php" is easy and it works, so there you go.

Very Generic Sample:

1. <?php
2. // --- --- --- --- --- --- --- --- --- --- ---
3. // --- SOME FILE INCLUDED HERE ---
4. template_include( '_some_file.inc.php' );
5. ?>

You can supply an array of params to the included file, and get really complicated about it if need be:

1. <?php
2. // --- --- --- --- --- --- --- --- --- --- ---
3. // --- SOME FILE INCLUDED HERE ---
4. template_include( '_some_file.inc.php', $params );
5. ?>
6.  
7. <?php
8. // --- --- --- --- --- --- --- --- --- --- ---
9. // --- SOME FILE INCLUDED HERE ---
10. template_include( '_some_file.inc.php', array(
11.         'a_param' => 'your_value',
12.         'another_param' => 'your_next_value',
13. ) );
14. ?>
15.  
16. <?php
17. // --- --- --- --- --- --- --- --- --- --- ---
18. // --- SOME FILE INCLUDED HERE ---
19. template_include( $params['file_name'], array(
20.     'a_param' => $params['a_param'],
21.     'another_param' => $params['another_param'],
22. ) );
23. ?>

SPECIAL CASE: including a page based on the value of $disp:

1. <?php
2. // --- --- --- --- --- --- --- --- --- --- ---
3. // --- MAIN CONTENT INCLUDED HERE ---
4. template_include( '$disp$', array(
5.     // these cases already handled by this file
6.     'disp_posts' => '', 
7.     'disp_single' => '', 
8.     'disp_page' => '', 
9. ) );
10.  
11. /* ------------- */
12.  
13. // --- --- --- --- --- --- --- --- --- --- ---
14. // --- MAIN CONTENT INCLUDED HERE ---
15. template_include( '$disp$', array() );
16.  
17. /* ------------- */
18.  
19. // --- --- --- --- --- --- --- --- --- --- ---
20. // --- MAIN CONTENT INCLUDED HERE ---
21. template_include( '$disp$', array(
22.     // these cases already handled by this file
23.     'disp_yourfile' => '_yourfile.disp.php'
24. ) );
25. ?>

⇑ top of page ⇑

template_container()

Containers are used as, well, "containers" for widgets. When you upload and install a template QP will find whatever containers it has and try to determine the best widgets for each under the circumstances (existing widgets, new blog defaults, others?).

Containers provide a very easy way to add and remove widgets from your web, but you might also consider using template_widget() after you know the widget arrangement that works best for you. Doing so will put a slightly smaller load on your server is why.

template_container() allows you to identify the container by name, and set some parameter values that will be used as default for widgets in that container.

If you do not plan on giving open sourcing your template (but please do!) you can name your containers in any way you like. Bob, Mary, Fred, Alice and Tom will work just as well as the names we use in the templates we provide.

You can name your containers anything but if you want to create a template for distribution via quamplures.net you'll want to stick to our naming convention if reasonably possible.

When template_container()s play nice they close any html tags they open. You should make your template_container()s play nice :)

ALL params with defaults shown >> 2 $params << and >> the $params motherlode <<

Extremely Loaded Sample:

1. <?php
2. // --- --- --- --- --- --- --- --- --- --- ---
3. // display "Something" container's widgets
4. template_container( NT_('Something'), array(
5.     'container_start' => '<div id="%sco_name%" class="container">',
6.     'container_end' => '</div>',
7.     'block_start' => '<div class="$wi_class$">',
8.     'block_end' => '</div>',
9.     'block_display_title' => true,
10.     'block_title_start' => '<h3>',
11.     'block_title_end' => '</h3>',
12.     'coll_start' => '<h4>',
13.     'coll_end' => '</h4>',
14.     'collist_start' => '',
15.     'collist_end' => '',
16.     'group_start' => '<ul>',
17.     'group_end' => '</ul>',
18.     'list_start' => '<ul>',
19.     'list_end' => '</ul>',
20.     'item_start' => '<li>',
21.     'item_end' => '</li>',
22.     'item_text_start' => '',
23.     'item_text' => '%s',
24.     'item_text_end' => '',
25.     'item_selected_start' => '<li class="selected">',
26.     'item_selected_text' => '%s',
27.     'item_selected_end' => '</li>',
28.     'item_selected_text_start' => '',
29.     'item_selected_text_end' => '',
30.     'link_default_class' => 'default',
31.     'link_selected_class' => 'selected',
32.     'link_type' => 'canonic',        // 'canonic' | 'context' (context will regenrate URL injecting/replacing a single filter)
33.     'notes_start' => '<div class="notes">',
34.     'notes_end' => '</div>',
35.     'thumb_size' => 'crop-80x80',
36.     'limit' => 100,
37. ) );
38. ?>

⇑ top of page ⇑

template_widget()

Using template_widget() allows you to place a widget directly into your page flow without the use of a Container. Doing so is harder to start with because you have to edit the appropriate files with the right bit of code, but will save your server a measurable amount of work. Think of Containers as "middle-men" that you want to cut out of the loop and you'll begin to enjoy template_widget()'s purpose.

template_widget() uses ComponentWidget->display() which uses ComponentWidget->init_display() to define the minimum parameters for displaying this widget.

You can, of course, also pass params that are unique to that particular widget.

lorem ipsum - this page is not done. It only shows widgets that are in a 'skin' in the old evo package. Needs to show all widgets with all widget-specific params. Needs to also show the params flow!

See template_widget() for samples

⇑ top of page ⇑