Extension:ScreenPlay

From MediaWiki.org
Jump to: navigation, search
MediaWiki extensions manual
Crystal Clear action run.png
ScreenPlay

Release status: unknown

Implementation Tag, Special page
Description Allows use of MediaWiki as a screenwriting tool.
Author(s) CJ Niemira
License GNU GPL
Download http://siege.org/pub/mwspe/

Translate the ScreenPlay extension if it is available at translatewiki.net

Check usage and version matrix; code metrics

The MediaWiki ScreenPlay Extension (ScreenPlay) is a text-formatting add-on which allows screenwriters and hobbyists the ability to use MediaWiki as a screenwriting tool.

Synopsis[edit | edit source]


<screenplay>An example is described</screenplay>

<scene int day>A '''Darkened''' Room</scene>

[[Bob Ross|BOB]] sits in front of a computer screen.

;bob
:Hello friends, I'm so glad you could join us. We're gonna make a happy little program today.
;voice
:(offstage)
:Oh goodie!

<trans>the end</trans>


Will produce the following type of formatting:


INT. - A DARKENED ROOM DAY
BOB sits in front of a computer screen.
BOB
Hello friends, I'm so glad you could join us. We're gonna make a happy little program today.
VOICE
(offstage)
Oh goodie!
THE END


Note how word case has been adjusted in certain cases.

Description[edit | edit source]

ScreenPlay supports three new editing hooks to add style codes that visually re-format certain wiki syntax (specifically, those used for definition lists, or "dl's") into proper screenplay format. The extension also adds a new "Special" page, which produces PDF output for a hard copy. PDF output provides additional notation, including page and scene numbering and dialogue continuation notes.

Though ScreenPlay is not a replacement for a full-featured ScreenWriting software package, it offers a number of advantages for screenwriters:

  1. It's free (most decent screenwriting software is expensive).
  2. You have the advantages of a wiki (including built-in version control, distributed access, multiple user edits, etc...)
  3. You can export as a PDF document which can be printed.
  4. Using wiki-links, you have a built-in reference system for notes, character drafts, images, etc...
  5. It's easily extendable.

Usage[edit | edit source]

