From 734d7506b2642788dce87b5d0811afd65c89d717 Mon Sep 17 00:00:00 2001 From: Mikhail Kormanowsky Date: Wed, 13 Dec 2017 14:46:18 +0300 Subject: [PATCH] Update README.md --- README.md | 123 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 123 insertions(+) diff --git a/README.md b/README.md index 079e98a..189bde7 100644 --- a/README.md +++ b/README.md @@ -31,3 +31,126 @@ var data = jExtract(structure); } ``` 3. Now you can do anything you want with extracted data. +## Extended usage +### Substructures +You can add substructures into your main structure. +```javascript +var struct = { + key1: 'selector1', + key2: { + subkey1: 'selector2', + subkey2: 'selector3' + } +}, data = jExtract(struct); +``` +### Options +By default, jExtract returns the text of matched element(s). But you can change this behavior by passing more than argument in your structure keys (`key: [selector, dataGettingMethod, filterMethod, asArray]` instead of `key: selector`). +#### Data getting method +It's a function that returns data that is extracted from element. +Default: `text()`. +Before v0.0.4, jExtract used its own element object that was based on jQuery. +Since v0.0.4, jExtract uses a plain jQuery object without any additions/deletions, so you can call any jQuery object methods while extracting data with jExtract. +There are a few ways to pass data getting method to jExtract: +1. a string that is a jQuery object method (e. g.: `width`); +2. an array in which first element is a jQuery object method, and others are parameters for this method (e.g.: `['attr', 'href']`); +3. your own function that recieves three parameters: `element`, `index`, `elements`: +```javascript +var struct = { + key1: ['div', function(element, index, elements){ + //in element -> one div (current in the loop) + //in index -> index of this div + //in elements -> all matched elements + }] +} +``` +##### Note: if dataGettingMethod returns `null` filterMethod will not be called. +#### Filter method +It's a function that filters extracted data. +Default: `jExtractText.get()` +jExtractText is a class that exists only in jExtract function, so you can't access it outside of it. In this class I collect useful methods for working with strings. Currently supported: +1.`jExtractText.get(trim)`: if trim is true - trims text that is stored in jExtractText and returns it. Defaults: `trim = true`. +2.`jExtractText.match(regexp, index)`: tries to match text with a given regular expression and returns a match with index = `index` if it is given or full match if is not. Defaults: no defaults. +3.`jExtractText.toInt(leaveNaN)`: tries to parseInt() text. If `leaveNaN` is true returns NaN if it appears. If `leaveNaN` is false returns 0 instead of NaN. Defaults: `leaveNaN = false`. +4.`jExtractText.toFloat(leaveNaN)`: tries to parseFloat() text. If `leaveNaN` is true returns NaN if it appears. If `leaveNaN` is false returns 0 instead of NaN. Defaults: `leaveNaN = false`. +If you want to use one of these methods, just pass a name and optionally arguments as a third parameter in your value: +```javascript +var struct = { + key1: [selector, dataGettingMethod, [name, ...arguments]] +} +``` +If you want to use your own method, pass it as third parameter. Your method will recieve 2 parameters: `value` and `index`. +```javascript +var struct = { + key1: ['div', 'text', function(value, index){ + /* if dataGettingMethod returned a string, value will be a jExtractText object. You can get the text by calling the get() method: */ + value = value.get(); + /* otherwise value will be a number/boolean/etc., that was returned by dataGettingMethod. */ + // Index is an ordinal number of element (starting with 0) + return value; + }] +} +``` +#### What to do with a single value? +jExtract generates an array of values during its loop. If there is less than two elements in the resulting array, the result will contain only first element of this array. +If you don't want to lose an array in the result, set the fourth parameter to true (default is false): +```javascript +... +key: [selector, dataGettingMethod, filterMethod, true] +... +``` +### Parent elements +By default, jExtract searches for elements in `` tag. You can pass a jQuery object as the second parameter to jExtract to change this: +```javascript +var data = jExtract(structure, $("#someElement"); +``` +Also you can create a substructure that will be applied to each matched element. +Think of the following HTML: +```html +
+
User 1
+
1
+
user1example.com
+
+
+
User 2
+
2
+
user2example.com
+
+
+
User 3
+
3
+
user3example.com
+
+
+
User 4
+
4
+
user4example.com
+
+
+
User 5
+
5
+
user5example.com
+
+```. +You can create an array of all users with each element filled with each user data. In your key pass two parameters: selector and a structure that you want to be applied to this selector. +```javascript +jExtract({ + user: ['.user', { + name: '.uname', + id: ['.uid', [], 'toInt'], + email: '.uemail' + }] +}); +``` +You will get an array: +```javascript +[ + {name: "User 1", id: 1, email: "user1example.com"}, + {name: "User 2", id: 2, email: "user2example.com"}, + {name: "User 3", id: 3, email: "user3example.com"}, + {name: "User 4", id: 4, email: "user4example.com"}, + {name: "User 5", id: 5, email: "user5example.com"} +] +``` +### Referring to current element +In your values you can refer to current element using `"."` as a selector.