Projects/kde.org/Capacity HOWTO: Difference between revisions

From KDE TechBase
No edit summary
m (Text replace - "</code>" to "</syntaxhighlight>")
Line 24: Line 24:


<?php include "footer.inc"; ?>
<?php include "footer.inc"; ?>
</code>
</syntaxhighlight>


==The magic site.inc==
==The magic site.inc==
Line 52: Line 52:
     'contact/'=>'Contact Us');
     'contact/'=>'Contact Us');
?>
?>
</code>
</syntaxhighlight>


Even in the {{path|site.inc}} you can already use the i18n-functions,
Even in the {{path|site.inc}} you can already use the i18n-functions,
Line 65: Line 65:
$url_root
$url_root
$current_relativeurl
$current_relativeurl
</code>
</syntaxhighlight>


* <tt>$site_root</tt> contains the relative path to the toplevel of the current site, like:
* <tt>$site_root</tt> contains the relative path to the toplevel of the current site, like:
<code php>
<code php>
$site_root = "../.."
$site_root = "../.."
</code>
</syntaxhighlight>


* <tt>$document_root</tt> contains the absolute pathname which is the documentroot of this site, even correct if the site isn't in it's own vhost. Example:
* <tt>$document_root</tt> contains the absolute pathname which is the documentroot of this site, even correct if the site isn't in it's own vhost. Example:
<code php>
<code php>
$document_root = "/home/www/sites/www"
$document_root = "/home/www/sites/www"
</code>
</syntaxhighlight>


* <tt>$url_root</tt> contains the absolute base url to the toplevel of your site, if your site would, for example, have a it's toplevel in http://127.0.0.1:8080/sites/www, like it is for staging, this would contain:
* <tt>$url_root</tt> contains the absolute base url to the toplevel of your site, if your site would, for example, have a it's toplevel in http://127.0.0.1:8080/sites/www, like it is for staging, this would contain:
<code php>
<code php>
$url_root = /sites/www
$url_root = /sites/www
</code>
</syntaxhighlight>


* <tt>$current_relativeurl</tt> contains the relative part of the current url to the url_root, would you access http://127.0.0.1:8080/sites/www/whatiskde/manifest.php and /sites/www is the <tt>$url_root</tt>, it would contain
* <tt>$current_relativeurl</tt> contains the relative part of the current url to the url_root, would you access http://127.0.0.1:8080/sites/www/whatiskde/manifest.php and /sites/www is the <tt>$url_root</tt>, it would contain
<code php>
<code php>
$current_relativeurl = whatiskde/manifest.php
$current_relativeurl = whatiskde/manifest.php
</code>
</syntaxhighlight>


'''BE AWARE:''' In former version of the framework it was common to set the <tt>$site_root</tt> manually before including the {{path|header.inc}}, this won't work now, as the {{path|header.inc}} will overwrite the <tt>$site_root</tt>. This should cause no danger, as {{path|header.inc}} should find out the right one, but in the long term, all manual definitions should be removed, the global variables {{path|header.inc}} exports should be used to replace the usage of the old <tt>$site_root</tt>.
'''BE AWARE:''' In former version of the framework it was common to set the <tt>$site_root</tt> manually before including the {{path|header.inc}}, this won't work now, as the {{path|header.inc}} will overwrite the <tt>$site_root</tt>. This should cause no danger, as {{path|header.inc}} should find out the right one, but in the long term, all manual definitions should be removed, the global variables {{path|header.inc}} exports should be used to replace the usage of the old <tt>$site_root</tt>.
Line 92: Line 92:
<code php>
<code php>
$some_url = "$site_root/mycoolpage.php"
$some_url = "$site_root/mycoolpage.php"
</code>
</syntaxhighlight>


==Configuration Variables==
==Configuration Variables==
Line 103: Line 103:
<code php>
<code php>
$site_title = "KDE Foo Site Title";
$site_title = "KDE Foo Site Title";
</code>
</syntaxhighlight>


* The title of the individual page.
* The title of the individual page.
<code php>
<code php>
$page_title = "Page Title";
$page_title = "Page Title";
</code>
</syntaxhighlight>


* Don't show edit function on the page. The default is <tt>$showedit = true;</tt>. This setting should normally not be used. {{path|site.inc}} is the preferred place.
* Don't show edit function on the page. The default is <tt>$showedit = true;</tt>. This setting should normally not be used. {{path|site.inc}} is the preferred place.
Line 114: Line 114:
<code php>
<code php>
$showedit = false;
$showedit = false;
</code>
</syntaxhighlight>


