dojox/storage/Provider.js

• Provides:

  • dojox.storage.Provider

• dojox.storage.Provider

  • type

    Function

  • summary

    A singleton for working with dojox.storage.

  • description

    dojox.storage exposes the current available storage provider on this
    platform. It gives you methods such as dojox.storage.put(),
    dojox.storage.get(), etc.
    
    For more details on dojox.storage, see the primary documentation
    page at
    http://manual.dojotoolkit.org/storage.html
    
    Note for storage provider developers who are creating subclasses-
    This is the base class for all storage providers Specific kinds of
    Storage Providers should subclass this and implement these methods.
    You should avoid initialization in storage provider subclass's
    constructor; instead, perform initialization in your initialize()
    method.

• dojox.storage.Provider.constructor

  • constructor - constructor
  • type

    Function

• dojox.storage.Provider.SUCCESS

  • type

    String

  • summary

    Flag that indicates a put() call to a
    storage provider was succesful.

• dojox.storage.Provider.FAILED

  • type

    String

  • summary

    Flag that indicates a put() call to
    a storage provider failed.

• dojox.storage.Provider.PENDING

  • type

    String

  • summary

    Flag that indicates a put() call to a
    storage provider is pending user approval.

• dojox.storage.Provider.SIZE_NOT_AVAILABLE

  • type

    String

  • summary

    Returned by getMaximumSize() if this storage provider can not determine
    the maximum amount of data it can support.

• dojox.storage.Provider.SIZE_NO_LIMIT

  • type

    String

  • summary

    Returned by getMaximumSize() if this storage provider has no theoretical
    limit on the amount of data it can store.

• dojox.storage.Provider.DEFAULT_NAMESPACE

  • type

    String

  • summary

    The namespace for all storage operations. This is useful if several
    applications want access to the storage system from the same domain but
    want different storage silos.

• dojox.storage.Provider.onHideSettingsUI

  • type

    Function

  • summary

    If a function is assigned to this property, then when the settings
    provider's UI is closed this function is called. Useful, for example,
    if the user has just cleared out all storage for this provider using
    the settings UI, and you want to update your UI.

• dojox.storage.Provider.initialize

  • summary

    Allows this storage provider to initialize itself. This is
    called after the page has finished loading, so you can not do
    document.writes(). Storage Provider subclasses should initialize
    themselves inside of here rather than in their function
    constructor.

  • type

    Function

• dojox.storage.Provider.isAvailable

  • summary

    Returns whether this storage provider is available on this
    platform.

  • type

    Function

• dojox.storage.Provider.put

  • parameters:
    • key: (typeof string)

      A string key to use when retrieving this value in the future.

    • value: (typeof object)

      A value to store; this can be any JavaScript type.

    • resultsHandler: (typeof function)

      A callback function that will receive three arguments. The
      first argument is one of three values: dojox.storage.SUCCESS,
      dojox.storage.FAILED, or dojox.storage.PENDING; these values
      determine how the put request went. In some storage systems
      users can deny a storage request, resulting in a
      dojox.storage.FAILED, while in other storage systems a storage
      request must wait for user approval, resulting in a
      dojox.storage.PENDING status until the request is either
      approved or denied, resulting in another call back with
      dojox.storage.SUCCESS.
      The second argument in the call back is the key name that was being stored.
      The third argument in the call back is an optional message that
      details possible error messages that might have occurred during
      the storage process.

    • namespace: (typeof string)

      Optional string namespace that this value will be placed into;
      if left off, the value will be placed into dojox.storage.DEFAULT_NAMESPACE

  • summary

    Puts a key and value into this storage system.

  • description

    Example-
    var resultsHandler = function(status, key, message, namespace){
    alert("status="+status+", key="+key+", message="+message);
    };
    dojox.storage.put("test", "hello world", resultsHandler);
    
    Arguments:
    
    status - The status of the put operation, given by
    dojox.storage.FAILED, dojox.storage.SUCCEEDED, or
    dojox.storage.PENDING
    key - The key that was used for the put
    message - An optional message if there was an error or things failed.
    namespace - The namespace of the key. This comes at the end since
    it was added later.
    
    Important note: if you are using Dojo Storage in conjunction with
    Dojo Offline, then you don't need to provide
    a resultsHandler; this is because for Dojo Offline we
    use Google Gears to persist data, which has unlimited data
    once the user has given permission. If you are using Dojo
    Storage apart from Dojo Offline, then under the covers hidden
    Flash might be used, which is both asychronous and which might
    get denied; in this case you must provide a resultsHandler.

  • type

    Function

• dojox.storage.Provider.get

  • parameters:
    • key: (typeof string)

      A string key to get the value of.

    • namespace: (typeof string)

      Optional string namespace that this value will be retrieved from;
      if left off, the value will be retrieved from dojox.storage.DEFAULT_NAMESPACE
      return: Returns any JavaScript object type; null if the key is not present

  • summary

    Gets the value with the given key. Returns null if this key is
    not in the storage system.

  • type

    Function

• dojox.storage.Provider.hasKey

  • parameters:
    • key: (typeof string)
    • namespace: (typeof string)
  • returns

    Boolean

  • summary

    Determines whether the storage has the given key.

  • type

    Function