Installing ScreenPlay is as easy as installing any other MediaWiki extension. Create a subdirectory named 'screenplay' in the 'extensions/' directory of your MediaWiki installation. Then download and extract the php source file (there's only one) and copy it into the 'extensions/screenplay/' directory. Add an appropriate include to your LocalSettings.php file. For example:

#
# This section is for ScreenPlay tags
require_once("$IP/extensions/screenplay/ScreenPlay-0.5.php");
#

Once installed, it is a simple matter to use ScreenPlay. Create a new wiki page, and begin by putting a '<screenplay>' tag on the first line as directed below. When rendered, this page will now contain screenplay formatting. To add a scene, use the '<scene>' tag as directed below. Stage directions are entered as normal paragraphs, and dialogue is written using "dl" syntax, (the ';' and ':' characters). The "dl" method is used because by simply changing the style attributes associated with them, the "dt" and "dd" html elements become the perfect tool for formatting dialogue (due to their already logically correct structure). Beyond that, you can use any built-in wiki formatting you desire. Be warned, however, that the PDF engine does not yet support additional formatting codes. PDF output may not look as you expect it.

Hooks[edit | edit source]

For correct PDF processing, all hooks should start and end on the same line.


<screenplay>Title</screenplay>[edit | edit source]

The 'screenplay' hook is used to activate the extension. The value of 'title' is used in the construction of a title page by the PDF engine. See below. This tag should appear near the top of your document, ideally as the first line. It can also be included through a template (though doing so removes the title page from a generated PDF), but again... keep it near the top.

The tag actually inserts a <style> code block into the output HTML which changes the default style attributes of the definition lists used to create dialogue. In addition, a <script> block is also inserted. It is this which adds a new entry to the top tab list for viewing the document as a PDF.


<scene (int|ext) time>Location</scene>[edit | edit source]

This hook is used to add a scene heading to your screenplay. A standard scene heading usually looks somthing like this:

INT. - Big Momma's House    DAY

Where we identify if it is interior or exterior, where the location is, and the time of day. The 'scene' hook allows you to do that easily.


<trans>Transition Type</trans>[edit | edit source]

The transition hook is used at the end of a scene to add... well... a transition note. "CUT TO," "FADE TO," "THE END," whatever...

Title Pages[edit | edit source]

ScreenPlay will add a title page to a generated PDF file if there is anything between the <screenplay> hooks. A simple text string will result in a plain title page with a "by" line that reflects the login ID of the individiual that authored the wiki page.

For a more proper title page, you can enter a simple XML snippit instead. Available XML title page tags are:

  • <title>
  • <author>
  • <address>
  • <phone>

Tags are used one for each line of output (though only the first <title> is used) in place of using new-lines. The following example demonstrates a two-line address:


<screenplay>
<title>Sample Screen Play</title>
<author>CJ Niemira</author>
<address>123 Anywhere St</address>
<address>Albuquerque NM 01234</address>
<phone>555-765-4321</phone>
</screenplay>

Note that when used in this way, the <screenplay> hook does not have to start and end on the same line.


Special Pages[edit | edit source]

One new "Special" page is added to your wiki if PDF support is available. [[Special:ScreenPlayPDF]] is created, and automatically linked to the top of any ScreenPlay page. When referenced, this page uses the built-in PDF library provided by PHP to convert your document to a savable PDF file.


PDF output uses PHP's built-in PDF API. If your copy of PHP is not compiled with PDF support, you can still write and view your screenplay in MediaWiki, but the PDF output function will not work. Adding PDF functionality to PHP is beyond the scope of this document.


The default configuration allows for on-disk caching of created PDF files by document edition number. That means once you create a PDF document, the cache remains in use either until deleted or the source document (the wiki page) is changed. You can create a PDF of any previous edition of a document by finding it in history and clicking "view pdf" (provided, of course, that the edition in question supported ScreenPlay).


Instructions for adjusting the default configuration are found in the ScreenPlay source file. You should make all changes in your LocalSettings.php file. Some of the settings you can change include:

  • PDF creation cache control
  • Paper size and all print margins
  • Font face and size

Compatibility[edit | edit source]

ScreenPlay was writen written and tested with a standard MediaWiki 1.5 installation under PHP 5.0.5. As usual, YMMV. Please report your success/failures:


Compatability Matrix
PHP MediaWiki Status
4.3.11 1.5 Working
5.0.5 1.5 Working


Version and ChangeLog[edit | edit source]

The Latest version is 0.5

To Do List[edit | edit source]
  • Support for wiki markup (bold, italic, etc...)
  • Support for includes
  • Needs a better way of dealing with configurations
  • Pre-configured paper/font formats would be nice
0.5[edit | edit source]
  • Adjusted use of PDFlib to be compatable with PHP 5.0+ (thus, for use MediaWiki 1.7+)
0.4[edit | edit source]
  • Feature add: title page generator added to PDF engine
  • Bug fix: default character width was wrong
0.3[edit | edit source]
  • Proper documentaion was added
  • Feature add: caching PDF documents
  • Feature add: oldid recognition
  • Feature add: scenes numbered in PDF
  • Feature add: PDF API detection
0.2[edit | edit source]
  • PDF transformer is now internal, and written in PHP
  • Feature add: <trans> tags
  • Feature add: "view pdf" tab at the top of article
0.1[edit | edit source]
  • Initial version

Author[edit | edit source]

The ScreenPlay extension was written by CJ Niemira <siege (at) siege (dot) org>.

Source[edit | edit source]

ScreenPlay is licensed under the GNU GPL.

It is available from its home at:
http://siege.org/pub/mwspe/

Or through its Subversion repository (requires a password) at:
https://www.siege.org/svn/oss/wikiExtensions/trunk/ScreenPlay.php