Skip to content
This repository has been archived by the owner on Feb 26, 2022. It is now read-only.

Spring cleaning 2012

Jump to bottom
Gozala edited this page May 1, 2012 · 8 revisions

Spring is in the air & it's time to do some cleanup! There is bunch of stuff in SDK that was there for a long time from little to no advantage to the users. Some of this stuff has being replaced with a better alternatives and some is not really compliant with our long term goals. Here is a list of things that fall into that group:

1. demystify require

At the moment require('foo') may mean too many things, that's because sdk performs module search in various places in the filesystem and results may vary. In practice that adds a lot of complexity mixed with confusion for very small occasional benefit of saving few keystrokes. There for we will deprecate module search logic in favor if few simple rules:

  1. Relative path for in-package dependencies:
require('./utils/something')
require('../foo/bar')
  1. Single term for high level SDK dependencies:
require('panel')
require('tabs')
  1. Complete require form for external package dependencies:
require('api-utils/functional')
require('io/fs')
require('package-name/module/path')

We would encourage you to use only these forms that work today and are compatible with our future plans and other projects like nodejs.

2. exports.main

This feature is currently documented under Listening for Load and Unload tutorial of the SDK. This feature allows authors to write an entry point main function that is called on add-on startup, with several arguments that can be used to do different things:

// called at startup
exports.main = function (options, callbacks) {
  options.loadReason  // describing the reason your add-on was loaded
  options.staticArgs  // data passed as `cfx --static-args`

  callbacks.print     // prints to output
  callbacks.quit      // quits application
};

// called at shutdown
exports.onUnload(reason) {
  reason              // describing the reason your add-on was unloaded
};

Now most of this can be replaced with already provided functionality:

  • options.loadReason: require('self').loadReason.
  • options.staticArgs: This is no way an API for add-on's as users are not going to run cfx run, on the other hand it adds complexity for no benefit. In addition this can be accessed via require('api-utils/system').staticArgs. Most likely we'll deprecate that some time in a future as well.
  • callbacks.print: This is redundant function as you already have console.log
  • callbacks.quit: This is again not really useful for add-ons, specially in this form. Also, there is more preferable alternative require('api-utils/system').exit().
  • exports.onUnload: There is require('api-utils/unload').when(f) for that, which is more preferable.

Removing this rarely useful features would allow us to start add-ons faster, and include only bit's it needs. That way only add-ons that depend on such features will have to pay price associated with it.

3. data & self

At the moment self module behavior in relation to data folder is somewhat magical. What this means is that if you happen to have another foo package in your packages folder that your add-on bar depended upon, modules form bar will get different result when calling require('self') from modules of foo. Not only module will be different but also a data folder it is associated with. In a near future we plan to build a much better system for module sharing that won't require any packages making this feature obsolete. At the moment there is 0 from 41 libraries on add-on bulider that has dependency on self, indicating that breaking change won't affect existing add-ons. Also in a future we plan to provide better alternative to verbose require('self').data.url('./index.html') in favor of simple './data/index.html'.

4. traits, cortex

Traits and lighter were providing an API for building class like constructs in sdk, and cortexs were used to secure them, so that they can be shared with untrusted code. First one will be replaced with a newer simpler API for doing that will be used internally to implement APIs and by users so they could subclass Panel, Widget, etc.. Also cortexs become redurant since namespaces allow string private data without risks of exposure.

5. Unified APIs

Some older low level APIs were written a long before we have being written some of high level APIs that share same unified API for event dispatching etc.. APIs like observer-service will be deprecated at some point in favor of better alternatives implementing same event emitting APIs as rest of the code. Also we will make sure to keep both APIs at least for one cycle so you have a time to migrate.

Clone this wiki locally