• dojox.storage.Provider.getKeys

  • parameters:
    • namespace: (typeof string)
  • summary

    Enumerates all of the available keys in this storage system.
    return: Array of available keys

  • type

    Function

• dojox.storage.Provider.clear

  • parameters:
    • namespace: (typeof string)
  • summary

    Completely clears this storage system of all of it's values and
    keys. If 'namespace' is provided just clears the keys in that
    namespace.

  • type

    Function

• dojox.storage.Provider.remove

  • parameters:
    • key: (typeof string)
    • namespace: (typeof string)
  • summary

    Removes the given key from this storage system.

  • type

    Function

• dojox.storage.Provider.getNamespaces

  • type

    Function

• dojox.storage.Provider.isPermanent

  • summary

    Returns whether this storage provider's values are persisted
    when this platform is shutdown.

  • type

    Function

• dojox.storage.Provider.getMaximumSize

  • summary

    The maximum storage allowed by this provider

  • return_summary

    Returns the maximum storage size
    supported by this provider, in
    thousands of bytes (i.e., if it
    returns 60 then this means that 60K
    of storage is supported).
    
    If this provider can not determine
    it's maximum size, then
    dojox.storage.SIZE_NOT_AVAILABLE is
    returned; if there is no theoretical
    limit on the amount of storage
    this provider can return, then
    dojox.storage.SIZE_NO_LIMIT is
    returned

  • type

    Function

• dojox.storage.Provider.putMultiple

  • parameters:
    • keys: (typeof array)

      An array of string keys to use when retrieving this value in the future,
      one per value to be stored

    • values: (typeof array)

      An array of values to store; this can be any JavaScript type, though the
      performance of plain strings is considerably better

    • resultsHandler: (typeof function)

      A callback function that will receive three arguments. The
      first argument is one of three values: dojox.storage.SUCCESS,
      dojox.storage.FAILED, or dojox.storage.PENDING; these values
      determine how the put request went. In some storage systems
      users can deny a storage request, resulting in a
      dojox.storage.FAILED, while in other storage systems a storage
      request must wait for user approval, resulting in a
      dojox.storage.PENDING status until the request is either
      approved or denied, resulting in another call back with
      dojox.storage.SUCCESS.
      The second argument in the call back is the key name that was being stored.
      The third argument in the call back is an optional message that
      details possible error messages that might have occurred during
      the storage process.

    • namespace: (typeof string)

      Optional string namespace that this value will be placed into;
      if left off, the value will be placed into dojox.storage.DEFAULT_NAMESPACE

  • summary

    Puts multiple keys and values into this storage system.

  • description

    Example-
    var resultsHandler = function(status, key, message){
    alert("status="+status+", key="+key+", message="+message);
    };
    dojox.storage.put(["test"], ["hello world"], resultsHandler);
    
    Important note: if you are using Dojo Storage in conjunction with
    Dojo Offline, then you don't need to provide
    a resultsHandler; this is because for Dojo Offline we
    use Google Gears to persist data, which has unlimited data
    once the user has given permission. If you are using Dojo
    Storage apart from Dojo Offline, then under the covers hidden
    Flash might be used, which is both asychronous and which might
    get denied; in this case you must provide a resultsHandler.

  • type

    Function

• dojox.storage.Provider.getMultiple

  • parameters:
    • keys: (typeof array)

      An array of string keys to get the value of.

    • namespace: (typeof string)

      Optional string namespace that this value will be retrieved from;
      if left off, the value will be retrieved from dojox.storage.DEFAULT_NAMESPACE
      return: Returns any JavaScript object type; null if the key is not present

  • summary

    Gets the valuse corresponding to each of the given keys.
    Returns a null array element for each given key that is
    not in the storage system.

  • type

    Function

• dojox.storage.Provider.removeMultiple

  • parameters:
    • keys: (typeof array)
    • namespace: (typeof string)
  • summary

    Removes the given keys from this storage system.

  • type

    Function

• dojox.storage.Provider.isValidKeyArray

  • parameters:
    • keys
  • type

    Function

• dojox.storage.Provider.hasSettingsUI

  • summary

    Determines whether this provider has a settings UI.

  • type

    Function

• dojox.storage.Provider.showSettingsUI

  • summary

    If this provider has a settings UI, determined
    by calling hasSettingsUI(), it is shown.

  • type

    Function

• dojox.storage.Provider.hideSettingsUI

  • summary

    If this provider has a settings UI, hides it.

  • type

    Function

• dojox.storage.Provider.isValidKey

  • parameters:
    • keyName: (typeof string)
  • summary

    Subclasses can call this to ensure that the key given is valid
    in a consistent way across different storage providers. We use
    the lowest common denominator for key values allowed: only
    letters, numbers, and underscores are allowed. No spaces.

  • type

    Function

• dojox.storage.Provider.getResourceList

  • summary

    Returns a list of URLs that this
    storage provider might depend on.

  • description

    This method returns a list of URLs that this
    storage provider depends on to do its work.
    This list is used by the Dojo Offline Toolkit
    to cache these resources to ensure the machinery
    used by this storage provider is available offline.
    What is returned is an array of URLs.
    Note that Dojo Offline uses Gears as its native
    storage provider, and does not support using other
    kinds of storage providers while offline anymore.

  • type

    Function

• dojox.storage

  • type

    Object

• dojox

  • type

    Object