2.0 Roadmap - silverorange/swat GitHub Wiki

Swat has evolved and stabilized quite a bit during it's 1.x lifetime. There are several improvements that should be made to Swat that are perhaps too large to be accommodated in the current Swat. Swat 2.0 should be an API branch from the current Swat API. It should not be a rewrite as much of Swat functions quite well. A Swat 2.0 release should include the following features. All features are open for discussion.

Resources

The handling of external CSS and JavaScript works fairly well in Swat. There are, however, several severe limitations. These include:

  1. Both style-sheets and scripts are included in the document head. Scripts should be included at the end of the document body.
  2. Swat resources are distributed across discrete files. There is no easy way to amalgamate resources into single files to reduce the number of HTTP requests.
  3. Swat resources are not minified and there is no architecture in place to provide minified versions.
  4. The web path of Swat resources is hard coded. Dynamic paths for resources would allow:
    1. filename-based versioning for better caching
    2. integration with other toolkits that use a different path structure for resources
  5. Resource dependencies are difficult to manage.
  6. Images should be stored in sub-directories per widget

Any change to Swat to make the handling of resources better should fix all the above problems.

Public Bug Tracking

A public bug and feature suggestion tracker is needed for Swat. The current goal is to migrate from MediaWiki to a trac installation. There is currently an internal trac installation at silverorange used to track bugs. The goal is for the public bug tracker to be managed in a similar way to how the YUI public bug tracking on Sourceforge is managed.

In this system, the public bug tracker is a place for users and developers to report bugs, suggest features and add comments to public entries. Someone from silverorange (aka Mike) would moderate these bugs and features requests and make sure they get reported on silverorange's internal system. Once the bug is marked as fixed in silverorange's system, the moderator would comment on the resolution on the public bug tracker and mark the public bug as closed.

Internationalization and Localization

Swat is currently using an emulated version of POSIX locale functions as found in the SwatI18N sub-package. This sub-package allows locale functions that both work properly, work flexibly and work on Windows.

If the PHP ICU extension makes PHP 5.3 inclusion it will be considered for Swat. The ICU extension handles things much better than POSIX. Gettext will still be used for translation. Zend Framework has a nice drop-in replacement for ICU but we do not want to depend on Zend Framework for Swat.

Namespaces and a Stable API

PHP 5.3+ will support namespaces. We would like Swat to take advantage of namespaces but since this is such a large API change it might be more appropriate for a Swat 2.0 release. Such a release would likely entail a major API review and ideally would result in a more guaranteed stable API. This could be completed before the end of 2008.

When revisiting the API, I would like to use accessors and mutators for all widget properties rather than making the properties public. I think this will result in a design that is less prone to bugs and far easier to refactor in the future.

Consistency Points

  • XHTML vs HTML vs Xhtml vs Html
  • XML vs Xml
  • set.By. vs set.From.
  • get.By. vs get.From.
  • CSS vs Css
  • YUI vs Yui
  • loadXml vs load

Parent Reference

One easy-to-fix API point is making the parent reference protected instead of public. Thanks to the magic of class-level scoping rules, all instances of SwatUIObject can modify the protected parent reference of any other UI-object it knows about. Inside Swat at least, this covers all the places the parent reference is used This will be a major clean-up of Swat's public API with little work required.

SwatTableView Orderable Column API

The order column API of SwatTableView is currently exposed as a read/write public property. This should be cleaned up.

Columns, Spanning Columns and Groups in SwatTableView

Currently, columns, spanning columns and groups are all handled differently. Groups are significantly different and should certainly be handled separately. Spanning columns are displayed differently but otherwise are identical to regular columns. It would be nice to simplify the API so it doesn't all have to be special-cased for spanning columns.

Getters and Setters

Using getters and setters for widget properties has several advantages. We can error check properties when they are set, we can provide a consistent stable API while still allowing the underlying implementation to change. '''We can drop the property type field in SwatML.'''

Show vs Display

Descriptive properties should use 'show' exclusively. Action-oriented methods should use 'display' in verb form.

Pass-Through SwatContainer Interface in SwatUI

Passing this interface through will make it easy to query the widget tree without having to call getRoot() all the time.

Pushing Up Stuff

Required and serializable should be expressed as interfaces, not as properties in the class tree.

