README.md (6958B)
1 # rama.js 2 3 1. [about](#about) 4 2. [installation](#installation) 5 3. [documentation](#documentation) 6 4. [examples](#examples) 7 5. [contributing](#contributing) 8 6. [other projects](#other-projects) 9 10 ## about 11 12 The simplest way to automate web tasks is using the language of the web - 13 Javascript and the normal web apis by just running the code from the developer 14 console. This way you don't need to install any program, extension or separate 15 browser to just automate this one feature. Additionally you don't need to learn 16 any new tools or apis. 17 18 But running simple tasks from the browser console has one big downside: All 19 activities of your script have to take place on that specific website instance. 20 **rama.js** tries to change this. It works by opening an [iframe][] and 21 providing a simple api to control it. So you can for example automate clicking 22 on a link and the script will keep running on the new page. 23 24 However due to the [same-origin policy][] all actions are still limited to pages 25 on that specific domain. I think you can turn that off in most browsers, but 26 it's generally a very bad idea as it opens security vulnerabilities. 27 28 ### name 29 30 rama.js is not named after the Hindu God 31 [Rama][rama-god] but after the Swedish verb _att rama 32 in_ = _to frame_. 33 34 ## installation 35 36 There obviously is no npm-package for this as this would not benefit anyone. To 37 use rama.js just paste `rama.js` or the minified version `rama.min.js` in your 38 console or add them to the top of your script. 39 40 ## documentation 41 42 ### iframe functions 43 44 #### rama.new(settings\<optional\>) 45 46 Creates a new `<iframe>` and returns the `rframe`-object. A settings object can 47 optionally be passed in. Possible settings are: 48 49 - `name` / `id`: for the new iframe (see 50 [below](#rframename-or-rframeid-read-only)). Default is something like 51 `rama-273` 52 - `parent`: parent DOM element. Default is the `body`-tag 53 - `url`: url to open (Can be `about:blank`). Default is the current url of the 54 main window 55 56 ```javascript 57 let client = rama.new({ 58 url: "about:blank", 59 parent: document.getElementById("iframe-wrapper") 60 }); 61 ``` 62 63 #### rframe.t or rframe.tag (read-only) 64 65 Access the `<iframe>`-tag. 66 67 ```javascript 68 client.t.classList.add("invisible"); 69 ``` 70 71 #### rframe.d or rframe.document (read-only) 72 73 Access the `document` inside the `<iframe>`. There is also the handy shorthand 74 `rframe.d.qsa(selector)` for `Array.from(rframe.d.querySelectorAll(selector))`. 75 76 ```javascript 77 let testElement = client.d.getElementById("test-element"); 78 let testElements = client.d.qsa(".test"); 79 ``` 80 81 #### rframe.w or rframe.window (read-only) 82 83 Access the `window`-object of the `<iframe>`. 84 85 ```javascript 86 client.w.history.back(); 87 ``` 88 89 #### rframe<nolink>.name or rframe<nolink>.id (read-only) 90 91 There is a good description for this on [MDN web docs][iframe]: 92 93 > A targetable name for the embedded browsing context. This can be used in the 94 > target attribute of the `<a>`, `<form>`, or `<base>` elements; the formtarget 95 > attribute of the `<input>` or `<button>` elements; or the windowName parameter 96 > in the `window.open()` method. 97 98 ```javascript 99 document.getElementById("links-to-frame").target = client.name; 100 ``` 101 102 #### rframe.waitForReload() 103 104 Pretty self-explanatory: Returns a Promise to wait for a reload of the iframe. 105 106 ```javascript 107 button.click(); 108 await client.waitForReload(); 109 // do something on the new page 110 ``` 111 112 #### rframe.waitFor(testFunction, delay\<optional\>) 113 114 Retruns a Promise, which resolves when `testFunction` evaluates to true. The 115 `rframe`-object is passed to `testFunction`. At the moment the implementation is 116 a bit hacky as it uses `setInterval()`. The delay for `setInterval()` can be 117 changed through the `delay` parameter, the default is 500 (measured in 118 milliseconds). 119 120 ```javascript 121 await client.waitFor( 122 (client) => client.d.querySelector("#some-div").style.display == "block" 123 ); 124 // do something now that your checks succeeded 125 ``` 126 127 #### rframe.waitForSelector(selector, delay\<optional\>) 128 129 Returns a Promise which resolves when any element on the page matches the given 130 selector. Useful for web-frameworks where at `rframe.waitForReload()` not 131 everything on the page is ready. Works by using `rframe.waitFor()`: the optional 132 `delay` attribute gets passed through. 133 134 ```javascript 135 button.click(); 136 await client.waitForReload(); 137 await client.waitForSelector("#some-div-somewhere"); 138 // do something on the new page 139 ``` 140 141 #### rframe.close() 142 143 Removes the iframe from the DOM. 144 145 ```javascript 146 client.close(); 147 ``` 148 149 #### rama.clearpage() 150 151 Clears the current window by setting the `<body>` to `display: none`. Changes 152 the standard parent for new iframes to the `<html>`-tag to keep them visible. 153 154 ```javascript 155 rama.clearpage(); 156 ``` 157 158 #### custom styling 159 160 All frames can be accessed with the CSS selector/class `rama-frame`. 161 Additionally every single frame has its id/name also as id on the iframe tag. 162 163 ### other functions 164 165 **rama.js** also provides some other functions not directly related to iframes, 166 to make web scripting easier: 167 168 #### rama.loadjs(url) 169 170 Creates a new script tag with the specified url. Useful for loading external 171 libraries. Returns a Promise, which resolves, when the scripts finished loading. 172 173 ```javascript 174 await rama.loadjs( 175 "https://cdn.jsdelivr.net/gh/davidshimjs/qrcodejs/qrcode.min.js" 176 ); 177 ``` 178 179 #### rama.loadcss(csstext) 180 181 Injects the given CSS into a new `<style>`-tag. 182 183 ```javascript 184 rama.loadcss("h1 {color: red;}"); 185 ``` 186 187 #### rama.clearcss() 188 189 Removes all `<style>` and `<link rel="stylesheet">`-tags. 190 191 NOTICE: inline styles given to specific elements stay! 192 193 ```javascript 194 rama.clearcss(); 195 ``` 196 197 ## examples 198 199 See examples folder 200 201 ## contributing 202 203 Issues and Pull-Requests are welcome. 204 205 The code is formatted with [prettier][]: the configuration can be found in 206 `.prettierrc`. To generate `rama.min.js` [terser][] is used: 207 208 ```bash 209 terser -c -m -o rama.min.js -- rama.js 210 ``` 211 212 ## other projects 213 214 There are several other approaches to web scripting, which could fit your needs 215 better: 216 217 - professional test frameworks like [puppeteer][] or [selenium][] 218 - userscripts. A large collection can be found on [openuserjs][] 219 - get the content with a utility like [curl][] and parse it yourself 220 221 I think however, at the moment this is the only project with this main idea. But 222 one can never be sure that there isn't some other similar project hidden 223 somewhere on the internet. So if you built or found one please write me a mail, 224 as I'm very curious about other ideas. 225 226 [iframe]: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/iframe 227 [same-origin policy]: https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy 228 [rama-god]: https://en.wikipedia.org/wiki/Rama 229 [prettier]: https://github.com/prettier/prettier 230 [terser]: https://github.com/terser/terser 231 [puppeteer]: https://github.com/puppeteer/puppeteer/ 232 [selenium]: https://www.selenium.dev/ 233 [openuserjs]: https://openuserjs.org/ 234 [curl]: https://en.wikipedia.org/wiki/CURL