==Online Editing==
==Online Editing==
Line 141: Line 141:
   $section->appendLink("A Single Page","singlepage.php");
   $section->appendLink("A Single Page","singlepage.php");
?>
?>
</code>
</syntaxhighlight>


Also you could show a little 16*16 Icon for each menu item.You should give the Icon url as the last argument to the appendDir or appendLink:
Also you could show a little 16*16 Icon for each menu item.You should give the Icon url as the last argument to the appendDir or appendLink:
Line 148: Line 148:
<?php
<?php
   $section->appendDir("A Subdirectory","subdirectory", true, false, "icon.png");
   $section->appendDir("A Subdirectory","subdirectory", true, false, "icon.png");
</code>
</syntaxhighlight>
in the Above code, first argument is the title of the menu, second argument is the url, third argument defines that if this menu item is relative, forth argument should be True if it links to a directory and last argument is the Icon
in the Above code, first argument is the title of the menu, second argument is the url, third argument defines that if this menu item is relative, forth argument should be True if it links to a directory and last argument is the Icon


Line 154: Line 154:
<code php>
<code php>
   $section->appendDir("A Subdirectory","subdirectory", "icon.png");
   $section->appendDir("A Subdirectory","subdirectory", "icon.png");
</code>
</syntaxhighlight>
Each mentioned subdirectory will then also be searched for a {{path|menu.inc}} file to define a submenu (e.g. http://www.kde.org/whatiskde/menu.inc).  
Each mentioned subdirectory will then also be searched for a {{path|menu.inc}} file to define a submenu (e.g. http://www.kde.org/whatiskde/menu.inc).  


Line 163: Line 163:
   $this->appendLink("A Page in the Subdirectory","singlepage.php");
   $this->appendLink("A Page in the Subdirectory","singlepage.php");
?>
?>
</code>
</syntaxhighlight>
    
    
The content of subsubdirectories is currently not added to the menu, but this may change in future.  
The content of subsubdirectories is currently not added to the menu, but this may change in future.  
Line 175: Line 175:
<h2><a name="section1" />Section Headline</h2>
<h2><a name="section1" />Section Headline</h2>
<h3>Subsection Headline</h3>
<h3>Subsection Headline</h3>
</code>
</syntaxhighlight>


Headlines must never be used to increase the size of a text. Use &lt;b&gt; to make it stick out. The first letters of every word of a headline or link should be capitalized, apart from small words like "a", "to", etc.  
Headlines must never be used to increase the size of a text. Use &lt;b&gt; to make it stick out. The first letters of every word of a headline or link should be capitalized, apart from small words like "a", "to", etc.  
Line 186: Line 186:
   <a href="section3">Third Section Headline</a> ]
   <a href="section3">Third Section Headline</a> ]
<div>
<div>
</code>  
</syntaxhighlight>  


If you wish to link &lt;h3&gt; headlines as well, then you can use:  
If you wish to link &lt;h3&gt; headlines as well, then you can use:  
Line 202: Line 202:
</p>
</p>
</div>
</div>
</code>
</syntaxhighlight>


==Own Header-Logo==
==Own Header-Logo==
Line 216: Line 216:
   kde_general_news($file, $items, $summaryonly)
   kde_general_news($file, $items, $summaryonly)
?>
?>
</code>
</syntaxhighlight>


The parameters of kde_general_news() are as follows:
The parameters of kde_general_news() are as follows:
Line 234: Line 234:
   $faq->show();
   $faq->show();
?>
?>
</code>
</syntaxhighlight>


Note: the page won't be rendered until you call <tt>show()</tt>.  
Note: the page won't be rendered until you call <tt>show()</tt>.  
Line 255: Line 255:
   $gallery->show();
   $gallery->show();
?>
?>
</code>
</syntaxhighlight>


The first call to <tt>addImage()</tt> creates an image that can be clicked on to link to a larger version of the image. <tt>startNewRow()</tt> creates a new row. The second call to <tt>addImage()</tt> creates an image that isn't clickable (note the 0 rather than the URL to the large image).  
The first call to <tt>addImage()</tt> creates an image that can be clicked on to link to a larger version of the image. <tt>startNewRow()</tt> creates a new row. The second call to <tt>addImage()</tt> creates an image that isn't clickable (note the 0 rather than the URL to the large image).  
Line 263: Line 263:
addImage($src_url, $dest_url, $width_pixels, $height_pixels,
addImage($src_url, $dest_url, $width_pixels, $height_pixels,
         $alt_text, $caption_text, $description_text)
         $alt_text, $caption_text, $description_text)
