Extension:APF - Advanced Page Functions

From MediaWiki.org

Jump to: navigation, search

           

Manual on MediaWiki Extensions
List of MediaWiki Extensions
Crystal Clear action run.png
APF - Advanced Page Functions

Release status: Beta
Implementation  Parser function
Description Updated and internationalized versions of some of the most commonly used page functions
Author(s)  Marilou Sargado (msargadoTalk)
Last Version  Beta 0.3 (August 1st, 2009)
MediaWiki  1.14, 1.15
License GPLv3
Download Download Snapshot

check usage (experimental)

Contents

[edit] Why would you want to use this extension

When you're looking to add functionality to your MediaWiki you'll want to minimize the time you spend adding, checking and updating different extensions. If you are looking for an extension that provides the most commonly requested page layout functions in one package then this extension should meet your needs. This extension is built to the latest MediaWiki standards, it already combines the functionality of twenty smaller extensions and new functionality is being added with each monthly release. Please try the beta code and if you find anything wrong or see any functionality that you would like added then I would like to hear from you: Bugs, Comments and Feature Requests

[edit] What can this extension do?

Beta 03 code allows you to:

  1. Change the heading that appears at the top of an article
  2. Change the name of the page that appears at the top of the browser
  3. Set the meta description that will be used in a search engine listing.
  4. Set the meta keywords that are used by some search engines.
  5. Append to the default meta keywords that are used by some search engines
  6. Add custom meta information
  7. Add per page inline CSS
  8. Add per page CSS from an external file
  9. Change the robots meta setting so that search engines will not index a page
  10. Add raw content from a file directly to a page
  11. Embed a flash movie anywhere on a page using two different formats for the source code
  12. Add content from an external file to your page

Beta 04 code will also allow you to:

  1. Embed a YouTube movie on a page

[edit] Adding or changing page heading, article name and page description

  • {{ page.head: text }}

This page function is used to change the heading that appears at the top of the article page. It does this by modifying the text that appears on the article page for the H1 element with id='firstHeading' and class='firstHeading. The article will still be stored in your wiki with the original name and the only thing this function changes is the name that appears on your screen.

  • {{ page.name: text }}

This page function is used to change the name / title of the page that appears in the top of the browser window, in search engines and as the words to describe your page when someone adds it to their "Favorites" or "Bookmarks" lists.. The text you use in the page.name tag is one of the most important factors in how a search engine may decide to rank your web page. In use the function changes the title by placing the text you specify inside of the <title></title> tag. Search engines like Google will use the title as part of their page ranking. Even though Google cuts off the display at roughly 63-64 characters (depending on your own word breaks), it will read beyond what is actually shown and use what is after the ellipses (...) as a ranking factor. Some other engines also display more. Yahoo! recommends 67 characters as a limit but depending on word breaks it will show up to 72. To be safe I recommend that you try to keep the length of the title to less than 70 characters if you don't want the title to be trucated.

  • {{ page.desc: text }}

This page function is used to set the page meta description. It does this my adding the description to the <meta name="description" content=""> tag. The meta description tag allows you to influence the description of your page in the search engines that support the tag. Here's some advice from Google about what to include in a description. There are exceptions but the typical maximum character lengths are Bing (185), Yahoo (161)an Google (156). With this in mind I suggest you try to keep the length of your description to less than 150 characters.

[edit] Adding or changing keywords and page meta information


  • {{ page.keys: key1, key2 }}

This page function is used to set the page meta keywords. These keywords are officially no longer used by the larger search engines however if you still want to use them then it's generally considered that the length of the keywords should be less than 255 characters and the same keyword should not appear more than three times in the string. By default MediaWiki assigns default meta keywords from the headings and links that it finds on a page. Often these are not appropriate and you can use this function to replace the existing keywords. This function replaces the text in the content area of the <meta name="keywords" content="" /> on your source page.

  • {{ page.addk: key1, key2 }}

By default MediaWik takes the title, categories, existing and broken links for the page and uses the first 10 of them for META keywords. This function allows you to leave the default choices and add additional keywords. When you use this function you should consider the points made above regarding the way search engines use the keywords. If you want to check the default links that MediaWiki has chosen then check the source code of the page and look for the <meta name="keywords" content="" /> string that MediaWiki creates in the header area. After you've added new keywords and saved the page you have edit check the source and you will see new keywords have been added.

  • {{ page.meta: name="name" content="content" }}

This page function is used to add to add custom meta information

[edit] Adding or changing CSS on your page

Use these functions to add new CSS to your page. If you use both of these functions on your page then the CSS generated from the page.cssd will take precedence over that from page.cssf as it will appear later. This allows you to fine-tune the CSS on the page and override CSS styles that were added from the imported files.

  • {{ page.cssd: <css> }}