More data types in SwatUI

Currently, SwatUI supports PHP native types, named constants and SwatDate objects in SwatML properties. There are other data types defined in Swat that would be useful to allow in SwatML including:

  • SwatOption,
  • SwatDataTreeNode (should be moved to SwatOptionTreeNode),
  • SwatTreeFlydownNode (should be moved to SwatOptionTreeNode),
  • SwatMessage and
  • SwatTableStore.

Additionally, it would be useful to be able to specify ui-object references in SwatML as well. This would be useful for the confirm password widget, for example.

Allowing such data-types should involve reworking how public properties are assigned to SwatUI objects and defining a flexible schema support for the new data-types. Ideally, a consistent interface for assigning properties will be defined and SwatUIObjects will implement the interface. Additionally, an interface would be defined for data types and all data types would implement the interface.

Integration

Swat exists as a standalone package installable using PEAR. The prime candidates for users of the Swat toolkit are users of existing website frameworks. Users of Swat have attempted integration with some success and some failures using [http://www.symfony-project.org Symfony], [http://www.cakephp.org CakePHP] and [http://framework.zend.com Zend Framework]. Swat 2.0 should make it easy to integrate Swat into each of these frameworks. Integration points should include:

  • packaging system that allows flexible directory structure and multiple PEAR package targets
  • flexible resource paths (as described above)
  • autoload support that doesn't stomp on other autoloaders
  • namespaces that don't collide with other projects
  • removal of non-toolkit parts of Swat into a separate package (SwatDB)
  • documentation and integration tutorials Integration with third party toolkits should be done with assistance from users of the framework. Alternate packages that integrate closely with a particular framework should be maintained by someone involved with that framework rather than by silverorange. Some Symfony developers have already expressed interest in helping out. Guidance from silverorange is needed for interested developers.

Widget State Interface

Currently, there is an interface in Swat that defines whether or not an object can get and set state. It is undefined what 'state' is for an object. We should have an interface or base class for an object that defines state and all the getState()/setState() methods should return and accept objects of the required type.

The idea behind 'state' is that the state of an entire ui-tree may be gotten and set on the entire tree at once. This can be used to serialize the state of a form. The current implementation works but is is very loose. Combined with the use of public properties across Swat objects it is easy to make a mistake and assign an impossible state to an object.

The ui-tree state system should be designed to make it easy to get and set the state and make it hard or impossible to set an impossible state on a widget (should throw an exception).

Refactor Exceptions

Swat currently defines its own base exception class that has many helpful methods. The problem is PHP SPL contains many useful exceptions that are peers to SwatException and do not have the helpful methods. Swat should do the following:

  1. Use SPL exceptions wherever possible
  2. Add the useful exception methods to a helper class (SwatExceptionHandler for example) that does not extend Exception itself
  3. remove SwatException
  4. make exception classes that are not covered by SPL extend Exception or extend a relevant SPL exception class

Coding Convention Updates

Our current coding conventions have been quite successful. Adopting some of the newer PEAR coding conventions for Swat 2.0 would be nice as they address some areas we don't have well defined standards. At a minimum we should adopt the following PEAR standards that differ from our own:

  • docblock formatting
  • multiline conditional statements
  • operator position of multiline statements
  • concatenation operator spacing
  • require braces on all control statements

As well as making parts of our code easier to read and develop, this will also keep us closer in line with developers who are already used to PEAR's standards.

If possible, we should use a tool like phpcs to detect any coding standards violations. Our coding conventions must also be made public.

Use Built-in Date Functions

We currently rely on PEAR::Date for all date-handling code. PEAR::Date is old, slow, buggy and written for PHP4. There are some fixes to address these concerns in CVS but no release has been made in years and many problems still remain. For example, the code is still written for PHP4 and does not use the built-in timezone functions added in PHP 5.1. This makes every page using dates in Swat needlessly slow and reliant on PHP4 code. Furthermore, the time zone database in PEAR::Date is out of date.

Update: PEAR::Date has had a new release. Aside from the time zone database still being maintained in a giant PHP file, most other concerns are addressed.

Tests

There is currently no formal testing for Swat. Releases are occasionally checked for functionality using the Swat demo. We should use PHPUnit to write unit tests for applicable code and Selenium for automated functional testing of the demo code.