</code>
</syntaxhighlight>
* <tt>$src_url</tt> - The URL of the thumbnail image. If it is empty (""), then only caption and description will be shown.
* <tt>$src_url</tt> - The URL of the thumbnail image. If it is empty (""), then only caption and description will be shown.
* <tt>$dest_url</tt> - The URL of the enlarged version of the image. The caption and the description will be links as well if <tt>$dest_url</tt> is specified.
* <tt>$dest_url</tt> - The URL of the enlarged version of the image. The caption and the description will be links as well if <tt>$dest_url</tt> is specified.
Line 296: Line 296:
   $appinfo->show();
   $appinfo->show();
?>
?>
</code>
</syntaxhighlight>


The second and third parameters of <tt>setIcon()</tt> are the width and height of the icon. The <tt>addContributor()</tt> function can take an optional third parameter, a short description of the person's function in the project.
The second and third parameters of <tt>setIcon()</tt> are the width and height of the icon. The <tt>addContributor()</tt> function can take an optional third parameter, a short description of the person's function in the project.
Line 331: Line 331:
   $handler->execute();
   $handler->execute();
?>
?>
</code>
</syntaxhighlight>


You must call <tt>execute()</tt> otherwise it won't work!
You must call <tt>execute()</tt> otherwise it won't work!
Line 343: Line 343:
   $site_locale = "de";
   $site_locale = "de";
?>
?>
</code>
</syntaxhighlight>


Please adjust the abbreviation to your needs.
Please adjust the abbreviation to your needs.
Line 353: Line 353:
<code php>
<code php>
<p><?php i18n("Some images of Okular in action...")?></p>
<p><?php i18n("Some images of Okular in action...")?></p>
</code>
</syntaxhighlight>
* i18n_var is the function you want to use if you want to get a translated text in a way you can assign it to a variable, e.g.
* i18n_var is the function you want to use if you want to get a translated text in a way you can assign it to a variable, e.g.
<code php>
<code php>
<?php $site_title = i18n_var("Okular - more than a reader"); ?></p>
<?php $site_title = i18n_var("Okular - more than a reader"); ?></p>
</code>
</syntaxhighlight>
* i18n_noop is the function you want to use if you simply want to mark your text as translatable because you know the translation will happen at a later stage.
* i18n_noop is the function you want to use if you simply want to mark your text as translatable because you know the translation will happen at a later stage.
<code php>
<code php>
<?php $page_title = i18n_noop('Frequently Asked Questions'); ?></p>
<?php $page_title = i18n_noop('Frequently Asked Questions'); ?></p>
</code>
</syntaxhighlight>


If you want to show a language selector in your webpage you have to define the site_languages variable to hold the supported languages.
If you want to show a language selector in your webpage you have to define the site_languages variable to hold the supported languages.
<code php>
<code php>
<?php $site_languages = array('en', 'es', 'pt_BR', 'uk'); ?></p>
<?php $site_languages = array('en', 'es', 'pt_BR', 'uk'); ?></p>
</code>
</syntaxhighlight>

Revision as of 20:57, 29 June 2011

Note
This projects page has been moved to [[1]]. Please don't edit on techbase anymore.


Introduction

Capacity is a versatile framework which helps you to construct your page by focusing on the content. Your pages will be simple PHP-files which include predefined header and footer. This header/footer layout the page, you only provide the real content and menu structure.


Example PHP-file

Any normal page just contains:

<?php

 $page_title = "Page Title";
 include "header.inc";

?>;

 Content of the web page

<?php include "footer.inc"; ?> </syntaxhighlight>

The magic site.inc

For each subsite, a site.inc in the toplevel directory of this page, which would be equal to the later documentroot on the server in many cases, may be created. This include is used by the header.inc, it should contain some information about your site, like its name and the email address of the webmaster, this will be used by header/footer to setup the page correct.

An example site.inc would be:

<?php

 // promote which subdomain we are
 // we are www.kde.org in this case!
 $site = "www";
 // use new style ;) yeah
 $templatepath = "newlayout/";
 // promote title to use
 $site_title = i18n_var("K Desktop Environment");
 // links in the top bar, right
 $menuright = array ('family/'=>'Sitemap',
   'contact/'=>'Contact Us');

?> </syntaxhighlight>

Even in the site.inc you can already use the i18n-functions, which is important to have the names right on translated pages!

Global Variables setup by header.inc

