Package Creation

Summary   : How to create your own Facile Forms packages
Author    : Larry Stavinoha
Created   : 2005-11-04
Revisions :
Based on  : Facile Forms 1.4.3,  Joomla 1.0.8 
Applies to: Facile Forms 1.0.0 ... 1.4.4, Joomla 1.0.0 ... 1.0.8, Mambo 4.5.1 ... 4.5.3

Preface

With Facile Forms, you can easily create forms and applications consisting of Scripts (Javascript), Pieces (PHP), Forms and Backend Menus for use in your Joomla/Mambo environment. These forms and applications can then be easily moved from one website to another by creating a Facile Forms Package.

Facile Forms Packages can be created as Named Packages or as Unnamed Packages. When creating Named Packages, all related forms, scripts, pieces and backend menus share a common Package Name. Packages created in this manner have the advantage that when installed into another Facile Forms instance, any existing package with the same name will automatically be removed. This makes it easy for you to provide an upgrade path to users of your packages.

When creating Unnamed Packages, individual items are chosen for inclusion in a package. When this unnamed package is installed into another Facile Forms instance, no scripts, forms, pieces or backend menus will be removed. This could cause you to have multiple scripts, forms, pieces and backend menus with the same name, leading to some confusion.

Facile Forms packages also allow you to include version, contact, and copyright information about your form or application. Please note that no frontend Joomla/Mambo menus will be included in a Facile Forms package. Any frontend Joomla/Mambo programming or menus must be recreated separately.

There is one important point concerning emailing forms to be aware of when distributing your forms or applications. If you have specified in any of your forms that the Email Notification should go to a custom address, the custom email address will also be distributed in the package. If you leave this feature set in your forms, you could end up getting email from other websites that you did not expect after distributing your package.

This chapter will outline creating both a Named package and an Unnamed package. This chapter references the Hello World scripts, forms and backend menus created in the Hello World chapter.

Creating the Named Package

When creating a Named Package, all related forms, scripts, pieces and backend menus share a common package name. This Package name was entered at design time for the various items. For the Hello World sample, all of the items had the package name "Hello World" entered at design time.

• From the Joomla/Mambo Administrator backend, click on the menu Components->Facile Forms->Configuration. This will open up the Facile Forms Configuration screen.

• Near the bottom left corner, click on the Create Package button. This will open up the Facile Forms - Create Package screen.

• From the ID select list, choose "Hello World". By specifying the ID in this manner, Facile Forms will automatically include any forms, scripts or pieces that have a package name of "Hello World". Once the ID has been selected, the named Create Package screen is shown.

• In the Package Name text box, enter hello_world. This will be the "stub" file name for your xml package when it is created. As you refine your forms and applications, you may wish to include the version number in your package name. This is a developer preference. If you wish to use this convention, then you would enter hello_world_001 in the Package Name text box.

• In the Package Version text box, enter or leave it as 0.0.1. As you refine your packages, you will want to adjust the version number appropriately.

• In the Package Title text box, enter Hello World.

• In the Author Name text box, enter your name.

• In the Author Email text box, enter your email address.

• In the Author URL text box, enter your website address.

• In the Description text box, enter a description of your package.

• In the Copyright text box, enter your copyright information.

The Named Create Package screen should now look similar to this:

Click on the Continue button. This will start a download process in your browser to download your package file, "hello_world.xml". Depending upon the browser that you are using, its settings, and your operating system, you may receive different prompts concerning saving the file. Notably, in some versions of Internet Explorer, you may receive the yellow Information Bar across the top asking if you would like to download the file. If you choose to Download File, you will then be prompted with the Open or Save dialog box. You should choose Save.

Once the package has been created, Facile Forms will remember your version, contact, and copyright settings for this package.

Now you have a Named "hello_world.xml" Package file that you can distribute to other Facile Form users.

Creating the Unnamed Package

When creating an Unnamed Package, you choose any forms, scripts, pieces and backend menus that you would like to include in the package, regardless of any package name. Creating an Unnamed Package is useful if you want to exclude certain design or testing items such as backend menus, or if you would like to include generic libraries of scripts or pieces that you have written. This sample unnamed package will exclude the backend Menu for the "Hello World" sample application.

• From the Joomla/Mambo Administrator backend, click on the menu Components->Facile Forms->Configuration. This will open up the Facile Forms Configuration screen.

• Near the bottom left corner, click on the Create Package button. This will open up the Facile Forms - Create Package screen.

• In the ID select list, do not choose a package. By leaving the ID blank, Facile Forms will present its unnamed Create Package screen, allowing you to pick and choose the items you will include in the Package.

• In the Package Name text box, enter [i]hello_world[/i]. This will be the "stub" file name for your xml package when it is created. As you refine your forms and applications, you may wish to include the version number in your package name. This is a developer preference. If you wish to use this convention, then you would enter hello_world_001 in the Package Name text box.

• In the Package Version text box, enter or leave it as 0.0.1. As you refine your packages, you will want to adjust the version number appropriately.

• In the Package Title text box, enter Hello World.

• In the Author Name text box, enter your name.

• In the Author Email text box, enter your email address.

• In the Author URL text box, enter your website address.

• In the Description text box, enter a description of your package.

• In the Copyright text box, enter your copyright information.

• In the Form Selection pick list, select Hello World::hello_world.

• Do not select anything in the Backend Menu Selection pick list. You will exclude the Hello World backend menu from this package.

• In the Script Selection pick list, select Hello World::say_hello.

• Do not select anything in the Piece Selection pick list.

The unnamed Create Package screen should look similar to this:

Click on the Continue button. This will start a download process in your browser to download your package file, "hello_world.xml". Depending upon the browser that you are using, its settings, and your operating system, you may receive different prompts concerning saving the file. Notably, in some versions of Internet Explorer, you may receive the yellow Information Bar across the top asking if you would like to download the file. If you choose to Download File, you will then be prompted with the Open or Save dialog box. You should choose Save.

Once the package has been created, Facile Forms will remember your version, contact, and copyright settings for this package.

Now you have an unnamed "hello_world.xml" package file without the backend menu that you can distribute to other Facile Form users.