Quickstart Guide

This guide will get you on your way to easy script installation.

Introduction

Firstly, the installation process in general is a series of sequential steps aimed at gathering information from both the user and the software environment using an simple wizard-like interface. PIS provides a simple array of tools which provides the framework to any installation process.

For instance, the PIS::input() function will insert a text area, select box or license agreement into an installation page which then takes and stores a user’s response in the installation-wide heap of variables.

Each installation process has a heap of variables either set by the script as a result of environment tests, or by the user specifying a configuration setting. This heap is accessible during the entire installation process, from page to page.

Getting Started

1. Download and unzip the PIS package. The only files required for an installation script are pis.php and your actual installation file. You may have additional files such as images or javascripts which decorate the wizard. ( For an example of a more decorated installation, try launch-install.php )
   
2. Next open up sample1.php. This file provides a basic template to start your installation script.
3. You should see a class definition named MyInstaller derived from the PIS class. Inside this class are a series of methods defined as page_somename().

   Every installation step is really a seperate method defined in the installation class. So the first step in the installation is going to call page_welcom(). It is inside these page methods that we construct each page’s elements. The steps proceed in the order the methods were defined in the class.

4. Now that we have methods for every page, we can call the inherited methods defined in the PIS class to create each page’s content. Below are a list of useful methods for creating page content.
   //Adds a text block to the page//
   $this->message ( "A text message" );

   //Adds a form input to the page, automatically sets the
   //value in the heap when submitted.
   $this->input ( "text", "varname" ,array("attribute"=>"value") );

   //Test for something, if it fails, will prevent installation from proceeding
   $this->test ( sometest(), "Some Test Failed" );

   //Can be used to conditionally bypass a step(method) //
   $this->bypass ( ‘previouspage’, ‘nextpage’ );

   //Retreive a variable from the heap//
   $this->get( ‘varname’, ‘defaultifblank’ );

   //Manullay set a variable in the heap//
   $this->set( ‘varname’, ‘value’ );

   //Inserts a <hr /> tag into the page//
   $this->hr();

   //Creates a configuration file/string from the heap of variables//
   $this->makeConfig();

5. After defining the the class, the next step would be to create an instance of it.
   //The first parameter will determine the <h1> title of the installation
   //process.
   $installer = new MyInstaller( ‘My Installer’ );

   //Another useful technique is if you have a couple different
   //installation classes such as a new install verses an update
   //script, you can define both then create one depending on some
   //outside state.

   if ( $isUpdate ){
      $installer = new MyUpdater( ‘My Updater’ );
   } else {
      $installer = new MyInstaller( ‘My Installer’ );
   }

6. Finally in the body of the HTML (after defining your CSS styles, attaching additional javascript and making a web page shell) call the PIS::run() method to create the installation process.
   $installer->run();
7. Please test your installation before deploying. IMPORTANT!! Be sure to either remove the installation script by force or require the user to remove it manually as this is something that CAN be a security issue if left on the server!

Quick Reference

Input Types

text – creates a simple text input field.
password – creates a simple password input field.
hidden – creates a hidden form field.
select – creates a select box. Its options are specified in the "options" attribute as an associative array. The key determines the label, value the option value.
textarea – creates a textarea input.
boolean – creates a true/false dropdown for those config file flags.
agreement – creates an agreement input consisting of a textarea and checkbox asking for agreement to the license. This input accepts an additional attribute named file which when set to the path of the license file (mit.txt,gnu.txt,etc) will load it into the textarea.

Common Attribute Types

The input attributes are set using an associative array passed to the input() function.
required – Will require the user to enter something.
label – The label for the field. Defaults to input id parameter.
help – The help string for more information on the field. This string is pushed into a javascript alert box and triggered by adding a "?" next to the field.
value – Default value of the field.
options – Currently only for select input, must be an associative array of key=value pairs.
file – Currently only for agreement input, path to a license text file to load into a page.

Input Reference Table

Leave a Reply