Skip to content

Commit c204e8e

Browse files
committed
wip
1 parent e64b49c commit c204e8e

12 files changed

Lines changed: 4557 additions & 65 deletions

File tree

README.md

Lines changed: 119 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -6,20 +6,19 @@ A set of magic helpers to use with AlpineJS
66

77
## About
88

9-
When to use?
9+
This adds three magic properties to use with Alpine JS. ***More to come!***
10+
| Magic Properties | Description |
11+
| --- | --- |
12+
| [`$fetch`](#fetch) | Using Axios, fetch JSON from an external source. |
13+
| [`$interfal`](#interval) | Run a function every n seconds. Optionally start and stop the timer. |
14+
| [`$truncate`](#truncate) | Limit a text string to a specific amount of characters or words. |
15+
16+
🚀 If you have ideas for more properties, please open a discussion
17+
##### TODO:
18+
1. Add more useful methods
19+
1. Create better examples with example pages
20+
1. Write tests
1021

11-
```html
12-
<div x-data="{}">
13-
</div>
14-
```
15-
```js
16-
function functionName() {
17-
return {
18-
foo: 'bar'
19-
}
20-
}
21-
```
22-
[Demo](url)
2322

2423
## Installation
2524

@@ -29,6 +28,16 @@ Include the following `<script>` tag in the `<head>` of your document (before Al
2928
<script src="https://cdn.jsdelivr.net/gh/kevinbatdorf/alpine-magic-helpers@0.x.x/dist/index.js"></script>
3029
```
3130

31+
Or only use the specific methods you need:
32+
33+
```html
34+
<script src="https://cdn.jsdelivr.net/gh/kevinbatdorf/alpine-magic-helpers@0.x.x/dist/fetch.js"></script>
35+
<script src="https://cdn.jsdelivr.net/gh/kevinbatdorf/alpine-magic-helpers@0.x.x/dist/interval.js"></script>
36+
<script src="https://cdn.jsdelivr.net/gh/kevinbatdorf/alpine-magic-helpers@0.x.x/dist/truncate.js"></script>
37+
```
38+
39+
---
40+
3241
### Manual
3342

3443
If you wish to create your own bundle:
@@ -44,6 +53,103 @@ import 'alpine-magic-helpers'
4453
import 'alpinejs'
4554
```
4655

56+
57+
### `$fetch`
58+
**Example:**
59+
```html
60+
<div x-data="{ url: 'https://jsonplaceholder.typicode.com/todos/1' }"
61+
x-init="$fetch(url).then(data => console.log(data))">
62+
<!-- After init, data will be logged to the console -->
63+
</div>
64+
```
65+
66+
**Optionally pass in an options**
67+
68+
By default, `$fetch` will return the JSON data object. However, because we are using Axios behind the scenes, you may pass in an object to customize the request [See all options](https://github.com/axios/axios).
69+
70+
**Example:**
71+
72+
```html
73+
<div x-data="{ url: 'https://jsonplaceholder.typicode.com/todos/1' }"
74+
x-init="$fetch({ url: url, method: 'post' }).then({ data } => console.log(data))">
75+
</div>
76+
```
77+
> Note that this will return the entire response object, whereas by default `$fetch` will only return the data
78+
79+
---
80+
81+
### `$interval`
82+
**Example:**
83+
```html
84+
<div
85+
x-data="{
86+
timer: 500,
87+
funtionToRun: function() {
88+
console.log('Hello console')
89+
}
90+
}"
91+
x-init="$interval(funtionToRun, timer)">
92+
</div>
93+
```
94+
95+
**Optionally pass in options**
96+
97+
By default, `$interval ` will run your function every `nth` millisecond when browser provides an animation frame (via `requestAnimationFrame`). This means that the function will not run if the browser tab is not visible. Optionally, you may pass in the following options as the second parameter:
98+
| Property | Description |
99+
| --- | --- |
100+
| `timer` | Timer in milliseconds. |
101+
| `delay` | Delay the first run. N.B. The first run is also relayed by the timer time. |
102+
| `forceInterval` | Ignore the browser animation request mechinism. Default is false |
103+
104+
> ⚠️ We also add a hidden property `autoIntervalTest` that will play/pause the timer depending on it's "truthyness"
105+
106+
**Example:**
107+
108+
```html
109+
<div
110+
x-data="{
111+
timer: 500,
112+
autoIntervalTest: true, // optional to start/stop the timer
113+
funtionToRun: function() {
114+
console.log('Hi again!')
115+
}
116+
}"
117+
x-init="$interval(funtionToRun, { timer: 1000, delay: 5000, forceInterval: true })"
118+
@click="autoIntervalTest = !autoIntervalTest">
119+
</div>
120+
```
121+
122+
---
123+
124+
### `$truncate`
125+
**Example:**
126+
```html
127+
<div
128+
x-data="{ characters: 50, string: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'}"
129+
x-text="$truncate(string, characters)"
130+
@click="characters = undefined">
131+
<!-- Text will show 'Lorem ipsum dolor sit amet, consectetur adipiscing' and will reveal all when clicked-->
132+
</div>
133+
```
134+
135+
**Optionally pass in options**
136+
137+
By default, `$truncate` will return take characters as a parameter. Instead you can pass in an object and trim by words.
138+
139+
**Example:**
140+
141+
```html
142+
<div
143+
x-data="{ count: 5, string: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.'}"
144+
x-text="$truncate(string, {words: count})"
145+
@click="count = 10">
146+
<!-- Will start with 5 words, then increase to 10 when clicked -->
147+
</div>
148+
```
149+
> Behind the scenes, for words, this uses `sentence.split(" ").splice(0, words).join(" ")` which does not define a word in all languages.
150+
151+
---
152+
47153
## License
48154

49155
Copyright (c) 2020 Kevin Batdorf

0 commit comments

Comments
 (0)