Free Trial

Safari Books Online is a digital library providing on-demand subscription access to thousands of learning resources.

  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint
Share this Page URL
Help

PHP 5 CMS Framework Development > A. Packaging Extensions

A. Packaging Extensions

Appendix A. Packaging Extensions This information is provided for those who want to build an installer following similar design principles to those described in this book, or for people who intend to use Aliro itself. Aliro comes with an easy-to-use universal installer for extensions. Technically, these may be modules, plugins, components, templates, or others. "Others" are specialized installation units, including patches. Aliro will handle packages that contain multiple extension objects, each of which has its own XML setup file. Whatever the type of the extension to be installed, the process is identical. Using the universal installer, the site administrator can add a feature or a template (or a package containing multiple items) by uploading a single archived file. This appendix describes how to create the setup files that are used by the installer. The XML setup file All installations using the installer require a text file written in XML. The XML file contains information about the extension, which is retained for display in the administration part of the site. It also contains directives that tell the installer how to handle the installation. Only a passing familiarity with XML is required since the structure is quite simple. Each XML file begins with the prologue, <?xml version="1.0" encoding="utf-8" ?>. It is also a good idea to include a DOCTYPE as the second line of the XML file. It could be: <!DOCTYPE extinstall SYSTEM " http://aliro.org/xml/extinstall.dtd"> This DOCTYPE statement refers to a DTD file at the Aliro website. Including a DOCTYPE means that the XML file can be checked using a choice of online XML validators. If the validator says that the XML is correct, then it should work with Aliro. If there is a problem with the XML, Aliro will issue detailed diagnostics. With every XML file submitted as part of an installation, Aliro will look for the outermost tag, and if it is recognized, the DOCTYPE will be replaced (or inserted, if not present) with a reference to one of the local DTD files included with the Aliro installation. This avoids any delays during validation through having to access a remote website. Note that the installation process does strict validation of the XML and will not complete an installation where the XML does not conform to the DTD. Strict XML checking includes a requirement that elements and attributes appear in the order of the specification. After the initial XML line and the DOCTYPE (if present), several nested sections appear, all of which are within the root element, <extinstall>. For backwards compatibility, Aliro will also accept <mosinstall> which derives from Mambo Open Source, which is a precursor to Aliro. Either tag can be used, but newer features will only be accepted within <extinstall>. The <mosinstall> tag is supported to make it easier to utilize software written for other systems, such as Mambo, MiaCMS, or Joomla! In fact, Aliro will also handle a file whose outermost tag is <install> and will assume that it is an XML file for the Joomla! 1.5 system. In this case, the tag is transformed to <josinstall> before being processed, because the Joomla! 1.5 XML is not legal on account of <install> being used both as the outermost element and also as an inner element. Again, this is to ease migration of software from one CMS platform to another. There is a corresponding DTD file called josinstall.dtd. Installation of software meant for other CMS may very well not immediately work, but attempting it can provide a helpful start to migration. The <extinstall> element supports the following attributes: type: This is a mandatory attribute and must be one of application, component, module, plugin, mambot, template, language, patch, include, parameters, or menu (plugin and mambot mean the same). Note that application is a new type brought about by development since the first edition. An application can incorporate plugins and modules, and can also have "urilinks". For details, see below.version: The lowest version of Aliro for which the extension can be validly installed—it is currently ignored.client: This is an optional attribute, and if present must be either administrator or user. This should be specified for extensions that exist specifically on either the administrator or user side of the system, such as a module. If omitted, user is assumed.userclass: This is an optional attribute, but see adminclass. This is the name of the class to be instantiated when the extension is invoked on the user side.adminclass: This is an optional attribute, and is the name of the class to be instantiated when the extension is invoked on the administration side. If neither userclass nor adminclass is specified, the extension is assumed to be written in the style required by Joomla 1.x or Mambo 4.x.menuclass: This is an optional attribute for components and is the class to be invoked when a new menu entry is being created for the component. It allows for the creation of a variety of different kinds of menu entries to carry out different functions in the component.triggers: This is a mandatory attribute for plugins and is a comma separated list of the event names for which the plugin is to be activated.published: This is an optional attribute for plugins and modules, and may be set to yes, in which case the extension will be immediately published without any action by the administrator.inner: This is an optional attribute for templates, and may be set to yes, in which case it indicates a template that is used for an area within the browser window, unlike a standard template that defines the entire window. XML elements that are common to all types of installation are listed as follows: <name> The name element is an informal name for the extension and will be seen by the administrator. <formalname> The formalname element is mandatory and must be unique in the installed system. By convention components will have a name of 'com_xxxxx', modules will be 'mod_xxxx', plugins will be 'bot_xxxx', user side templates will be 'ut_xxxx', and admin side templates will be 'at_xxxx' where 'xxxx' is the chosen name. Care should be taken over the selection of formalname. Note that this is an addition relative to Aliro's precursors, although for backwards compatibility Aliro will, with components only, attempt to derive a value for the formalname from the ordinary name. The addition of formalname is intended to make the labeling of extensions more transparent. <version> This is the version of the installed package. <description> This is a brief description of the component, module, template, or plugin. Note that if this contains any XHTML it must be enclosed as CDATA. This is done by first writing the string <![CDATA[ followed by the XHTML and terminated by the string ]]>. <creationdate> This is the creation date for this package. There is no specifically defined format for this date; it is just a string. Simple numeric forms are ambiguous internationally and should be avoided. <author> This is the name of the author of the extension. <authorurl> This is the author's URL. <authoremail> This is the e-mail address of the author. <copyright> This is the copyright information affecting the extension. <license> This is the license under which the extension is being released. <warning> This is included for compatibility but has no function at present. <credits> This is included for compatibility but has no function at present. <group> This is included for compatibility, but has no function at present. <module> An application is allowed to define integrated modules. Attributes should be applied to tell the framework about the module. They can be userclass, adminclass, client, and published, and have the same meanings as when used as attributes of <extinstall>. Where a class is given, it can simply be the name of a class, or it can be the class name followed by a comma and a method name. If no method is supplied, the default activate will be used. This element can contain <name>, <formalname>, <description>, and <params> elements, which are all described here. <plugin> An application is also allowed to define integrated plugins. Attributes can be userclass, triggers, and published. There is no distinction between user and administrator plugins, otherwise the userclass functions as for integrated modules. The triggers attribute works just as it does when applied to <extinstall> (described earlier). Contained elements are the same as for an integrated module. <urilink> An application can also specify <urilink> elements to give a direct connection between the received URI and the application. These elements can have attributes class, published, template, and html. Contained elements are <name>, <description> and <uri>. The first two of these function as elsewhere, and <uri> contains a regular expression that will be matched against the URI, after the domain has been removed. Briefly, if the URI matches the given regular expression, the specified class will be activated. The <published> element operates as for modules or plugins. It is possible to indicate with the template attribute (which can be yes or no and defaults to yes) whether the response should include a whole page via template processing, or only the output of the class invoked by the link. It is also possible to define through the html attribute (also defaults to yes) whether the output should be wrapped with the usual <html> page structure, or output with no addition at all. The latter is suitable where, for instance, the link is being used to dynamically deliver something like an image. <files> This is optional, and this section is used to tell the installer which files it should install. The <files> element can contain an arbitrary number of <filename> sections. Each of the major extension types has its own distinct directory within an Aliro installation (some have one directory for user side and one for administration side). An extension will be given its own directory named with the <formalname> value, one reason why there is a requirement for uniqueness. To fully utilize Aliro, only files that do not fall into any of the following categories should be included here. <classfiles> This is similar to <files> except that the individual <filename> entries within <classfiles> are expected to refer to files that contain PHP code, probably including classes. Files that are listed here will be parsed and information about contained classes will be used for automatic loading. <images> This is similar to <files> except images that are used in by the extension as essential to its normal functioning (for example, needed as part of the browser screen display) should be included in this section for clarity. <css> This is similar to <files> except that CSS files should be included here for clarity. <media> This is similar to <files> except that the files included here should be material, such as images that are treated as data by the extension. <langfiles> This is similar to <files> except that the individual <filename> entries within <langfiles> are expected to refer to a gettext PO file and the file name should be a language in the standard form of, for example, 'es' or 'fr-CA' which defines the language and possibly the region for which the file gives translations, followed by the .po extension. For components, the language files are stored by the installer in the user side component directory, using any subdirectory information implied by the <filename> entry. <filename> Any of the file holding elements (that is files, classfiles, images, css, media, or langfiles) must contain one or more <filename> elements. The filename is given within this entry and can be preceded by one or more directory levels, each one separated from others and from the filename by a forward slash. Wherever this feature is used (and its use is recommended) the file must be in the specified subdirectory in the install package and should be placed in the corresponding subdirectory in the Aliro installation. The <filename> element has an important attribute when it occurs within a <classfiles> section: classes: This was a comma separated list giving the names of classes that are included within the file. Its use is now deprecated, and the information provided is ignored by Aliro, since the files are parsed to obtain information about classes. Wherever a <filename> element appears in the XML of a language package, it will have a number of other attributes such as domain, strings, translated, fuzzy, percent, and filetype but these are not described here because the XML files for language are always created automatically by Aliro. <install> This element brackets a <queries> element, which in turn contains an arbitrary number of <query> elements. When the extension is installed, each SQL query within a <query> element inside the <install> element will be executed. <uninstall> This operates in exactly the same way as <install> except that it applies to the removal of the extension. Note that unlike its predecessors, Aliro's installer caters for upgrades, so it is reasonable to include in the <uninstall> element SQL to completely remove the data for the extension. <installfile> Applies only to a component or application, and specifies a file in the same way as the <filename> element. On an installation, the file will be moved to the administrator component directory and executed. <uninstallfile> Applies only to a component or application, and specifies a file in the same way as the <filename> element. On an installation, the file will be moved to the administrator component directory, and it will be executed when the component or application is uninstalled. Any SQL specified within an <uninstall> element will also be run after the uninstall file has been run. <upgradefile> Applies only to a component or application, and specifies a file in the same way as the <filename> element. On an installation or upgrade, the file will be moved to the administrator component directory, and on an upgrade it will be executed. Note that the XML does not include provisions for SQL queries on upgrade as it is assumed that more logic is required to determine exactly what SQL actions are appropriate according to the circumstances. The logic can more effectively be placed in the PHP of the upgrade file. <administration> The <administration> element is used only for components and applications and may include a <files> element to specify files that will be placed in the administration side components directory. It may also include an <images> element on the same basis. In addition, it can contain one or more <menu> elements. The <menu> element is described in more detail below. It can also contain a <submenu> element. <menu> The menu element can appear within the <administration> element, or within a <submenu> element (see below). It specifies the text that is to go into the administrator's menu of applications. The link for the menu entry is determined by the attributes, which can be act, task, or link. <submenu> An extension into a submenu can be achieved by including a <submenu> element in the <administration> element. It contains one or more <menu> elements that will be used to form a submenu. <params> This defines parameters used by the extension, and is described in more detail in the next section. <locale> This is used only in the XML for language packages, and always has the attributes name, title, territory, locale, text_direction, iso639, iso3166_2, iso3166_3, and charset. It is always automatically generated by the language processing in Aliro, so further details are not given here. Parameters Extension setup files may also have a group of elements defining parameters, for example: <params> <param name="menu_image" type="imagelist" directory="/images/stories" hide_default="1" default="" label="Menu Image" description="A small image to be placed to the left or right of your menu item, images must be in images/stories/" /> <param name="pageclass_sfx" type="text" size="20" default="" label="Page Class Suffix" description="A suffix to be applied to the css classes of the page, this allows individual page styling" /> <param name="back_button" type="list" default="" label="Back Button" description="Show/Hide a Back Button, that returns you to the previously view page"> <option value="">Use Global</option> <option value="0">Hide</option> <option value="1">Show</option> </param> <param name="header" type="text" size="30" default="" label="Page Title" description="Text to display at the top of the page" /> <param name="page_title" type="radio" default="1" label="Page Title" description="Show/Hide the Page title"> <option value="0">Hide</option> <option value="1">Show</option> </param> </params> This is a generalized XML-driven system that allows for easy creation of sets of parameters. A set of parameters is implemented as an associative array and is normally stored in the database by being serialized. The XML provides enough information for the creation of a screen block that invites the entry of values for all the parameters identified in the XML. The XML can include defaults and the entry can be through an input field, or can be a choice of specified options. There are only three tag types here, but a number of attributes are available for the <param> tag. The tags are: <params> The main tag to define a set of parameters. <param> The tag for an individual parameter can have the following attributes: name: This will be used as the key to hold parameter information as an associative array.type: This indicates the type of parameter and can have any of these values, text, list, radio, imagelist, textarea, editarea, dynamic, or spacer. There are others retained for backwards compatibility, but they are deprecated in favor of using dynamic. The types are explained in detail in the next section.directory: This is used in association with the imagelist type to define a directory from which all images will be offered as a list from which a selection can be made.default: This is the default value to be assigned if no choice is made.label: This is the text that will be used to label the field when values are being invited for this parameter.description: This will be linked to the entry of this parameter as a tooltip or some other device that gives extra information to the person entering parameter data.class: This refers to the name of a singleton class and is only used in connection with the dynamic type of parameter.method: This is again only used with the dynamic type of parameter, and refers to the method to be used after the static method getInstance has been used against the specified class to obtain an object.other: It is possible for the "dynamic" type of parameter to implement other attributes specific to the context. <option> Wherever the type of the <param> is list or radio then two or more <option> tags need to be included within the <param> tag. Each option has a value that is the text to be shown against the choice and each option has an attribute value which determines the actual value to be stored in the associative array if this option is chosen. Parameter types text: This allows the entry of a string of text on one line. list: This provides a menu of items (defined by <option> tags) from which one choice can be made. radio: This provides a set of choices (defined by <option> tags) shown as radio buttons. imagelist: This gives a list of images from which any one can be selected. It must be associated with a directory attribute that defines a directory (relative to the document root) that contains a set of images. textarea: This is similar to text but creates an input area rather than a single line. editarea: This is similar to textarea but invokes the system WYSIWYG editor rather than only allowing plain text (if no editor is installed, Aliro will provide a null editor and this parameter type will drop-down to being a textarea). dynamic: This supports arbitrary extensions to the parameter system for use by extensions. It must be associated with class and method attributes. The class is taken as a class name that is assumed to be a singleton and to implement the getInstance static class method. Once getInstance has been used against the class name to obtain an object, the method specified is called with the following parameters: name: The name of the parameter, which is also the key to be used in the associate array that implements the set of parameters.value: The current value of the parameter.controlname: The overall name to be used for values entered into the parameter block, with controlname subscripted by name.param: The PHP SimpleXML element corresponds to this parameter so that the method can extract further attributes if desired. spacer: This produces a horizontal rule or similar division between parameters, but does not define a parameter as such. This list is extensible, as any class introduced into the system with a name of the form aliroParameterRender**** will add the type **** to the system, provided the class is subclassed from aliroParameterRender and is made known to the framework by being included within a <classfiles> element.

  

You are currently reading a PREVIEW of this book.

                                                                                                                    

Get instant access to over $1 million worth of books and videos.

  

Start a Free Trial


  
  • Safari Books Online
  • Create BookmarkCreate Bookmark
  • Create Note or TagCreate Note or Tag
  • PrintPrint