This page function can be used to add additional inline custom CSS styles to a page. To use the function, replace <css> with the CSS style commands, edit your page and place one or more of these page functions anywhere on the page. The CSS will always be added to the top of your MediaWiki page when the page is generated. If you have more than one call then the CSS styles from each call will be added in the order that the functions appear on the page. When you use this function a sanity check on the CSS is performed. This check stops a user from entering various words such as 'expression', 'http', 'https', 'ftp', 'url' etc.

  • {{ page.cssf: <filename> }}

To add CSS styles from a file(s) that you have placed in the /extensions/APF/CSS directory, replace <filename> with the name of the file containing your CSS styles, and enter the page function(s) anywhere on your page. If you prefer to store your CSS files in another directory then set the $apfCssDir global variable in your LocalSettings.php file. For example: $apfCssDir = "C:\wamp\www\wiki5\mw\extensions\APF\CSS_FILES";. If you have more than one call then the CSS styles from each call will be added in the order that the functions appear on the page. When you click save then an error message will be generated if you attempt to use a file not in the /extensions/APF/CSS directory or the directory that you have specified by adding an entry for the $apfCssDir variable in your LocalSettings.php file.

[edit] Adding a Flash movie to your page

  • {{ page.swf1: param='val', param='val' }}

This function can be used to embed a flash movie in your page. The default directory searched for the flash movie is $IP/images. Where $IP is your MediaWiki installation directory. You can specify an alternate directory by setting the $apfSwfDir global variable in your LocalSettings.php file. For example: $apfSwfDir = "C:\wamp\www\wiki5\mw\extensions\APF\SWF_FILES"; if you attempt to use a file not in the /images or user specified directory then an error message will be generated. When using this function you can specify any of the following parameters as arguments for the flash movie: align, base, bgcolor, classid, codebase, devicefont, file, height, loop, movie, menu, play, quality, salign, scale, src, swliveconnect, width, wmode. Use of any other parameter will result in an error message. Note that all parameters with the exception of file are optional. You must use the 'file=' parameter to specify the flash movie filename. If you do not specify them then the following defaults apply: height=500px, width=500px

  • {{ page.swf2: param='val', param='val' }}

Adds a flash movie in the same way as page.swf1 however the generated HTML code is more suitable for older browsers.

[edit] Adding content from a file to your page

  • {{ page.file: filename.txt }}

To add content from a file(s) that you have placed in the /extensions/APF/FILE directory, replace <filename> with the name of the file, and enter the page function(s) anywhere on your page. If you prefer to store the files in another directory then you change the source directory by setting $apfFileDir global variable in your LocalSettings.php file. For example: $apfFileDir = "C:\wamp\www\wiki5\mw\extensions\APF\DATA_FILES";

[edit] Examples of how to use these functions

To use the functions edit a page and then enter the function calls in the source window. With the exception of the functions that are position defendant I would suggest you add the function calls to the top area of the edit window where you can easily see them should you want to go back and make changes.

  • Adding or changing page heading, article name and page description:
### Page functions added in the editor: ###

{{ page.name: Cebu Hotels in Philippines }}
{{ page.desc: Cebu hotel listing }}
{{ page.head: Cebu Hotel }}

### Results in the following code added to your HTML source: ###

<title>Cebu Hotels in Philippines</title>
<meta name="description" content="Cebu hotel listing" />
<h1 id='firstHeading' class='firstHeading'>Cebu Hotel</h1>
  • Adding or changing keywords and page meta information:

Note that page.addk and page.keys are mutually exclusive so you can only use one or the other and not both page functions on the same page. Here I show you them used together but this it just to show you a sample of the output from each. Do not use both on the same page.

### Page functions added in the editor: ###

{{ page.addk: Cebu, Hotel }}
{{ page.keys: Cebu, Hotel }}
{{ page.meta: name="ROBOTS" content="NOINDEX,FOLLOW" }}
{{ page.meta: http-equiv="name" content="content" }}

### Results in the following code added to your HTML source: ###

<meta name="keywords" content="Safety Food and Drink, Cebu, Hotel" /> 
<meta name="keywords" content="Cebu, Hotel" />
<meta name="ROBOTS" content="NOINDEX,FOLLOW" />
<meta http-equiv="name" content="content" />
  • Adding or changing CSS on your page
### Code added in the editor: ###

{{ page.cssf: sample.css }}
{{ page.cssd: #content h1,h2,h3 {color: #fff000;} }}
{{ page.cssd: #footer {
  background-color: red;
}
#header {
  background-color: black;
}
}}
{{ page.cssf: sample1.css }}

### Results in the following code added to your HTML source: ###
### Please note indentation is added here but not in source. ###

<style  type='text/css'>
@import '/wiki5/mw/extensions/APF/CSS/sample.css';
@import '/wiki5/mw/extensions/APF/CSS/sample1.css';
#content h1,h2,h3 {color: #fff000;}
#footer {
  background-color: red;
}
#header {
  background-color: black;
}
</style>
  • Adding a Flash movie to your page
### Code added in the editor: ###

{{ page.swf1: file='filename.swf' width=400 height='250' }}

### Results in the following code added to your HTML source: ###
### Please note indentation is added here but not in source. ###

