Skip to content

imaman/jquery.uri

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

32 Commits
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

   jquery.uri(uriString) - A JQuery plugin for inspecting and manipulating a URI or a URL.
   
   Typical usage example:
      var uri = $.uri(window.location.href); 
      // Assuming current url is "http://api.jquery.com"
      
      var newUri = uri.at({path: "main/index.html", query: { format: "xml" }};
      window.location.replace(newUri); 
         // Will forward the browser to "http://api.jquery.com/main/index.html?format=xml"

   Parameters: uriString - Input string
   Returns: An immutable object, providing the following methods:
     
   - at: function(part) 
      Return the value of the specified URI part. part can be any one 
      of the following strings: "protocol", "domain", "port", "path", "query", 
      "fragment". Any other value yields an exception. 
       
      The "query" part returns an object that maps parameter names to their values,
      as specified by at the query part of the URI. All names and values are 
      decoded via decodeURIComponent(). A "defensive getter" semantics is used so 
      the returned object can be subsequently mutated by the caller without 
      affecting this.             

   Example:       
      var uri = $.uri('http://jquery.com:8080/main/index.html?format=json#top');
      assert uri.at('protocol') == 'http'
      assert uri.at('domain') == 'jquery.com'
      assert uri.at('port') == '8080'
      assert uri.at('path') == 'main/index.html'
      assert uri.at('query') == { 'format': 'json' }
      assert uri.at('fragment') == 'top'
          
   - at: function(part, value)
      Set the value of a URI part.
      Returns a new instance similar to this one except that the specified URI 
      part is now set to value. The receiving object is unchanged. part can 
      be any one of the following strings: "protocol", "domain", "port", "path", 
      "query", "fragment". Any other value yields an exception. 
        
      Example:       
         var uri = $.uri('http://api.jquery.com:8080/main/index.html?format=json');
         uri = uri.at('port', '2020').at('path', 'welcome.html');
         assert uri.at('port') == '2020'
         assert uri.at('path') == 'welcome.html'
       
      if part == "query" then value should be an object. Properties of this object
      provide new name,value mapping for the "query" part at the returned object.
      A new mapping will override an existing mapping (with the same name). Existing
      mapping that were not overridden will be available in the new instance. A 
      "defensive setter" semantics is used so value can be subsequently mutated 
      by the caller without affecting this. 

      Example:       
         var uri = $.uri('http://api.jquery.com?a=1&b=2');
         uri = uri.at('query', { b:200, c:300 });
         assert uri.at('query').a == 1;
         assert uri.at('query').b == 200;
         assert uri.at('query').c == 300;

   - at: function(object)
      Set the values of several URI parts and/or query parameters.      
      Returns a new instance similar to this one except that all name,value 
      mappings specified by the parameter are applied the new instance 
      in a manner similar to at(name,value).  The receiving object is unchanged.
      
      A "defensive setter" semantics is used so object can be subsequently mutated 
      by the caller without affecting this.       
       
      Example:       
          var uri = $.uri('http://api.jquery.com:8080/main/index.html?format=json');
          uri = uri.at({ port: '2020', path: 'welcome.html' });
          assert uri.at('port') == '2020'
          assert uri.at('path') == 'welcome.html'
       
      If object.query is defined, then the query part of the result is the same
      as if .at("query", object.query) were called.

      Example:       
         var uri = $.uri('http://api.jquery.com?a=1&b=2');
         uri = uri.at({ query: { b:200, c:300 }});
         assert uri.at('query').a == 1;
         assert uri.at('query').b == 200;
         assert uri.at('query').c == 300;

   - toString([compareFunction])
      Return a well-formed URL representing this object.
      Unspecified components (e.g., if .at('port') == '') do not appear at the result.
      Names and value of parameters at the query part are encoded via encodeURIComponent().
      
      Caller can pass an optional compareFunction to affect the order of parameters 
      at the query part of the result. If compareFunction is not specified, order is 
      undefined.
      
      parameter: compareFunction 
         A function taking two arguments, a and b, each of which is an object  
         with two properties - name, value - representing a query parameter. 

         Returns 
            -1 if a should appear before b, 
            +1 if a should appear after b, 
            0 otherwise.
            
   - retain(name1, name2, ...) 
      Keep the specified query parmas, discard all others.
      Return a new instance similar to this one except that its query 
      part contains only the params whose names are specified by name1, name2, 
      etc. All other params are discarded from the result. The receiving object 
      is unchanged.
            
      Example:       
          var uri = $.uri('http://api.jquery.com?a=1&b=2&c=3&d=4');
          assert uri.retain('b', 'c').at('query') == { b:2, c: 3 }
          
   - defaults(anObject) 
      Provide defaults for query parameters.
      Properties of anObject provide new name,value mappings for the query part
      of the returned object. A mapping will be ignored if an existing parameter 
      (with the same name) is already defined. 
      The receiving object is unchanged.

      Example:       
         var uri = $.uri('http://api.jquery.com?a=1&b=2');
         uri = uri.at({ query: { b:200, c:300 }});
         assert uri.at('query').a == 1;
         assert uri.at('query').b == 2;
         assert uri.at('query').c == 300;

About

A JQuery plugin for inspecting/manipulating URIs/URLs

Resources

Stars

Watchers

Forks

Releases

No releases published

Packages

No packages published