Skip to content

Commit

Permalink
Update README.md
Browse files Browse the repository at this point in the history
  • Loading branch information
chrisisbeef committed Aug 19, 2015
1 parent f162d51 commit f91472a
Showing 1 changed file with 21 additions and 7 deletions.
28 changes: 21 additions & 7 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -40,7 +40,7 @@ Using the plugin is very simple, there are both static and instance methods to p

`canonicalize( String data, bool strict=true )`

Canonicalization (also called normalization) is the act of reducing a string to it's simplest form. For example, if the string @%3CB%3E@ is passed into the canonicalize method, the value returned will be decoded into @<b>@. The most important part of this method is that it will detect if a string is passed in that contains either multiple encoding types, or double encoding, or both. The default behavior of the method is to raise an exception if it detects one of these scenarios. As a general rule, normal application operation should never pass data that is either double encoded or encoded using multiple escaping rules. Most definately, data that is provided by a user (such as a form field) will never contain data that fits that description.
Canonicalization (also called normalization) is the act of reducing a string to it's simplest form. For example, if the string `%3CB%3E` is passed into the canonicalize method, the value returned will be decoded into `<b>`. The most important part of this method is that it will detect if a string is passed in that contains either multiple encoding types, or double encoding, or both. The default behavior of the method is to raise an exception if it detects one of these scenarios. As a general rule, normal application operation should never pass data that is either double encoded or encoded using multiple escaping rules. Most definately, data that is provided by a user (such as a form field) will never contain data that fits that description.

```
try {
Expand All @@ -53,7 +53,7 @@ Canonicalization (also called normalization) is the act of reducing a string to

`@encodeForCSS( String input, char[] immune )`

This method allows developers to encode data specifically to be inserted into the @style@ attribute of an element or as the value of a style attribute passed in through the jQuery @.style()@ method.
This method allows developers to encode data specifically to be inserted into the @style@ attribute of an element or as the value of a style attribute passed in through the jQuery `.style()` method.

```
$.post('/service/userprefs', { user: userID }, function(data) {
Expand All @@ -63,7 +63,7 @@ This method allows developers to encode data specifically to be inserted into th

`@encodeForHTML( String input )`

This method allows developers to encode data specifically to be inserted between two tags in a document, either through the use of the @html()@ method or by accessing @innerHTML@ directly.
This method allows developers to encode data specifically to be inserted between two tags in a document, either through the use of the `html()` method or by accessing @innerHTML@ directly.

```
$.post('http://untrusted.com/news/', function(data) {
Expand Down Expand Up @@ -101,14 +101,28 @@ This method allows developers to encode data specifically to be inserted into a

### Instance Methods

New in version 0.1.1 is the ability to call encoding directly on an element for the `.attr()`, `.html()`, and `.style()` methods.

`encode( Enum(html|css|attr) context, String input )`

_( coming soon )_
Sets a property of the element with the correct contextual, property-aware encoding applied.

`encode( Object opts )`
```
// Sets the 'value' attribute of the element with id #my-element
$('#my-element').encode('attr', 'value', untrustedData)
_( coming soon )_
// Add a 'background-image' to the element with id #my-element
$('#my-element').encode('css', 'background-image', untrustedUrl);
```

## Release History

_( coming soon )_
### v0.1.1 - 2015.08.19

* Updated for jQuery 1.9+ compatibility
* New instance method .encode
* Added full support for "Property-Aware Contextual OE"
* Migrated to be a grunt build instead of a hacky maven build
* Fixed Issue #8 - Support Astral Symbols in encodeForHTMLAttribute (Thanks @stuartf and @mathiasbynens)

### v0.1.0 - Initial Release

0 comments on commit f91472a

Please sign in to comment.