<object classid='clsid:d27cdb6e-ae6d-11cf-96b8-444553540000' 
    width='400' 
    height='250' 
    id='/wiki5/mw/images/filename.swf' 
    codebase='http://fpdownload.macromedia.com/pub/shockwave 
/cabs/flash/swflash.cab#version=8,0,0,0'>
<param name='movie' value='/wiki5/mw/images/filename.swf'>
<embed src='/wiki5/mw/images/filename.swf' 
    width='400' 
    height='250' 
    type='application/x-shockwave-flash' 
    pluginspage='http://www.macromedia.com/go/getflashplayer'>
</embed></object>

### Code added in the editor: ###

{{ page.swf2: file='filename.swf' width=400 height='250' }}

### Results in the following code added to your HTML source: ###
### Please note indentation is added here but not in source. ##

<object classid='clsid:D27CDB6E-AE6D-11cf-96B8-444553540000' 
    width='400' 
    height='250'>
    <param name='movie' value='/wiki5/mw/images/filename.swf' />
    <!--[if !IE]>-->
    <object type='application/x-shockwave-flash' 
    data='/wiki5/mw/images/filename.swf' width='400' height='250'>
    <!--<![endif]-->
    <p>Alternative content</p>
    <!--[if !IE]>-->
    </object>
    <!--<![endif]-->
</object>
  • Adding content from a file to your page
{{ page.file: filename.txt }}


[edit] Download Instructions

Download the extension files from the latest Zip download Snapshot containing the following files:

/APF.i18n.magic.php
/APF.i18n.php
/APF_setup.php
/CSS/sample.css
/FILE/filename.txt
/includes/APF.php
/includes/APF_HTML.php
/includes/APF_Tag.php

and place these files in the following MediaWiki directory on your server:

$IP/extensions/APF/

$IP is your MediaWiki installation directory and if it doesn't already exist you must create a directory in the $IP/extensions directory named APF. All files and directories must be in this directory as the extension expects you to use this directory naming convention. Each new download snapshot of the software is a complete release and does not depend on any files from a previous release being present.

[edit] Internationalization Instructions

If you need to internationalize this extension make changes to the following files:

  1. /APF.i18n.magic.php
  2. /APF.i18n.php

Check the contents of the files for more information on what you will need to change to internationalize the functions for your language.

[edit] Installation

  1. In the directory in $IP/extensions create a new directory APF - where $IP is your MediaWiki installation directory.
  2. Copy the extension directories and files into the APF directory you just created
  3. Add the following line to the bottom of the LocalSettings.php in your MediaWiki installation directory: require_once('extensions/APF/APF_setup.php');
  4. Modify the files: APF.i18n.magic.php and APF.i18n.php if you need to internationalize this extension for another language.
  5. If you use the page.cssf function then store your files in the /extensions/APF/CSS directory
  6. If you use the page.swf1 function and if you want to allow users to upload their own swf files then add $wgFileExtensions[] = 'swf'; to LocalSettings.php. Files uploaded by users will be uploaded to the /images directory

[edit] Code

You can download zip files containing the extension code and sample files from this page: Download Snapshot.

[edit] Bugs, Comments and Feature Requests

At this stage in the development process my focus is on providing additional functionality with each new beta release. If you have a chance to try out this extension then I would very much appreciate your feed back if you are find any bugs. Please use the comment area on this page to notify me about bugs that you find and also tell if you have any feature requests: Bugs, Comments and Feature Requests

[edit] Dependency

  • No dependencies when used with MediaWiki 1.14 and above

[edit] Releases

Version Release date Notes
Beta 0.4 2009-09-01 I hope to have the next beta completed by the end of August. The next beta will add more functionality with not as many changes to the core code as with the first three betas. As of August 6th the following have been added: page.utb1 function has been added for uTube movies and page.indx has been added to switch on and off the robot meta.
Beta 0.3 2009-08-01 Some major changes were made to the code to improve functionality. Two additional classes (APF_HTML and APF_Utils) were created and the new page functions: page.swf1, page.swf2 and page.file were added. I've added some sample files to the download zip and these can be found in the CSS and FILE directories. When adding the new functions for flash I added the two different functions as it seems like there are more than a few schools of thought about how to embed flash in a page. If anyone needs anything different just let me know and I'll make a change or add another function. I added some new error messages and cleaned up some of the old ones. As far as the functions that were present in beta 02, all of those still work unchanged.
Beta 0.2 2009-07-01 Added page.cssf, APF_Tag class. Major code changes to improve functionality.
Beta 0.1 2009-06-01 Initial release

[edit] See also

This extension provides most of the functionality of the following 20 extensions in the one package:

If you find that you need additional functionality that's provided in one of the above extensions then I will be pleased to review your requests and add this functionality if possible. The only changes that I cannot make are those that might compromise your wiki security and those that would enable the extension to work on versions of MediaWiki earlier than 1.14.

Retrieved from "http://www.mediawiki.org/wiki/Extension:APF_-_Advanced_Page_Functions"