The header.inc does some setup of global vars, even before it includes the site.inc, these are:

$site_root $document_root $url_root $current_relativeurl </syntaxhighlight>

  • $site_root contains the relative path to the toplevel of the current site, like:

$site_root = "../.." </syntaxhighlight>

  • $document_root contains the absolute pathname which is the documentroot of this site, even correct if the site isn't in it's own vhost. Example:

$document_root = "/home/www/sites/www" </syntaxhighlight>

  • $url_root contains the absolute base url to the toplevel of your site, if your site would, for example, have a it's toplevel in http://127.0.0.1:8080/sites/www, like it is for staging, this would contain:

$url_root = /sites/www </syntaxhighlight>

$current_relativeurl = whatiskde/manifest.php </syntaxhighlight>

BE AWARE: In former version of the framework it was common to set the $site_root manually before including the header.inc, this won't work now, as the header.inc will overwrite the $site_root. This should cause no danger, as header.inc should find out the right one, but in the long term, all manual definitions should be removed, the global variables header.inc exports should be used to replace the usage of the old $site_root.

The framework is clever, it will never add trailing slashs to the $site_root, $document_root and $url_root, therefor they can and must always be used like: $some_url = "$site_root/mycoolpage.php" </syntaxhighlight>

Configuration Variables

You can set some variables to alter the behaviour of the framework, either global in your site.inc or in front of your header.inc inclusion in each .php-files.

Useful variables are:

  • The Name for your whole subdomain/site, best set once in site.inc

$site_title = "KDE Foo Site Title"; </syntaxhighlight>

  • The title of the individual page.

$page_title = "Page Title"; </syntaxhighlight>

  • Don't show edit function on the page. The default is $showedit = true;. This setting should normally not be used. site.inc is the preferred place.

$showedit = false; </syntaxhighlight>

Online Editing

Capacity features online editing and previewing of changes.

You can make and preview changes of existing pages online by clicking on the [edit] link at the bottom of each page. Try it on this page. Then you can download you changes and commit them yourself via SVN, or you can click the link to email a unified diff to the web team.

Menu Definitions

The navigation menu is defined by a number of menu.inc files. They are included by a function in media/includes/classes/class_menu.inc, which is called from media/includes/header.inc. The general menu structure is defined in the menu.inc file of the root directory of each KDE subsite (e.g. http://www.kde.org/menu.inc or http://www.kde.org/areas/kde-ev/menu.inc).

It should look like this: <?php

 $this->setName ("KDE Foo Site Title");
 $section =& $this->appendSection("Inform");
 $section->appendLink("Home","");
 $section->appendLink("KDE Home","http://www.kde.org/",false);
 
 $section =& $this->appendSection("A Second Menu Section");
 $section->appendDir("A Subdirectory","subdirectory");
 $section->appendLink("A Single Page","singlepage.php");

?> </syntaxhighlight>

Also you could show a little 16*16 Icon for each menu item.You should give the Icon url as the last argument to the appendDir or appendLink:

<?php

 $section->appendDir("A Subdirectory","subdirectory", true, false, "icon.png");

</syntaxhighlight> in the Above code, first argument is the title of the menu, second argument is the url, third argument defines that if this menu item is relative, forth argument should be True if it links to a directory and last argument is the Icon

To show an Icon with appendDir, just add icon url as the third argument, like this:

 $section->appendDir("A Subdirectory","subdirectory", "icon.png");

</syntaxhighlight> Each mentioned subdirectory will then also be searched for a menu.inc file to define a submenu (e.g. http://www.kde.org/whatiskde/menu.inc).

The format is similar: <?php

 $this->appendDir("A Subsubdirectory","subsubdirectory");
 $this->appendLink("A Page in the Subdirectory","singlepage.php");

?> </syntaxhighlight>

The content of subsubdirectories is currently not added to the menu, but this may change in future. If a subdirectory has just the index.php file or a submenu for the subdirectory is not desired, then an empty menu.inc can be added. If the menu.inc is missing, then the subdirectory is be treated like having an empty menu.inc file.

Headlines

The main headline of a page is defined via $page_title. If a page has several sections with a headline each, <h2> is used for them (<h3> for subsections):

<a name="section1" />Section Headline

Subsection Headline

</syntaxhighlight>

Headlines must never be used to increase the size of a text. Use <b> to make it stick out. The first letters of every word of a headline or link should be capitalized, apart from small words like "a", "to", etc.

To allow better navigation through the site, each <h2> heading should be linked from a quicklinks section on top of the page: