This is an automated email from the ASF dual-hosted git repository.
poorejc pushed a commit to branch FLAGON-469
in repository https://gitbox.apache.org/repos/asf/incubator-flagon-useralejs.git
The following commit(s) were added to refs/heads/FLAGON-469 by this push:
new 865152b [FLAGON-479] Updated README for UserALEjs Module Import
Example
865152b is described below
commit 865152bd5d7bb91937f17870f5c1fd0af77bfeb9
Author: poorejc <[email protected]>
AuthorDate: Sat Jan 11 21:11:59 2020 -0500
[FLAGON-479] Updated README for UserALEjs Module Import Example
---
example/README.md | 62 ++++++++++++++++++++++---------------------
example/index.js | 2 +-
example/webpackUserAleExample | 1 +
src/packageLogs.js | 4 +--
4 files changed, 36 insertions(+), 33 deletions(-)
diff --git a/example/README.md b/example/README.md
index e0f2e96..3265797 100755
--- a/example/README.md
+++ b/example/README.md
@@ -1,7 +1,7 @@
-# This UserALE.js Example Utility
+# The UserALE.js Example Utility
This directory provides
- * example usage for UserALE.js within a simple HTML Webpage;
+ * example usage for UserALE.js deployed as a **script tag** within a simple
HTML Webpage;
* a testing utility for developers to evaluate UserALE modifications to
logged events;
* a means of viewing log event structure within a simple UserALE logging
server;
* a means of testing UserALE.js API functions within a simple HTML Webpage.
@@ -10,26 +10,24 @@ This directory provides
Ensure that you have [node.js](https://nodejs.org/) installed.
-You will need to clone the [UserALE.js
repository](https://github.com/apache/incubator-flagon-useralejs) and install
npm dev dependencies to run the Example Utility.
+You will need to clone the [UserALE.js
repository](https://github.com/apache/incubator-flagon-useralejs) and `npm
install` install dev dependencies to run the Example Utility.
Please see the
[Prerequsites](https://github.com/apache/incubator-flagon-useralejs#prerequsites)
for additional details.
## Using the Example Page
-The UserALE.js Example Page is a simple HTML Webpage with a simple DOM,
including a single button.
+This Example Page is a simple HTML Webpage with UserALE.js included as a
**script tag**.
-To generate UserALE.js logs with the Example Page, you will need to modify the
'src' HTML5 parameter of the UserALE.js script tag.
+To generate UserALE.js logs with the Example Page, you may need to modify the
'src' HTML5 parameter of the UserALE.js script tag.
-The `src` parameter should reference the complete file path to your version of
the minified UserALE.js script (userale-2.0.2.min.js), usually in the /build
dir of your cloned incubator-flagon-useralejs repository. See the snippet below.
-
-ProTip: An easy way to find the complete path to your minified UserALE.js
script is to simply drag userale-2.0.2.min.js into your browser, copy the URL,
and paste into the `src` parameter.
+The `src` parameter should reference the file path to your version of the
minified UserALE.js script, in the /build dir of your cloned
`incubator-flagon-useralejs` repository or `flagon-userale` node module. See
the snippet below.
```
<script
- src="file:///{your file
path}/incubator-flagon-useralejs/build/userale-2.0.2.min.js" #REPLACE WITH YOUR
PATH
+ src="../build/userale-2.1.0.min.js" #works out of the box if downloaded
flagon-userale via npm
data-url="http://localhost:8000/";
data-user="example-user"
- data-version="2.0.2"
+ data-version="2.1.0"
data-tool="Apache UserALE.js Example"
></script>
```
@@ -45,10 +43,23 @@ On this page, all user events will be captured and sent to
the logging server. S
The UserALE.js Example page can be used to test the structure of logs after
instrumentation or UserALE.js src code modification. It can also be used to
experiment with UserALE.js API functions.
-In order to experiment with various elements of the UserALE.js API, simply
modify the API examples in `aleAPI.js`.
+In order to experiment with various elements of the UserALE.js API, simply
modify the well documented API examples in `index.js`. Details about the API
can be found at the [UserALE.js parent
README](https://github.com/apache/incubator-flagon-useralejs/tree/FLAGON-469).
However, a complete list of exported functions in the API can be found below:
+| Function | Description | Notes |
+|---|---|---|
+| userale.options | modify userale's configuration option | see top level
README for complete list of options |
+| userale.filter | filters out logs from logging queue by keys or values |
filters are callbacks with global scope |
+| userale.map | modify/add log keys or values | mappings are callbacks with
global scope |
+| userale.log | appends a custom log to the log queue | the custom log object
is an object key:value pairs |
+| userale.packageLog | transforms the provided event into a log and appends it
to the log queue | designed for HTML events |
+| userale.packageCustomLog | packages the provided customLog to include
standard meta data and appends it to the log queue | designed for non HTML
events|
+| userale.details | defines the way information is extracted from various
events | supports packageLog/packageCustomLog 'details' |
+| userale.getSelector | builds a string CSS selector from the provided HTML
element id | populates 'target' field in packaged logs |
+| userale.buildPath| builds an array of elements from the provided event
target, to the root element (DOM path) | populates the 'path' field in packaged
logs |
+| userale.start | used to start the logging process if | unecessary if
'autostart' is set to true in initial setting (default) |
+| userale.stop | halts the logging process. Logs will no longer be sent | will
need to invoke userale.start to restart logging |
-NOTE: Each modification of `index.html` or `aleAPI.js` will require that you
both save the modifications and refresh the webpage in your browser.
+NOTE: Each modification of `index.html` or `index.js` will require that you
both save the modifications and refresh the webpage in your browser.
See the [Flagon website](http://flagon.incubator.apache.org/) for additional
documentation on the
[API](http://flagon.incubator.apache.org/docs/useralejs/API/) and [testing for
scale](http://flagon.incubator.apache.org/docs/stack/scaling/).
@@ -56,21 +67,12 @@ See the [Flagon
website](http://flagon.incubator.apache.org/) for additional doc
The example logging server receives log from any UserALE.js instrumented page
at `localhost:8000`.
-This means you can test logs from your own instrumented application, the
[UserALE.js
WebExtension](https://github.com/apache/incubator-flagon-useralejs/tree/master/src/UserALEWebExtension),
or the UserALE.js Example Page, so long as the `data-url` parameter is set to
`localhost:8000`. This is the default setting for both the WebExtension and
UserALE.js Example Page. See below:
-
-```
- <script
- src="file:///{your file
path}/incubator-flagon-useralejs/build/userale-2.0.2.min.js" #REPLACE WITH YOUR
PATH
- data-url="http://localhost:8000/"; #MUST BE SET TO 'localhost:8000'
- data-user="example-user"
- data-version="2.0.2"
- data-tool="Apache UserALE.js Example"
- ></script>
-```
+This means you can test logs from your own instrumented application, the
[UserALE.js
WebExtension](https://github.com/apache/incubator-flagon-useralejs/tree/master/src/UserALEWebExtension),
+or the UserALE.js Example Page, so long as the `data-url` parameter is set to
`localhost:8000`. This is the default setting for both the WebExtension and
UserALE.js Example Page. See the example above.
Once your UserALE.js script tag is properly configured to point to a minified
UserALE.js script, and `localhost:8000`, you can log to the Example Logging
Server.
-Simply navigate to your cloned `incubator-flagon-useralejs` repository and run
the following:
+from the `/example` directory or its parent directory, run the following:
```
$npm run example:watch
@@ -79,12 +81,12 @@ $npm run example:watch
Once started you will see:
```
-> [email protected] example:watch
.../Apache_Flagon/prod/incubator-flagon-useralejs
+> [email protected] example:watch ...
> nodemon -w ./example example/server.js
[nodemon] 1.19.1
[nodemon] to restart at any time, enter `rs`
-[nodemon] watching:
.../Apache_Flagon/prod/incubator-flagon-useralejs/example/**/*
+[nodemon] watching: ...
[nodemon] starting `node example/server.js`
UserAle Local running on port 8000
```
@@ -101,9 +103,9 @@ Then start using your instrumented application, browser, or
the UserALE.js Examp
userAction: true,
details: null,
userId: 'example-user',
- toolVersion: '2.0.2',
+ toolVersion: '2.1.0',
toolName: 'Apache UserALE.js Example',
- useraleVersion: '1.0.0' },
+ useraleVersion: '2.1.0' },
...
]
```
@@ -114,8 +116,8 @@ Kill the logging script with `^C` or as you would any bash
script.
In addition to showing in your terminal, logs collected by the UserALE.js
Example Server are written locally to file.
-Find them in your cloned `incubator-flagon-useralejs` in the `/logs` dir. A
new log file will appear each time you restart the logging server.
+Find them in `/logs` under the top level flagon-userale dir. A new log file
will appear each time you restart the logging server.
## Contributing
-Contributions are welcome! Simply [submit an issue
report](https://issues.apache.org/jira/browse/FLAGON) for problems you
encounter or a pull request for your feature or bug fix. The core team will
review it and work with you to incorporate it into UserALE.js.
\ No newline at end of file
+Contributions are welcome! Simply [submit an issue
report](https://issues.apache.org/jira/browse/FLAGON) for problems you
encounter or submit a pull request for your feature or bug fix. The core team
will review it and work with you to incorporate it into UserALE.js.
\ No newline at end of file
diff --git a/example/index.js b/example/index.js
index 2cf8cc6..89d9d89 100644
--- a/example/index.js
+++ b/example/index.js
@@ -29,7 +29,7 @@ window.userale.options({
/**the 'filter' API allows you to eliminate logs you don't want
* use as a global filter and add classes of events or log types to eliminate
* or use in block scope to surgically eliminate logs from specific elements
from an event handler
- * The filter below reduces logs to capture click, change, select, and submit
events on index.html
+ * The filter below reduces logs to capture click, change, select, scroll and
submit events on index.html
* Note that for surgical filters, you may need to clear or reset back to a
global filter callback
* the same is true for the 'map' API. See examples below:
*/
diff --git a/example/webpackUserAleExample b/example/webpackUserAleExample
new file mode 160000
index 0000000..a12a083
--- /dev/null
+++ b/example/webpackUserAleExample
@@ -0,0 +1 @@
+Subproject commit a12a083c4a7962d2da9169744fd7df850d6b1032
diff --git a/src/packageLogs.js b/src/packageLogs.js
index 78f460f..26ad1ed 100644
--- a/src/packageLogs.js
+++ b/src/packageLogs.js
@@ -68,7 +68,7 @@ export function initPackager(newLogs, newConfig) {
}
/**
- * Transforms the provided event into a log and appends it to the log
container.
+ * Transforms the provided HTML event into a log and appends it to the log
queue.
* @param {Object} e The event to be logged.
* @param {Function} detailFcn The function to extract additional log
parameters from the event.
* @return {boolean} Whether the event was logged.
@@ -123,7 +123,7 @@ export function packageLog(e, detailFcn) {
}
/**
- * Packages the provided customLog to include standard meta data and appends
it to the log container.
+ * Packages the provided customLog to include standard meta data and appends
it to the log queue.
* @param {Object} customLog The behavior to be logged.
* @param {Function} detailFcn The function to extract additional log
parameters from the event.
* @param {boolean} userAction Indicates user behavior (true) or system
behavior (false)
