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

    From KDE TechBase
    (404)
    (URL chan)
    (24 intermediate revisions by 12 users not shown)
    Line 1: Line 1:
    {{Remember|2=Important!|1=|This project page has been moved to [http://community.kde.org/KDE.org/Capacity_HOWTO community.kde.org]. Please don't edit on techbase anymore.}}
    __TOC__
    __TOC__


    Line 13: Line 16:
    Any normal page just contains:
    Any normal page just contains:


      <?php
    <syntaxhighlight lang="php">
        $page_title = "Page Title";
    <?php
        include "header.inc";
      $page_title = "Page Title";
      ?>;
      include "header.inc";
     
    ?>;
     
       Content of the web page
       Content of the web page
     
     
      <?php include "footer.inc"; ?>
    <?php include "footer.inc"; ?>
    </syntaxhighlight>


    ==The magic site.inc==
    ==The magic site.inc==
    Line 26: Line 31:
    which would be equal to the later documentroot on the server in many
    which would be equal to the later documentroot on the server in many
    cases, may be created. This include is used by the {{path|header.inc}}, it
    cases, may be created. This include is used by the {{path|header.inc}}, it
    should contain some information about your site, like it's name
    should contain some information about your site, like its name
    and the email address of the webmaster, this will be used by header/footer
    and the email address of the webmaster, this will be used by header/footer
    to setup the page correct.
    to setup the page correct.
    Line 32: Line 37:
    An example {{path|site.inc}} would be:
    An example {{path|site.inc}} would be:


      <?php
    <syntaxhighlight lang="php">
        // promote which subdomain we are
    <?php
        // we are www.kde.org in this case!
      // promote which subdomain we are
        $site = "www";
      // we are www.kde.org in this case!
        
      $site = "www";
        // use new style ;) yeah
     
        $templatepath = "newlayout/";
       // use new style ;) yeah
        
      $templatepath = "newlayout/";
        // promote title to use
     
        $site_title = i18n_var("K Desktop Environment");
       // promote title to use
        
      $site_title = i18n_var("K Desktop Environment");
        // links in the top bar, right
     
        $menuright = array ('family/'=>'Sitemap',
       // links in the top bar, right
          'contact/'=>'Contact Us');
      $menuright = array ('family/'=>'Sitemap',
      ?>
        'contact/'=>'Contact Us');
    ?>
    </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 54: Line 61:
    The {{path|header.inc}} does some setup of global vars, even before it includes the {{path|site.inc}}, these are:
    The {{path|header.inc}} does some setup of global vars, even before it includes the {{path|site.inc}}, these are:


      $site_root
    <syntaxhighlight lang="php">
      $document_root
    $site_root
      $url_root
    $document_root
      $current_relativeurl
    $url_root
    $current_relativeurl
    </syntaxhighlight>


    * <code>$site_root</code> 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:
      $site_root = "../.."
    <syntaxhighlight lang="php">
    $site_root = "../.."
    </syntaxhighlight>


    * <code>$document_root</code> contains the absolut 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:
      $document_root = "/home/www/sites/www"
    <syntaxhighlight lang="php">
    $document_root = "/home/www/sites/www"
    </syntaxhighlight>


    * <code>$url_root</code> contains the absolute baseurl 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:
      $url_root = /sites/www
    <syntaxhighlight lang="php">
    $url_root = /sites/www
    </syntaxhighlight>


    * <code>$current_relativeurl</code> 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 <code>$url_root</code>, 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
      $current_relativeurl = whatiskde/manifest.php
    <syntaxhighlight lang="php">
    $current_relativeurl = whatiskde/manifest.php
    </syntaxhighlight>


    '''BE AWARE:''' In former version of the framework it was common to set the <code>$site_root</code> manually before including the {{path|header.inc}}, this won't work now, as the {{path|header.inc}} will overwrite the <code>$site_root</code>. 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 <code>$site_root</code>.
    '''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>.


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


    ==Configuration Variables==
    ==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 {{path|header.inc}} inclusion in each .php-files.
    You can set some variables to alter the behaviour of the framework, either global in your {{path|site.inc}} or in front of your {{path|header.inc}} inclusion in each .php-files.


    Useful variables are:
    Useful variables are:


    * The Name for your whole subdomain/site, best set once in {{path|site.inc}}
    * The Name for your whole subdomain/site, best set once in {{path|site.inc}}
      $site_title = "KDE Foo Site Title";
    <syntaxhighlight lang="php">
    $site_title = "KDE Foo Site Title";
    </syntaxhighlight>


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


    * Don't show edit function on the page. The default is <code>$showedit = true;</code>. 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.


      $showedit = false;
    <syntaxhighlight lang="php">
    $showedit = false;
    </syntaxhighlight>


    ==Online Editing==
    ==Online Editing==
    Line 101: Line 126:
    ==Menu Definitions==
    ==Menu Definitions==


    The navigation menu is defined by a number of menu.inc files.  
    The navigation menu is defined by a number of {{path|menu.inc}} files.  
    They are included by a function in media/includes/classes/class_menu.inc, which is called from media/includes/header.inc.  
    They are included by a function in {{path|media/includes/classes/class_menu.inc}}, which is called from {{path|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).  
    The general menu structure is defined in the {{path|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:  
    It should look like this:
      <?php
    <syntaxhighlight lang="php">
        $this->setName ("KDE Foo Site Title");
    <?php
        $section =&amp; $this->appendSection("Inform");
      $this->setName ("KDE Foo Site Title");
        $section->appendLink("Home","");
      $section =&amp; $this->appendSection("Inform");
        $section->appendLink("KDE Home","http://www.kde.org/",false);
      $section->appendLink("Home","");
       
      $section->appendLink("KDE Home","http://www.kde.org/",false);
        $section =&amp; $this->appendSection("A Second Menu Section");
     
        $section->appendDir("A Subdirectory","subdirectory");
      $section =&amp; $this->appendSection("A Second Menu Section");
        $section->appendLink("A Single Page","singlepage.php");
      $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:
     
    <syntaxhighlight lang="php">
    <?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


    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).  
    To show an Icon with appendDir, just add icon url as the third argument, like this:
    <syntaxhighlight lang="php">
      $section->appendDir("A Subdirectory","subdirectory", "icon.png");
    </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).  


    The format is similar:
    The format is similar:
      <?php
    <syntaxhighlight lang="php">
        $this->appendDir("A Subsubdirectory","subsubdirectory");
    <?php
        $this->appendLink("A Page in the Subdirectory","singlepage.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.  
    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.
    If a subdirectory has just the index.php file or a submenu for the subdirectory is not desired, then an empty {{path|menu.inc}} can be added. If the {{path|menu.inc}} is missing, then the subdirectory is be treated like having an empty {{path|menu.inc}} file.


    ==Headlines==
    ==Headlines==


    The main headline of a page is defined via $page_title.  
    The main headline of a page is defined via <tt>$page_title</tt>.  
    If a page has several sections with a headline each, &lt;h2&gt; is used for them (&lt;h3&gt; for subsections):  
    If a page has several sections with a headline each, &lt;h2&gt; is used for them (&lt;h3&gt; for subsections):
      &lt;h2&gt;&lt;a name="section1" /&gt;Section Headline&lt;h2&gt;
    <syntaxhighlight lang="html4strict">
      &lt;h3&gt;Subsection Headline&lt;h3&gt;
    <h2><a name="section1" />Section Headline</h2>
    <h3>Subsection Headline</h3>
    </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.  


    To allow better navigation through the site, each &lt;h2&gt; heading should be linked from a quicklinks section on top of the page:  
    To allow better navigation through the site, each &lt;h2&gt; heading should be linked from a quicklinks section on top of the page:
      &lt;div id="quicklinks"&gt; [  
    <syntaxhighlight lang="html4strict">
        &lt;a href="section1"&gt;Section Headline&lt;/a&gt; |  
    <div id="quicklinks"> [
        &lt;a href="section2"&gt;Second Section Headline&lt;/a&gt; |  
      <a href="section1">Section Headline</a> |
        &lt;a href="section3"&gt;Third Section Headline&lt;/a&gt; ]  
      <a href="section2">Second Section Headline</a> |
      &lt;div&gt;
      <a href="section3">Third Section Headline</a> ]
    <div>
    </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:  
      &lt;div id="quicklinks"&gt;
    <syntaxhighlight lang="html4strict">
      &lt;p&gt;
    <div id="quicklinks">
        &lt;b&gt;&lt;a href="section1"&gt;Section Headline&lt;/a&gt;&lt;/b&gt;: &lt;br /&gt; [  
    <p>
        &lt;a href="section11"&gt;Subsection Headline&lt;/a&gt; |  
      <b><a href="section1">Section Headline</a></b>: <br />; [
        &lt;a href="section21"&gt;Second Subsection Headline&lt;/a&gt; |  
      <a href="section11">Subsection Headline</a> |
        &lt;a href="section31"&gt;Third Subsection Headline&lt;/a&gt; ]  
      <a href="section21">Second Subsection Headline</a> |
      &lt;p&gt;
      <a href="section31">Third Subsection Headline</a> ]
      &lt;p&gt;
    </p>
        &lt;b&gt;&lt;a href="section2"&gt;Second Section Headline&lt;/a&gt;&lt;/b&gt;: &lt;br /&gt; [  
    <p>
        &lt;a href="section21"&gt;Subsection Headline&lt;/a&gt; ]  
      <b><a href="section2">Second Section Headline</a></b>: <br /> [
      &lt;p&gt;
      <a href="section21">Subsection Headline</a> ]
      &lt;div&gt;
    </p>
    </div>
    </syntaxhighlight>
     
    ==Own Header-Logo==
     
    Each site can have it's own right-side header-logo, like http://conference2006.kde.org. You just need to add a {{path|site.png}} to the top-level directory of your site, the framework will add it automatically if it finds one. Look at http://conference2006.kde.org/site.png for the correct dimensions. While a transparent background would be preferred, atm the Internet Explorer has problems with transparent PNGs, and GIFs are (were) problematic because of patents. Therefore the background needs atm to be duplicated in the image like done for the conference site.


    ==News==
    ==News==


    The kde_general_news() can be used to easily show a new story on a page.
    The <tt>kde_general_news()</tt> can be used to easily show a new story on a page.


      <?php
    <syntaxhighlight lang="php">
        kde_general_news($file, $items, $summaryonly)
    <?php
      ?>
      kde_general_news($file, $items, $summaryonly)
    ?>
    </syntaxhighlight>


    The parameters of kde_general_news() are as follows:
    The parameters of kde_general_news() are as follows:
    * $file - The relative path to the news.rdf file. This will generally be "./news.rdf".
    * <tt>$file</tt> - The relative path to the {{path|news.rdf}} file. This will generally be "{{path|./news.rdf}}".
    * $items - The number of news stories to show.
    * <tt>$items</tt> - The number of news stories to show.
    * $summaryonly - Whether to show the summary only (e.g. for index.php) or the full stories (news.php).
    * <tt>$summaryonly</tt> - Whether to show the summary only (e.g. for {{path|index.php}}) or the full stories ({{path|news.php}}).


    ==FAQs==
    ==FAQs==
    Line 175: Line 228:
    A PHP class has been written to make it easy to write FAQs. It will always give a consistent formatting style. Using the class is simple:  
    A PHP class has been written to make it easy to write FAQs. It will always give a consistent formatting style. Using the class is simple:  


      <?php
    <syntaxhighlight lang="php">
        $faq = new FAQ();
    <?php
        $faq->addQuestion("This is the text of the question",
      $faq = new FAQ();
          "This is the text of the answer");
      $faq->addQuestion("This is the text of the question",
        $faq->show();
        "This is the text of the answer");
      ?>
      $faq->show();
    ?>
    </syntaxhighlight>


    Note: the page won't be rendered until you call show().  
    Note: the page won't be rendered until you call <tt>show()</tt>.  
    Please use this class rather than hand constructing a FAQ to save your time and to improve consistency.
    Please use this class rather than hand constructing a FAQ to save your time and to improve consistency.


    Line 189: Line 244:
    A PHP class has been written to make it easy to write image galleries. The image galleries can link to enlarged versions of the image, but this isn't compulsory. Using the class is simple:  
    A PHP class has been written to make it easy to write image galleries. The image galleries can link to enlarged versions of the image, but this isn't compulsory. Using the class is simple:  


      <?php
    {{Tip| If you want to have a fancy Image Gallery with Lightbox, pass <tt>True</tt> as the second argument to the <tt>imageGallery</tt> class.}}
        $gallery = new ImageGallery("Add a summary for screen readers here");
        $gallery->addImage("pics/image_sm.png", "pics/image.png", "640", "480",
          "Alt text", "Image caption (top)", "Image description (bottom)");
        $gallery->startNewRow();
        $gallery->addImage("pics/image_sm.png",  0, "640", "480",
          "Alt text", "Image caption (top)", "Image description (bottom)");
        $gallery->show();
      ?> 


    The first call to addImage() creates an image that can be clicked on to link to a larger version of the image. startNewRow() creates a new row. The second call to addImage() creates an image that isn't clickable (note the 0 rather than the URL to the large image).
    <syntaxhighlight lang="php">
    <?php
      $gallery = new ImageGallery("Add a summary for screen readers here");
      $gallery->addImage("pics/image_sm.png", "pics/image.png", "640", "480",
        "Alt text", "Image caption (top)", "Image description (bottom)");
      $gallery->startNewRow();
      $gallery->addImage("pics/image_sm.png",  0, "640", "480",
        "Alt text", "Image caption (top)", "Image description (bottom)");
      $gallery->show();
    ?>
    </syntaxhighlight>


    The parameters of addImage() are as follows:
    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).
      addImage($src_url, $dest_url, $width_pixels, $height_pixels,
        $alt_text, $caption_text, $description_text)
    * $src_url - The URL of the thumbnail image. If it is empty (""), then only caption and description will be shown.
    * $dest_url - The URL of the enlarged version of the image. The caption and the description will be links as well if $dest_url is specified.
    * $width_pixels - The width of the image in pixels
    * $height_pixels - The height of the image in pixels
    * $alt_text - A short description of the image for use in the alt="" tag (used by non-graphical browsers and screen readers)
    * $caption_text - A short caption which will appear above the image in bold (optional)
    * $description_text - A short description of the image which will appear underneath (optional)


    Note: the page won't be rendered until you call show().
    The parameters of <tt>addImage()</tt> are as follows
    <syntaxhighlight lang="php">
    addImage($src_url, $dest_url, $width_pixels, $height_pixels,
            $alt_text, $caption_text, $description_text)
    </syntaxhighlight>
    * <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>$width_pixels</tt> - The width of the image in pixels
    * <tt>$height_pixels</tt> - The height of the image in pixels
    * <tt>$alt_text</tt> - A short description of the image for use in the alt="" tag (used by non-graphical browsers and screen readers)
    * <tt>$caption_text</tt> - A short caption which will appear above the image in bold (optional)
    * <tt>$description_text</tt> - A short description of the image which will appear underneath (optional)
     
    {{Warning| The page won't be rendered until you call <tt>show()</tt>}}
    Please use this class rather than hand constructing an image gallery to save your time and to improve consistency.
    Please use this class rather than hand constructing an image gallery to save your time and to improve consistency.


    Line 219: Line 280:
    For web sites like koffice.org and edu.kde.org it makes sense to have a sub-directory for each program that is part of the project and in that sub-directory have a page which shows information about the program. The AppInfo class has been designed to make it easy to create such a page. It can be used as follows:
    For web sites like koffice.org and edu.kde.org it makes sense to have a sub-directory for each program that is part of the project and in that sub-directory have a page which shows information about the program. The AppInfo class has been designed to make it easy to create such a page. It can be used as follows:


      <?php
    <syntaxhighlight lang="php">
        $appinfo = new AppInfo("KWord");
    <?php
        $appinfo->setIcon( "pics/hi48-app-kword.png", "48", "48");
      $appinfo = new AppInfo("KWord");
        $appinfo->setVersion($kwordversion);
      $appinfo->setIcon( "pics/hi48-app-kword.png", "48", "48");
        $appinfo->setLicense("lgpl");
      $appinfo->setVersion($kwordversion);
        $appinfo->setCopyright("1998", "the KWord Team");
      $appinfo->setLicense("lgpl");
        $appinfo->addAuthor("Reginald Stadlbauer", "reggie@kde.org");
      $appinfo->setCopyright("1998", "the KWord Team");
        $appinfo->addAuthor("Torben Weis", "weis@kde.org");
      $appinfo->addAuthor("Reginald Stadlbauer", "email@host.com");
        $appinfo->addContributor("David Faure", "faure@kde.org");
      $appinfo->addAuthor("Torben Weis", "email@host.com");
        $appinfo->addContributor("Thomas Zander", "zander@kde.org");
      $appinfo->addContributor("David Faure", "email@host.com");
        $appinfo->addContributor("Shaheed Haque", "srhaque@ieee.org");
      $appinfo->addContributor("Thomas Zander", "email@host.com");
        $appinfo->addContributor("Laurent Montel",
      $appinfo->addContributor("Shaheed Haque", "email@host.com");
          "lmontel@mandrakesoft.com");
      $appinfo->addContributor("Laurent Montel",
        $appinfo->addContributor("Sven L&uuml;ppken", "sven@kde.org");
        "email@host.com");
        $appinfo->show();
      $appinfo->addContributor("Sven Lüppken", "email@host.com");
      ?>
      $appinfo->show();
    ?>
    </syntaxhighlight>


    The second and third parameters of setIcon() are the width and height of the icon. The addContributor() 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.


    ==Common Mistakes==
    ==Common Mistakes==


    When converting pages, it is important to keep a few common mistakes in mind:  
    When converting pages, it is important to keep a few common mistakes in mind:  
    Every page must have $page_title set to ensure correct rendering on all styles. This also means that the original heading must be removed. Otherwise the headline will be dublicated when setting $page_title.  
    Every page must have <tt>$page_title</tt> set to ensure correct rendering on all styles. This also means that the original heading must be removed. Otherwise the headline will be duplicated when setting <tt>$page_title</tt>.  


    * All settings have to be made before header.inc is included.  
    * All settings have to be made before {{path|header.inc}} is included.  
    * There cannot be several links on the same page that use the same description for different URLs. This is required for compatibility with certain accessibility related solutions. &lt;a href="foo.php"&gt;More...&lt;/a&gt; should be replaced by &lt;a href="foo.php"&gt;More about KDE 3.x.y&lt;/a&gt;, etc.  
    * There cannot be several links on the same page that use the same description for different URLs. This is required for compatibility with certain accessibility related solutions. &lt;a href="foo.php"&gt;More...&lt;/a&gt; should be replaced by &lt;a href="foo.php"&gt;More about KDE 3.x.y&lt;/a&gt;, etc.  
    * The new layout uses UTF-8 as encoding. A lot of pages contain non-ASCII characters in names etc., make sure to either convert those to UTF-8 or use their HTML names.  
    * The new layout uses UTF-8 as encoding. A lot of pages contain non-ASCII characters in names etc., make sure to either convert those to UTF-8 or use their HTML names.  
    * The new layout uses XHTML. All tags without an end tag must be converted from &lt;tag&gt; to &lt;tag /&gt;, e.g. &lt;img src="..." alt="..." /&gt;. The alt attribute is required for a better accessibility of KDE.org. Additionally, attributes without a value are treated differently in XHTML, e.g. &lt;table nowrap&gt; would become &lt;table nowrap="nowrap"&gt;.  
    * The new layout uses XHTML. All tags without an end tag must be converted from &lt;tag&gt; to &lt;tag /&gt;, e.g. &lt;img src="..." alt="..." /&gt;. The alt attribute is required for a better accessibility of KDE.org. Additionally, attributes without a value are treated differently in XHTML, e.g. &lt;table nowrap&gt; would become &lt;table nowrap="nowrap"&gt;.  
    * Please ensure that you use JPG or PNG images rather than GIF
    * Please ensure that you use JPG or PNG images rather than GIF
    * Images for a particular area/directory should be placed under a pics/ subdirectory
    * Images for a particular {{path|area/directory}} should be placed under a {{path|pics/}} subdirectory


    ==404 Handler==
    ==404 Handler==


    All sites use a custom 404 handler page which is written in PHP. The handler is implemented in the 'Handler404' classs. It has these features:
    All sites use a custom 404 handler page which is written in PHP. The handler is implemented in the <tt>Handler404</tt> class. It has these features:
    If foo.html is requested and foo.php exists, the user is redirected to foo.php
    * If {{path|foo.html}} is requested and {{path|foo.php}} exists, the user is redirected to {{path|foo.php}}.
    If foo.htm is requested and foo.php exists, the user is redirected to foo.php
    * If {{path|foo.htm}} is requested and {{path|foo.php}} exists, the user is redirected to {{path|foo.php}}.
    If foo.phtml is requested and foo.php exists, the user is redirected to foo.php
    * If {{path|foo.phtml}} is requested and {{path|foo.php}} exists, the user is redirected to {{path|foo.php}}.
    (etc)
    * etc...
     
    For pages which have changed location, a custom mapping can be added in {{path|www/media/404.php}} so that the user can be directed to just about anywhere.
     
    <syntaxhighlight lang="php">
    <?php
      include("handler.inc");
     
      $handler = new Handler404();
      $handler->add("/faq.html", "/faq");
      $handler->add("/events.html", "http://events.kde.org/");
      $handler->execute();
    ?>
    </syntaxhighlight>
     
    You must call <tt>execute()</tt> otherwise it won't work!
     
    ==i18n - Translate interface to other languages==
    English words like "search" are not useful for pages like e.g. german.
     
    Create a file named "locale.inc" in root folder and use the following content:
    <syntaxhighlight lang="php">
    <?php
      $site_locale = "de";
    ?>
    </syntaxhighlight>
     
    Please adjust the abbreviation to your needs.


    For pages which have changed location, a custom mapping can be added in www/media/404.php so that the user can be directed to just about anywhere.
    Now the caption "Search" becomes german "Suche".


      <?php
    If you want to translate random text of your web page you have to use one of the three i18n functions available, that is i18n(), i18n_var() and i18n_noop().
        include("handler.inc");
    * i18n is the function you want to use if you simply want to show a text that would be translatable, e.g.
       
    <syntaxhighlight lang="php">
        $handler = new Handler404();
    <p><?php i18n("Some images of Okular in action...")?></p>
        $handler->add("/faq.html", "/faq");
    </syntaxhighlight>
        $handler->add("/events.html", "http://events.kde.org/");
    * 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.
        $handler->execute();
    <syntaxhighlight lang="php">
      ?>
    <?php $site_title = i18n_var("Okular - more than a reader"); ?></p>
    </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.
    <syntaxhighlight lang="php">
    <?php $page_title = i18n_noop('Frequently Asked Questions'); ?></p>
    </syntaxhighlight>


    You must call execute() otherwise it won't work!
    If you want to show a language selector in your webpage you have to define the site_languages variable to hold the supported languages.
    <syntaxhighlight lang="php">
    <?php $site_languages = array('en', 'es', 'pt_BR', 'uk'); ?></p>
    </syntaxhighlight>

    Revision as of 19:11, 29 November 2012

     
    Important!
    This project page has been moved to community.kde.org. 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"; ?>
    

    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');
    ?>
    

    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
    
    • $site_root contains the relative path to the toplevel of the current site, like:
    $site_root = "../.."
    
    • $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"
    
    • $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
    
    $current_relativeurl = whatiskde/manifest.php
    

    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"
    

    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";
    
    • The title of the individual page.
    $page_title = "Page Title";
    
    • 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;
    

    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 =&amp; $this->appendSection("Inform");
      $section->appendLink("Home","");
      $section->appendLink("KDE Home","http://www.kde.org/",false);
      
      $section =&amp; $this->appendSection("A Second Menu Section");
      $section->appendDir("A Subdirectory","subdirectory");
      $section->appendLink("A Single Page","singlepage.php");
    ?>
    

    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");
    

    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");
    

    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");
    ?>
    

    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):

    <h2><a name="section1" />Section Headline</h2>
    <h3>Subsection Headline</h3>
    

    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:

    <div id="quicklinks"> [
      <a href="section1">Section Headline</a> |
      <a href="section2">Second Section Headline</a> |
      <a href="section3">Third Section Headline</a> ]
    <div>
    

    If you wish to link <h3> headlines as well, then you can use:

    <div id="quicklinks">
    <p>
      <b><a href="section1">Section Headline</a></b>: <br />; [
      <a href="section11">Subsection Headline</a> |
      <a href="section21">Second Subsection Headline</a> |
      <a href="section31">Third Subsection Headline</a> ]
    </p>
    <p>
      <b><a href="section2">Second Section Headline</a></b>: <br /> [
      <a href="section21">Subsection Headline</a> ]
    </p>
    </div>
    

    Each site can have it's own right-side header-logo, like http://conference2006.kde.org. You just need to add a site.png to the top-level directory of your site, the framework will add it automatically if it finds one. Look at http://conference2006.kde.org/site.png for the correct dimensions. While a transparent background would be preferred, atm the Internet Explorer has problems with transparent PNGs, and GIFs are (were) problematic because of patents. Therefore the background needs atm to be duplicated in the image like done for the conference site.

    News

    The kde_general_news() can be used to easily show a new story on a page.

    <?php
      kde_general_news($file, $items, $summaryonly)
    ?>
    

    The parameters of kde_general_news() are as follows:

    • $file - The relative path to the news.rdf file. This will generally be "./news.rdf".
    • $items - The number of news stories to show.
    • $summaryonly - Whether to show the summary only (e.g. for index.php) or the full stories (news.php).

    FAQs

    A PHP class has been written to make it easy to write FAQs. It will always give a consistent formatting style. Using the class is simple:

    <?php
      $faq = new FAQ();
      $faq->addQuestion("This is the text of the question",
        "This is the text of the answer");
      $faq->show();
    ?>
    

    Note: the page won't be rendered until you call show(). Please use this class rather than hand constructing a FAQ to save your time and to improve consistency.

    Image Galleries

    A PHP class has been written to make it easy to write image galleries. The image galleries can link to enlarged versions of the image, but this isn't compulsory. Using the class is simple:

    Tip
    If you want to have a fancy Image Gallery with Lightbox, pass True as the second argument to the imageGallery class.


    <?php
      $gallery = new ImageGallery("Add a summary for screen readers here");
      $gallery->addImage("pics/image_sm.png", "pics/image.png", "640", "480",
        "Alt text", "Image caption (top)", "Image description (bottom)");
      $gallery->startNewRow();
      $gallery->addImage("pics/image_sm.png",  0, "640", "480",
        "Alt text", "Image caption (top)", "Image description (bottom)");
      $gallery->show();
    ?>
    

    The first call to addImage() creates an image that can be clicked on to link to a larger version of the image. startNewRow() creates a new row. The second call to addImage() creates an image that isn't clickable (note the 0 rather than the URL to the large image).

    The parameters of addImage() are as follows

    addImage($src_url, $dest_url, $width_pixels, $height_pixels,
             $alt_text, $caption_text, $description_text)
    
    • $src_url - The URL of the thumbnail image. If it is empty (""), then only caption and description will be shown.
    • $dest_url - The URL of the enlarged version of the image. The caption and the description will be links as well if $dest_url is specified.
    • $width_pixels - The width of the image in pixels
    • $height_pixels - The height of the image in pixels
    • $alt_text - A short description of the image for use in the alt="" tag (used by non-graphical browsers and screen readers)
    • $caption_text - A short caption which will appear above the image in bold (optional)
    • $description_text - A short description of the image which will appear underneath (optional)
    Warning
    The page won't be rendered until you call show()

    Please use this class rather than hand constructing an image gallery to save your time and to improve consistency.

    Application Information Page

    For web sites like koffice.org and edu.kde.org it makes sense to have a sub-directory for each program that is part of the project and in that sub-directory have a page which shows information about the program. The AppInfo class has been designed to make it easy to create such a page. It can be used as follows:

    <?php
      $appinfo = new AppInfo("KWord");
      $appinfo->setIcon( "pics/hi48-app-kword.png", "48", "48");
      $appinfo->setVersion($kwordversion);
      $appinfo->setLicense("lgpl");
      $appinfo->setCopyright("1998", "the KWord Team");
      $appinfo->addAuthor("Reginald Stadlbauer", "[email protected]");
      $appinfo->addAuthor("Torben Weis", "[email protected]");
      $appinfo->addContributor("David Faure", "[email protected]");
      $appinfo->addContributor("Thomas Zander", "[email protected]");
      $appinfo->addContributor("Shaheed Haque", "[email protected]");
      $appinfo->addContributor("Laurent Montel",
        "[email protected]");
      $appinfo->addContributor("Sven Lüppken", "[email protected]");
      $appinfo->show();
    ?>
    

    The second and third parameters of setIcon() are the width and height of the icon. The addContributor() function can take an optional third parameter, a short description of the person's function in the project.

    Common Mistakes

    When converting pages, it is important to keep a few common mistakes in mind: Every page must have $page_title set to ensure correct rendering on all styles. This also means that the original heading must be removed. Otherwise the headline will be duplicated when setting $page_title.

    • All settings have to be made before header.inc is included.
    • There cannot be several links on the same page that use the same description for different URLs. This is required for compatibility with certain accessibility related solutions. <a href="foo.php">More...</a> should be replaced by <a href="foo.php">More about KDE 3.x.y</a>, etc.
    • The new layout uses UTF-8 as encoding. A lot of pages contain non-ASCII characters in names etc., make sure to either convert those to UTF-8 or use their HTML names.
    • The new layout uses XHTML. All tags without an end tag must be converted from <tag> to <tag />, e.g. <img src="..." alt="..." />. The alt attribute is required for a better accessibility of KDE.org. Additionally, attributes without a value are treated differently in XHTML, e.g. <table nowrap> would become <table nowrap="nowrap">.
    • Please ensure that you use JPG or PNG images rather than GIF
    • Images for a particular area/directory should be placed under a pics/ subdirectory

    404 Handler

    All sites use a custom 404 handler page which is written in PHP. The handler is implemented in the Handler404 class. It has these features:

    • If foo.html is requested and foo.php exists, the user is redirected to foo.php.
    • If foo.htm is requested and foo.php exists, the user is redirected to foo.php.
    • If foo.phtml is requested and foo.php exists, the user is redirected to foo.php.
    • etc...

    For pages which have changed location, a custom mapping can be added in www/media/404.php so that the user can be directed to just about anywhere.

    <?php
      include("handler.inc");
      
      $handler = new Handler404();
      $handler->add("/faq.html", "/faq");
      $handler->add("/events.html", "http://events.kde.org/");
      $handler->execute();
    ?>
    

    You must call execute() otherwise it won't work!

    i18n - Translate interface to other languages

    English words like "search" are not useful for pages like e.g. german.

    Create a file named "locale.inc" in root folder and use the following content:

    <?php
      $site_locale = "de";
    ?>
    

    Please adjust the abbreviation to your needs.

    Now the caption "Search" becomes german "Suche".

    If you want to translate random text of your web page you have to use one of the three i18n functions available, that is i18n(), i18n_var() and i18n_noop().

    • i18n is the function you want to use if you simply want to show a text that would be translatable, e.g.
    <p><?php i18n("Some images of Okular in action...")?></p>
    
    • 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.
    <?php $site_title = i18n_var("Okular - more than a reader"); ?></p>
    
    • 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.
    <?php $page_title = i18n_noop('Frequently Asked Questions'); ?></p>
    

    If you want to show a language selector in your webpage you have to define the site_languages variable to hold the supported languages.

    <?php $site_languages = array('en', 'es', 'pt_BR', 'uk'); ?></p>