Revision [20133]
This is an old revision of WikiFile made by ChewBakka on 2008-07-18 05:18:16.
WikiFile action and handler
This pair of files allows you to attach files to wikipages.
I did everything in Wikka 1.1.6.2 so I can not tell whether it will work in older versions.
How to use it
Example: assume you have a photograph of the Millennium Falcon in a file named IMG_1234.JPG on your computer. You want to put it in the wiki.
So you edit the respective page and put the {{file}} placeholder at the place where you want to see the image.
MillenniumFalcon
===== Millennium Falcon =====
Below you see a photograph of the Millennium Falcon, last year on Tatooine.
There was lots of sand, as always.
{{file}}
Below you see a photograph of the Millennium Falcon, last year on Tatooine.
There was lots of sand, as always.
{{file}}
The page now shows a form which allows you to upload the file.
After uploading, you see the image in the page, and below the image another upload form is visible, in case you want to replace the photo with another one later. You can also delete the file.
Now, suppose you want to add more images to the same page. Then you need to distinguish the files by adding an id.
MillenniumFalcon
===== Millennium Falcon =====
Below you see a photograph of the Millennium Falcon, last year on Tatooine.
There was lots of sand, as always.
{{file}}
On the next images, some Jawas admire the mighty space vessel:
{{file id="jawas1"}}
{{file id="jawas2"}}
Below you see a photograph of the Millennium Falcon, last year on Tatooine.
There was lots of sand, as always.
{{file}}
On the next images, some Jawas admire the mighty space vessel:
{{file id="jawas1"}}
{{file id="jawas2"}}
As you see above, it is allowed to have one file per page which has no id. Also, don't worry about id of images on other pages - the id just need to be unique inside the wiki page.
Advanced usage
To display an image also on another page, you do not need to upload it twice. Instead, you can tell the file placeholder to fetch the image from a different page:
{{file page="PageWhichContainsTheFile"}}
How to install it
We are going to add two program files to the Wikka software, and create a folder.
In your Wikka root directory, there is a folder named actions which contains several php files. Save the following code (use the grab button) as file.php in the actions folder.
actions/file.php (line 1)
- <?php
- /**
- * WikiFile action
- *
- * Displays a file in the page (as image or link) and optinally an upload form.
- *
- * Syntax: {{file [id="IdUniqueInPage"] [page="PageToTakeFileFrom"]}}
- *
- * @package Actions
- * @name File
- *
- * @author {@link http://wikkawiki.org/ChewBakka ChewBakka} (first draft)
- */
- /**
- * Reads the file's metadata file and returns it as an array.
- *
- * @author {@link http://wikkawiki.org/ChewBakka ChewBakka} (first draft)
- * @input $tag name of the page; default = current page.
- * @output Array or (if no file in page) null.
- */
- {
- function getFile( $tag, $wikka, $id )
- {
- $data = null; // this variable will be returned
- $sep = ($id ? '~' : '' ); // Separator between tag and id in filename
- // Read the metadata from the file TagName~id.file
- $metafile = $wikka->config['upload_path'].'/'.$tag.$sep.$id.'.file';
- {
- // Lines look like "key: value" -> convert them to an array
- 'extension' => '', // file extension, e.g. 'png', 'jpg', 'ogg'
- 'content-type' => '', // mime content type, e.g. 'image/png'
- 'uploaded' => '?', // date and time, . e.g. '2007-01-31 18:00'
- 'uploader' => '?', // wikiname, e.g. 'ChewBakka'
- 'image' => 'false', // 'true' for image files
- 'width' => '', // width in pixels (images only)
- 'height' => '' // height in pixels (images only)
- );
- foreach ($lines as $line)
- {
- {
- }
- }
- // Add convenient attributes which can not be stored permanently
- $data['filename'] = $tag.$sep.$id . '.' . $data['extension'];
- $data['path'] = $wikka->config['upload_path'] .'/' . $data['filename'];
- $data['metafile'] = $metafile;
- $data['url'] = $wikka->config['base_url'] . $tag . '/file' . ($id?'?id='.$id:'');
- // Final check: file must exist.
- {
- $data = null;
- }
- }
- return $data;
- }
- }
- /**
- * Here the real action starts
- */
- // Initialize variables
- $output = ''; // The HTML code that is being generated by this action
- $uploadform = False; // Show an upload form instead of the file?
- $tag = $this->GetPageTag(); // The page that the user requested
- $id = ''; // Optional file id, appended to the tag name
- {
- $tag = $vars['page'];
- }
- {
- $id = $vars['id'];
- }
- if( $id )
- {
- // A file ID was submitted.
- // Check if it is alphanumeric and not longer than 100 characters
- // in order to prevent security issues.
- {
- $id = '!BAD!';
- $output = 'An illegal file ID was submittet';
- }
- }
- if( $id != '!BAD!' )
- {
- $data = getFile($tag,$this,$id);
- // Check whether current user has read access and if there is a file.
- if ($this->HasAccess( 'read', $tag ) && $data )
- {
- if ($data['image'] == 'true')
- {
- // Image file - create an <img> tag
- $output = '<a href="' . $tag . '">'
- . '<img src="' . $data['url'] . '"'
- . ' width="' . $data['width'] . '"'
- . ' height="' . $data['height'] . '"'
- . ' alt="' . $tag . '"'
- . ' border="0">'
- . '</a>';
- }
- else
- {
- // Plain file - create a download link
- $output = '<a href="' . $data['url'] . '">' . $data['url'] . '</a>';
- }
- }
- if ($this->HasAccess( 'write', $tag ) && $tag == $this->GetPageTag())
- {
- // If on the same page, also show an upload form
- $headline = 'Upload a file to appear here';
- $buttonlabel = 'Upload';
- $deletelink = '';
- if( $data )
- {
- $headline = 'REPLACE the '
- . ($data['image'] == 'true' ? 'image' : 'file' )
- . ' above by uploading a new file';
- $buttonlabel = 'Upload';
- . 'cmd=delete">DELETE</a>'
- . ' the '
- . ($data['image'] == 'true' ? 'image' : 'file' )
- . ' above from the wiki';
- }
- $miniref = $this->Href('file', $tag);
- $output = $output
- . '<br />' . $headline . ' <br />'
- . '<form action="' . $miniref . '" method="POST" enctype="multipart/form-data">'
- . (!$this->config["rewrite_mode"] ? '<input type="hidden" name="wakka" value="' . $miniref . '" />' : '')
- . '<input name="file" type="file" size="72">'
- . '<input type="hidden" name="id" value="' . $id . '">'
- . '<input type="submit" value="' . $buttonlabel . '">'
- . $deletelink
- . '</form><br />'
- ;
- }
- }
- print $this->ReturnSafeHTML($output);
- ?>
Also in your Wikka root directory, there is a folder named handlers, which in turn contains a folder names page which contains several php files. Save the following code (use the grab button) as file.php in the handlers/page folder. (Yes, we have two files with the same name, but in different locations and with different function).
handlers/page/file.php (line 1)
- <?php
- /**
- * WikiFile handler
- *
- * Supports file retrieval and upload.
- *
- * Syntax: http://server/WikiName/file[?id=someid]
- *
- * @package Handlers
- * @name File
- *
- * @author {@link http://wikkawiki.org/ChewBakka ChewBakka} (first draft)
- */
- /**
- * Reads the file's metadata file and returns it as an array.
- *
- * @author {@link http://wikkawiki.org/ChewBakka ChewBakka} (first draft)
- * @input $tag name of the page; default = current page.
- * @output Array or (if no file) null.
- */
- function getFile( $tag, $wikka, $id )
- {
- $data = null; // this variable will be returned
- $sep = ($id ? '~' : '' ); // Separator between tag and id in filename
- // Read the metadata from the file TagName~id.file
- $metafile = $wikka->config['upload_path'].'/'.$tag.$sep.$id.'.file';
- {
- // Lines look like "key: value" -> convert them to an array
- 'extension' => '', // file extension, e.g. 'png', 'jpg', 'ogg'
- 'content-type' => '', // mime content type, e.g. 'image/png'
- 'uploaded' => '?', // date and time, . e.g. '2007-01-31 18:00'
- 'uploader' => '?', // wikiname, e.g. 'ChewBakka'
- 'image' => 'false', // 'true' for image files
- 'width' => '', // width in pixels (images only)
- 'height' => '' // height in pixels (images only)
- );
- foreach ($lines as $line)
- {
- {
- }
- }
- // Add convenient attributes which can not be stored permanently
- $data['filename'] = $tag.$sep.$id . '.' . $data['extension'];
- $data['path'] = $wikka->config['upload_path'] .'/' . $data['filename'];
- $data['metafile'] = $metafile;
- $data['url'] = $wikka->config['base_url'] . $tag . '/file' . ($id?'?id='.$id:'');
- // Final check: file must exist.
- {
- $data = null;
- }
- }
- return $data;
- }
- /**
- * Store an http-uploaded file.
- *
- * @author {@link http://wikkawiki.org/ChewBakka ChewBakka} (first draft)
- * @input $uploaded_file An item from PHP's $_FILES array (see there)
- * @output None
- */
- function saveFile( $uploaded_file, $wikka, $id )
- {
- $pathname = $wikka->config['upload_path'] . '/' . $wikka->tag . ($id?'~':'') . $id;
- $path = $pathname . '.' . $extension;
- $contenttype = '';
- // Remove existing file if it already exists
- if ($data = getFile( $wikka->GetPageTag(), $wikka, $id ) )
- {
- // File exists; remove it first
- // E.g. if a GIF exists and the user replaces it with a PNG now.
- $data = null;
- }
- {
- // Find the mime type (it will be stored in the metadata)
- {
- }
- if( ! $contenttype )
- {
- switch( $extension )
- {
- // Quick resonse for most frequently used file types
- case 'png':
- $contenttype = 'image/png';
- break;
- case 'jpg':
- $contenttype = 'image/jpeg';
- break;
- case 'ogg':
- $contenttype = 'application/ogg';
- break;
- case 'zip':
- $contenttype = 'application/zip';
- break;
- default:
- // Use wikka's own mime_types.txt
- {
- {
- {
- {
- $contenttype = $a[0];
- break;
- }
- }
- }
- }
- }
- }
- // build an array with metadata
- 'extension' => $extension,
- 'content-type' => $contenttype,
- 'uploader' => $wikka->GetUserName(),
- 'image' => 'false'
- );
- {
- $data['image'] = 'true';
- $data['width'] = $size[0];
- $data['height'] = $size[1];
- }
- // Save the dat aarry in the metadata file
- $contents = '';
- foreach ($data as $key => $value)
- {
- $contents .= ($key . ': ' . $value . "\n");
- }
- }
- }
- /**
- * Here the real handler starts
- */
- $handled = False;
- {
- // A file ID was submitted.
- // Check if it is alphanumeric and not longer than 100 characters
- // in order to prevent security issues.
- {
- $cmd = 'nothing';
- }
- }
- {
- $cmd = 'upload';
- }
- switch( $cmd )
- {
- case 'upload':
- // User uploaded a file
- if ($this->HasAccess('write'))
- {
- $uploadedfile = $_FILES['file'];
- if ($uploadedfile['error'] > 0)
- {
- // redirect to page
- $this->redirect( $this->Href(), 'Transmitted file was damaged' );
- }
- else
- {
- saveFile( $uploadedfile, $this, $id );
- $this->Redirect( $this->Href() );
- }
- $handled = True;
- }
- break;
- case 'get':
- // Return the file
- if ($this->HasAccess('read') && $data = getFile($this->GetPageTag(),$this,$id))
- {
- if ($data['image'] != 'true')
- {
- }
- $handled = True;
- }
- break;
- case 'delete':
- // Delete the file permanently from the wiki
- if ($this->HasAccess('write') && $data = getFile($this->GetPageTag(),$this,$id))
- {
- }
- $this->Redirect( $this->Href() );
- $handled = True;
- break;
- }
- if( !$handled )
- {
- $this->Redirect( $this->Href() );
- }
- ?>
And now for the really last step - read your wikka.config.php, it should contain a line like this:
wikka.config.php (line 40)
- // ...
- 'upload_path' => 'uploads',
- // ...
This means that the Wikka root folder should contain a folder named uploads; please create this folder if it does not exist.
Should the above line not be in your config file, please add the line too.
Ready! If something does not work yet, leave me a comment. --ChewBakka
How it works
Behind the scenes, an uploaded file is stored in the uploads directory along with a metadata file. In the example above, Wikka stores the uploaded file IMG_1234.JPG as MillenniumFalconOnTatooine.jpg along with MillenniumFalconOnTatooine.file which contains the metadata. The latter is a plain ascii file which tells Wikka that the actual file is a jpg file.
History
2007-Feb-05
handlers/page/file.php: bugfix (switch without break, now if/elseif); sends filename with download (makes download easier)
libs/Wakka.class.php: supports *.*.gz
2008-Jul-15
Complete rewrite.
Only ACTION and HANDLER; no more Wikka.class.php modifications.
2008-Jul-18
Multiple files per page now possible.
Credits
While developing the above code, I browsed through many Wikka sources in order to learn how to write a good extension, and how to document it. They were too many to remember, so I just want to say thanks to all the people who made Wikka.
Category: CategoryUserContributions User contributions