fmrest-spyke 0.13.0
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/.yardopts +4 -0
- data/CHANGELOG.md +127 -0
- data/LICENSE.txt +21 -0
- data/README.md +523 -0
- data/lib/fmrest-spyke.rb +3 -0
- data/lib/fmrest/spyke.rb +21 -0
- data/lib/fmrest/spyke/base.rb +9 -0
- data/lib/fmrest/spyke/container_field.rb +59 -0
- data/lib/fmrest/spyke/model.rb +33 -0
- data/lib/fmrest/spyke/model/associations.rb +166 -0
- data/lib/fmrest/spyke/model/attributes.rb +159 -0
- data/lib/fmrest/spyke/model/auth.rb +43 -0
- data/lib/fmrest/spyke/model/connection.rb +163 -0
- data/lib/fmrest/spyke/model/container_fields.rb +40 -0
- data/lib/fmrest/spyke/model/global_fields.rb +40 -0
- data/lib/fmrest/spyke/model/http.rb +77 -0
- data/lib/fmrest/spyke/model/orm.rb +256 -0
- data/lib/fmrest/spyke/model/record_id.rb +96 -0
- data/lib/fmrest/spyke/model/serialization.rb +115 -0
- data/lib/fmrest/spyke/model/uri.rb +29 -0
- data/lib/fmrest/spyke/portal.rb +65 -0
- data/lib/fmrest/spyke/relation.rb +359 -0
- data/lib/fmrest/spyke/spyke_formatter.rb +274 -0
- data/lib/fmrest/spyke/validation_error.rb +25 -0
- metadata +96 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA256:
|
3
|
+
metadata.gz: aa1ef5a05cb00186bcd92d32bcde44a712c751a957ec5306064a9412f4fa3df4
|
4
|
+
data.tar.gz: b6f3766567c79b4c92cae9e1edb0dc7b83f573a635cbffc386a7caadd8062a63
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: c81e6e8ea6d5493c32ef28d3910c55ca168e8a19145c846a48b2c9e02dfc2466ee38b5e130dc3bec0e46d94685139e6659cea2624d5b0f9cac15c5cdfc529c0b
|
7
|
+
data.tar.gz: 8ce5116617c78a2c439c5b087e8aacfef1b187d5cfb8401b63119c19dcb4362866c42878335d28abe299be31a4589c02b67466f1675c51246000c09193230db6
|
data/.yardopts
ADDED
data/CHANGELOG.md
ADDED
@@ -0,0 +1,127 @@
|
|
1
|
+
## Changelog
|
2
|
+
|
3
|
+
### 0.13.0
|
4
|
+
|
5
|
+
* Split `fmrest` gem into `fmrest-core` and `fmrest-spyke`. `fmrest` becomes a
|
6
|
+
wrapper for the two new gems.
|
7
|
+
* Fix bug preventing connection databases with spaces in their names.
|
8
|
+
* Improved portal support with ability to delete portal records, and better
|
9
|
+
refreshing of portal records after saving the parent.
|
10
|
+
* `FmRest::Spyke::Base#__record_id` and `FmRest::Spyke::Base#__mod_id` now
|
11
|
+
always return integers if set.
|
12
|
+
|
13
|
+
### 0.12.0
|
14
|
+
|
15
|
+
* Rename `FmRest::Spyke::Base#id=` to `FmRest::Spyke::Base#__record_id=` to
|
16
|
+
prevent clobbering of FileMaker layout-defined fields
|
17
|
+
* Removed previously deprecated `FmRest::Spyke::Base(config)` syntax
|
18
|
+
* Better yard documentation
|
19
|
+
|
20
|
+
### 0.11.1
|
21
|
+
|
22
|
+
* Fix a couple crashes due to missing constants
|
23
|
+
|
24
|
+
### 0.11.0
|
25
|
+
|
26
|
+
* Added custom class for connection settings, providing indifferent access
|
27
|
+
(i.e. keys can be strings or symbols), and centralized default values and
|
28
|
+
validations
|
29
|
+
* Added `:autologin`, `:token` and `:token_store` connection settings
|
30
|
+
* Added `FmRest::Base.fmrest_config_overlay=` and related methods
|
31
|
+
* Added `FmRest::V1.request_auth_token` and
|
32
|
+
`FmRest::Spyke::Base.request_auth_token` (as well as `!`-suffixed versions
|
33
|
+
which raise exceptions on failure)
|
34
|
+
|
35
|
+
### 0.10.1
|
36
|
+
|
37
|
+
* Fix `URI.escape` obsolete warning messages in Ruby 2.7 by replacing it with
|
38
|
+
`URI.encode_www_form_component`
|
39
|
+
([PR#40](https://github.com/beezwax/fmrest-ruby/pull/40))
|
40
|
+
|
41
|
+
### 0.10.0
|
42
|
+
|
43
|
+
* Added `FmRest::StringDateAwareness` module to correct some issues when using
|
44
|
+
`FmRest::StringDate`
|
45
|
+
* Added basic timezones support
|
46
|
+
* Deprecated `class < FmRest::Spyke::Base(config_hash)` syntax in favor of
|
47
|
+
using `self.fmrest_config=`
|
48
|
+
|
49
|
+
### 0.9.0
|
50
|
+
|
51
|
+
* Added `FmRest::Spyke::Base.set_globals`
|
52
|
+
|
53
|
+
### 0.8.0
|
54
|
+
|
55
|
+
* Improved metadata when using `FmRest::Spyke::Model`. Metadata now uses
|
56
|
+
Struct/OpenStruct, so properties are accessible through `.property`, as well
|
57
|
+
as `[:property]`
|
58
|
+
* Added batch-finders `.find_in_batches` and `.find_each` for
|
59
|
+
* `FmRest::Spyke::Base`
|
60
|
+
|
61
|
+
### 0.7.1
|
62
|
+
|
63
|
+
* Made sure `Model.find_one` and `Model.find_some` work without needing to call
|
64
|
+
`Model.all` in between
|
65
|
+
|
66
|
+
### 0.7.0
|
67
|
+
|
68
|
+
* Added date coercion feature
|
69
|
+
|
70
|
+
### 0.6.0
|
71
|
+
|
72
|
+
* Implemented session logout
|
73
|
+
([#16](https://github.com/beezwax/fmrest-ruby/issues/16))
|
74
|
+
|
75
|
+
### 0.5.2
|
76
|
+
|
77
|
+
* Improved support for legacy ActiveModel 4.x
|
78
|
+
|
79
|
+
### 0.5.1
|
80
|
+
|
81
|
+
* Alias `:username` option as `:account_name` for ginjo-rfm gem
|
82
|
+
cross-compatibility
|
83
|
+
|
84
|
+
### 0.5.0
|
85
|
+
|
86
|
+
* Much improved script execution support
|
87
|
+
([#20](https://github.com/beezwax/fmrest-ruby/issues/20))
|
88
|
+
* Fixed bug when setting `default_limi` and trying to find a record
|
89
|
+
([35](https://github.com/beezwax/fmrest-ruby/issues/35))
|
90
|
+
|
91
|
+
### 0.4.1
|
92
|
+
|
93
|
+
* Prevent raising an exception when a /\_find request yields no results
|
94
|
+
([#33](https://github.com/beezwax/fmrest-ruby/issues/33) and
|
95
|
+
[#34](https://github.com/beezwax/fmrest-ruby/issues/34))
|
96
|
+
|
97
|
+
### 0.4.0
|
98
|
+
|
99
|
+
* Implement ability to set limit and offset for portals
|
100
|
+
* Implement disabling and requesting all portals
|
101
|
+
|
102
|
+
### 0.3.3
|
103
|
+
|
104
|
+
* Fix encoding of paths for layouts with brackets in them (e.g. `"\[Very Ugly\]
|
105
|
+
Layout"`)
|
106
|
+
* Raise an error if `"id"` is assigned as an attribute on a model, as it's
|
107
|
+
currently a reserved method name by Spyke
|
108
|
+
|
109
|
+
### 0.3.2
|
110
|
+
|
111
|
+
* Fix support for ActiveSupport < 5.2
|
112
|
+
([#27](https://github.com/beezwax/fmrest-ruby/issues/27))
|
113
|
+
|
114
|
+
### 0.3.0
|
115
|
+
|
116
|
+
* Add Moneta token store
|
117
|
+
|
118
|
+
### 0.2.5
|
119
|
+
|
120
|
+
* Fix crash in `fetch_container_data` when no proxy options were set
|
121
|
+
|
122
|
+
### 0.2.4
|
123
|
+
|
124
|
+
* Use `String#=~` instead of `String#match?` for Ruby <2.4 compatibility (Fixes
|
125
|
+
[#26](https://github.com/beezwax/fmrest-ruby/issues/26))
|
126
|
+
* Deprecate `FmRest.config` in favor of `FmRest.default_connection_settings`
|
127
|
+
* Honor Faraday SSL and proxy settings when fetching container files
|
data/LICENSE.txt
ADDED
@@ -0,0 +1,21 @@
|
|
1
|
+
The MIT License (MIT)
|
2
|
+
|
3
|
+
Copyright (c) 2018 Pedro Carbajal and Beezwax Datatools, Inc.
|
4
|
+
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
7
|
+
in the Software without restriction, including without limitation the rights
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
10
|
+
furnished to do so, subject to the following conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be included in
|
13
|
+
all copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
21
|
+
THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,523 @@
|
|
1
|
+
# fmrest-ruby
|
2
|
+
|
3
|
+
[![Gem Version](https://badge.fury.io/rb/fmrest.svg?style=flat)](https://rubygems.org/gems/fmrest)
|
4
|
+
![CI](https://github.com/beezwax/fmrest-ruby/workflows/CI/badge.svg)
|
5
|
+
|
6
|
+
A Ruby client for
|
7
|
+
[FileMaker 18 and 19's Data API](https://help.claris.com/en/data-api-guide)
|
8
|
+
using
|
9
|
+
[Faraday](https://github.com/lostisland/faraday) and with optional
|
10
|
+
ActiveRecord-ish ORM features through [Spyke](https://github.com/balvig/spyke).
|
11
|
+
|
12
|
+
fmrest-ruby only partially implements FileMaker 18's Data API.
|
13
|
+
See the [implementation completeness table](#api-implementation-completeness-table)
|
14
|
+
to see if a feature you need is natively supported by the gem.
|
15
|
+
|
16
|
+
## Gems
|
17
|
+
|
18
|
+
The `fmrest` gem is a wrapper for two other gems:
|
19
|
+
|
20
|
+
* `fmrest-core`, which provides the core Faraday connection builder, session
|
21
|
+
management, and other core utilities.
|
22
|
+
* `fmrest-spyke`, which provides an ActiveRecord-like ORM library built on top
|
23
|
+
of `fmrest-core` and Spyke.
|
24
|
+
|
25
|
+
## Installation
|
26
|
+
|
27
|
+
Add this to your Gemfile:
|
28
|
+
|
29
|
+
```ruby
|
30
|
+
gem 'fmrest'
|
31
|
+
```
|
32
|
+
|
33
|
+
Or if you just want to use the Faraday connection without the ORM features, do:
|
34
|
+
|
35
|
+
```ruby
|
36
|
+
gem 'fmrest-core'
|
37
|
+
```
|
38
|
+
|
39
|
+
## Simple examples
|
40
|
+
|
41
|
+
### ORM example
|
42
|
+
|
43
|
+
Most people would want to use the ORM features provided by `fmrest-spyke`:
|
44
|
+
|
45
|
+
```ruby
|
46
|
+
class Honeybee < FmRest::Spyke::Base
|
47
|
+
# Connection settings
|
48
|
+
self.fmrest_config = {
|
49
|
+
host: "…",
|
50
|
+
database: "…",
|
51
|
+
username: "…",
|
52
|
+
password: "…"
|
53
|
+
}
|
54
|
+
|
55
|
+
# Mapped attributes
|
56
|
+
attributes name: "Bee Name", age: "Bee Age"
|
57
|
+
|
58
|
+
# Portals
|
59
|
+
has_portal :flowers
|
60
|
+
|
61
|
+
# File container
|
62
|
+
container :photo, field_name: "Bee Photo"
|
63
|
+
end
|
64
|
+
|
65
|
+
# Find a record by id
|
66
|
+
bee = Honeybee.find(9)
|
67
|
+
|
68
|
+
bee.name = "Hutch"
|
69
|
+
|
70
|
+
# Add a new record to portal
|
71
|
+
bee.flowers.build(name: "Daisy")
|
72
|
+
|
73
|
+
bee.save
|
74
|
+
```
|
75
|
+
|
76
|
+
### Barebones connection example (without ORM)
|
77
|
+
|
78
|
+
In case you don't need the advanced ORM features (e.g. if you only need minimal
|
79
|
+
Data API interaction and just want a lightweight solution) you can simply use
|
80
|
+
the Faraday connection provided by `fmrest-core`:
|
81
|
+
|
82
|
+
```ruby
|
83
|
+
connection = FmRest::V1.build_connection(
|
84
|
+
host: "…",
|
85
|
+
database: "…",
|
86
|
+
username: "…",
|
87
|
+
password: "…"
|
88
|
+
)
|
89
|
+
|
90
|
+
# Get all records (as parsed JSON)
|
91
|
+
connection.get("layouts/MyFancyLayout/records")
|
92
|
+
|
93
|
+
# Create new record
|
94
|
+
connection.post do |req|
|
95
|
+
req.url "layouts/MyFancyLayout/records"
|
96
|
+
|
97
|
+
# You can just pass a hash for the JSON body
|
98
|
+
req.body = { … }
|
99
|
+
end
|
100
|
+
```
|
101
|
+
|
102
|
+
See the [main document on using the base
|
103
|
+
connection](docs/BaseConnectionUsage.md) for more.
|
104
|
+
|
105
|
+
## Connection settings
|
106
|
+
|
107
|
+
The minimum required connection settings are `:host`, `:database`, `:username`
|
108
|
+
and `:password`, but fmrest-ruby has many other options you can pass when
|
109
|
+
setting up a connection (see [full list](#full-list-of-available-options) below).
|
110
|
+
|
111
|
+
`:ssl` and `:proxy` are forwarded to the underlying
|
112
|
+
[Faraday](https://github.com/lostisland/faraday) connection. You can use this
|
113
|
+
to, for instance, disable SSL verification:
|
114
|
+
|
115
|
+
```ruby
|
116
|
+
{
|
117
|
+
host: "…",
|
118
|
+
…
|
119
|
+
ssl: { verify: false }
|
120
|
+
}
|
121
|
+
```
|
122
|
+
|
123
|
+
You can also pass a `:log` option for basic request logging, see the section on
|
124
|
+
[Logging](#Logging) below.
|
125
|
+
|
126
|
+
### Full list of available options
|
127
|
+
|
128
|
+
Option | Description | Format | Default
|
129
|
+
--------------------|--------------------------------------------|-----------------------------|--------
|
130
|
+
`:host` | Hostname with optional port, e.g. `"example.com:9000"` | String | None
|
131
|
+
`:database` | | String | None
|
132
|
+
`:username` | | String | None
|
133
|
+
`:password` | | String | None
|
134
|
+
`:account_name` | Alias of `:username` | String | None
|
135
|
+
`:ssl` | SSL options to be forwarded to Faraday | Faraday SSL options | None
|
136
|
+
`:proxy` | Proxy options to be forwarded to Faraday | Faraday proxy options | None
|
137
|
+
`:log` | Log JSON responses to STDOUT | Boolean | `false`
|
138
|
+
`:coerce_dates` | See section on [date fields](#date-fields-and-timezones) | Boolean \| `:hybrid` \| `:full` | `false`
|
139
|
+
`:date_format` | Date parsing format | String (FM date format) | `"MM/dd/yyyy"`
|
140
|
+
`:timestamp_format` | Timestmap parsing format | String (FM date format) | `"MM/dd/yyyy HH:mm:ss"`
|
141
|
+
`:time_format` | Time parsing format | String (FM date format) | `"HH:mm:ss"`
|
142
|
+
`:timezone` | The timezone for the FM server | `:local` \| `:utc` \| `nil` | `nil`
|
143
|
+
`:autologin` | Whether to automatically start Data API sessions | Boolean | `true`
|
144
|
+
`:token` | Used to manually provide a session token (e.g. if `:autologin` is `false`) | String | None
|
145
|
+
|
146
|
+
### Default connection settings
|
147
|
+
|
148
|
+
If you're only connecting to a single FM database you can configure it globally
|
149
|
+
through `FmRest.default_connection_settings=`. E.g.:
|
150
|
+
|
151
|
+
```ruby
|
152
|
+
FmRest.default_connection_settings = {
|
153
|
+
host: "…",
|
154
|
+
database: "…",
|
155
|
+
username: "…",
|
156
|
+
password: "…"
|
157
|
+
}
|
158
|
+
```
|
159
|
+
|
160
|
+
These settings will be used by default by `FmRest::Spyke::Base` models whenever
|
161
|
+
you don't set `fmrest_config=` explicitly, as well as by
|
162
|
+
`FmRest::V1.build_connection` in case you're setting up your Faraday connection
|
163
|
+
manually.
|
164
|
+
|
165
|
+
## Session token store
|
166
|
+
|
167
|
+
fmrest-ruby includes a number of options for storing session tokens:
|
168
|
+
|
169
|
+
* Memory
|
170
|
+
* ActiveRecord
|
171
|
+
* Redis
|
172
|
+
* Moneta
|
173
|
+
|
174
|
+
See the [main document on token stores](docs/TokenStore.md) for detailed info
|
175
|
+
on how to set up each store.
|
176
|
+
|
177
|
+
## Date fields and timezones
|
178
|
+
|
179
|
+
fmrest-ruby has automatic detection and coercion of date fields to and from
|
180
|
+
Ruby date/time objects. Basic timezone support is also provided.
|
181
|
+
|
182
|
+
See the [main document on date fields](docs/DateFields.md) for more info.
|
183
|
+
|
184
|
+
## ActiveRecord-like ORM (fmrest-spyke)
|
185
|
+
|
186
|
+
[Spyke](https://github.com/balvig/spyke) is an ActiveRecord-like gem for
|
187
|
+
building REST ORM models. fmrest-ruby builds its ORM features atop Spyke,
|
188
|
+
bundled in the `fmrest-spyke` gem (already included if you're using the
|
189
|
+
`fmrest` gem).
|
190
|
+
|
191
|
+
To create a model you can inherit directly from `FmRest::Spyke::Base`, which is
|
192
|
+
itself a subclass of `Spyke::Base`.
|
193
|
+
|
194
|
+
```ruby
|
195
|
+
class Honeybee < FmRest::Spyke::Base
|
196
|
+
end
|
197
|
+
```
|
198
|
+
|
199
|
+
All of Spyke's basic ORM operations work as expected:
|
200
|
+
|
201
|
+
```ruby
|
202
|
+
bee = Honeybee.new
|
203
|
+
|
204
|
+
bee.name = "Hutch"
|
205
|
+
bee.save # POST request (creates new record)
|
206
|
+
|
207
|
+
bee.name = "ハッチ"
|
208
|
+
bee.save # PATCH request (updates existing record)
|
209
|
+
|
210
|
+
bee.reload # GET request
|
211
|
+
|
212
|
+
bee.destroy # DELETE request
|
213
|
+
|
214
|
+
bee = Honeybee.find(9) # GET request
|
215
|
+
```
|
216
|
+
|
217
|
+
It's recommended that you read Spyke's documentation for more information on
|
218
|
+
these basic features. If you've used ActiveRecord or similar ORM libraries
|
219
|
+
however you'll find it quite familiar.
|
220
|
+
|
221
|
+
In addition, `FmRest::Spyke::Base` extends `Spyke::Base` with the following
|
222
|
+
features:
|
223
|
+
|
224
|
+
### Model.fmrest_config=
|
225
|
+
|
226
|
+
This allows you to set your Data API connection settings on your model:
|
227
|
+
|
228
|
+
```ruby
|
229
|
+
class Honeybee < FmRest::Spyke::Base
|
230
|
+
self.fmrest_config = {
|
231
|
+
host: "…",
|
232
|
+
database: "…",
|
233
|
+
username: "…",
|
234
|
+
password: "…"
|
235
|
+
}
|
236
|
+
end
|
237
|
+
```
|
238
|
+
|
239
|
+
This will automatically create a proper Faraday connection using those
|
240
|
+
connection settings, so you don't have to worry about setting that up.
|
241
|
+
|
242
|
+
Note that these settings are inheritable, so you could create a base class that
|
243
|
+
does the initial connection setup and then inherit from it in models using that
|
244
|
+
same connection. E.g.:
|
245
|
+
|
246
|
+
```ruby
|
247
|
+
class BeeBase < FmRest::Spyke::Base
|
248
|
+
self.fmrest_config = { host: "…", … }
|
249
|
+
}
|
250
|
+
end
|
251
|
+
|
252
|
+
class Honeybee < BeeBase
|
253
|
+
# This model will use the same connection as BeeBase
|
254
|
+
end
|
255
|
+
```
|
256
|
+
|
257
|
+
#### Connection settings overlays
|
258
|
+
|
259
|
+
There may be cases where you want to use a different set of connection settings
|
260
|
+
depending on context. For example, if you want to use username and password
|
261
|
+
provided by the user in a web application. Since `Model.fmrest_config` is set
|
262
|
+
at the class level, changing the username/password for the model in one context
|
263
|
+
would also change it in all other contexts, leading to security issues.
|
264
|
+
|
265
|
+
To solve this scenario, fmrest-ruby provides a way of defining thread-local and
|
266
|
+
reversible connection settings overlays through `Model.fmrest_config_overlay=`.
|
267
|
+
|
268
|
+
See the [main document on connection setting overlays](docs/ConfigOverlays.md)
|
269
|
+
for details on how it works.
|
270
|
+
|
271
|
+
### Model.layout
|
272
|
+
|
273
|
+
Use `Model.layout` to define the layout for your model.
|
274
|
+
|
275
|
+
```ruby
|
276
|
+
class Honeybee < FmRest::Spyke::Base
|
277
|
+
layout "Honeybees Web"
|
278
|
+
end
|
279
|
+
```
|
280
|
+
|
281
|
+
Note that you only need to set this if the name of the model and the name of
|
282
|
+
the layout differ, otherwise the default will just work.
|
283
|
+
|
284
|
+
### Model.request_auth_token
|
285
|
+
|
286
|
+
Requests a Data API session token using the connection settings in
|
287
|
+
`fmrest_config` and returns it if successful, otherwise returns `false`.
|
288
|
+
|
289
|
+
You normally don't need to use this method as fmrest-ruby will automatically
|
290
|
+
request and store session tokens for you (provided that `:autologin` is
|
291
|
+
`true`).
|
292
|
+
|
293
|
+
### Model.logout
|
294
|
+
|
295
|
+
Use `Model.logout` to log out from the database session (you may call it on any
|
296
|
+
model that uses the database session you want to log out from).
|
297
|
+
|
298
|
+
```ruby
|
299
|
+
Honeybee.logout
|
300
|
+
```
|
301
|
+
|
302
|
+
### Mapped Model.attributes
|
303
|
+
|
304
|
+
Spyke allows you to define your model's attributes using `attributes`, however
|
305
|
+
sometimes FileMaker's field names aren't very Ruby-ORM-friendly, especially
|
306
|
+
since they may sometimes contain spaces and other special characters, so
|
307
|
+
fmrest-ruby extends `attributes`' functionality to allow you to map
|
308
|
+
Ruby-friendly attribute names to FileMaker field names. E.g.:
|
309
|
+
|
310
|
+
```ruby
|
311
|
+
class Honeybee < FmRest::Spyke::Base
|
312
|
+
attributes first_name: "First Name", last_name: "Last Name"
|
313
|
+
end
|
314
|
+
```
|
315
|
+
|
316
|
+
You can then simply use the pretty attribute names whenever working with your
|
317
|
+
model and they will get mapped to their FileMaker fields:
|
318
|
+
|
319
|
+
```ruby
|
320
|
+
bee = Honeybee.find(1)
|
321
|
+
|
322
|
+
bee.first_name # => "Princess"
|
323
|
+
bee.last_name # => "Buzz"
|
324
|
+
|
325
|
+
bee.first_name = "Queen"
|
326
|
+
|
327
|
+
bee.attributes # => { "First Name": "Queen", "Last Name": "Buzz" }
|
328
|
+
```
|
329
|
+
|
330
|
+
### Model.has_portal
|
331
|
+
|
332
|
+
You can define portal associations on your model wth `has_portal`, as such:
|
333
|
+
|
334
|
+
```ruby
|
335
|
+
class Honeybee < FmRest::Spyke::Base
|
336
|
+
has_portal :flowers
|
337
|
+
end
|
338
|
+
|
339
|
+
class Flower < FmRest::Spyke::Base
|
340
|
+
attributes :color, :species
|
341
|
+
end
|
342
|
+
```
|
343
|
+
|
344
|
+
See the [main document on portal associations](docs/Portals.md) for details.
|
345
|
+
|
346
|
+
### Dirty attributes
|
347
|
+
|
348
|
+
fmrest-ruby includes support for ActiveModel's Dirty mixin out of the box,
|
349
|
+
providing methods like:
|
350
|
+
|
351
|
+
```ruby
|
352
|
+
bee = Honeybee.new
|
353
|
+
|
354
|
+
bee.changed? # => false
|
355
|
+
|
356
|
+
bee.name = "Maya"
|
357
|
+
|
358
|
+
bee.changed? # => true
|
359
|
+
|
360
|
+
bee.name_changed? # => true
|
361
|
+
```
|
362
|
+
|
363
|
+
fmrest-ruby uses the Dirty functionality to only send changed attributes back
|
364
|
+
to the server on save.
|
365
|
+
|
366
|
+
You can read more about [ActiveModel's Dirty in Rails
|
367
|
+
Guides](https://guides.rubyonrails.org/active_model_basics.html#dirty).
|
368
|
+
|
369
|
+
### Query API
|
370
|
+
|
371
|
+
Since Spyke is API-agnostic it only provides a wide-purpose `.where` method for
|
372
|
+
passing arbitrary parameters to the REST backend. fmrest-ruby however is well
|
373
|
+
aware of its backend API, so it extends Spkye models with a bunch of useful
|
374
|
+
querying methods: `.query`, `.limit`, `.offset`, `.sort`, `.portal`, `.script`,
|
375
|
+
etc.
|
376
|
+
|
377
|
+
See the [main document on querying](docs/Querying.md) for detailed information
|
378
|
+
on the query API methods.
|
379
|
+
|
380
|
+
### Finding records in batches
|
381
|
+
|
382
|
+
Sometimes you want to iterate over a very large number of records to do some
|
383
|
+
processing, but requesting them all at once would result in one huge request to
|
384
|
+
the Data API, and loading too many records in memory all at once.
|
385
|
+
|
386
|
+
To mitigate this problem you can use `.find_in_batches` and `.find_each`.
|
387
|
+
|
388
|
+
See the [main document on finding in batches](docs/FindInBatches.md) for
|
389
|
+
detailed information on how those work.
|
390
|
+
|
391
|
+
### Container fields
|
392
|
+
|
393
|
+
You can define container fields on your model class with `container`:
|
394
|
+
|
395
|
+
```ruby
|
396
|
+
class Honeybee < FmRest::Spyke::Base
|
397
|
+
container :photo, field_name: "Beehive Photo ID"
|
398
|
+
end
|
399
|
+
```
|
400
|
+
|
401
|
+
See the [main document on container fields](docs/ContainerFields.md) for
|
402
|
+
details on how to use it.
|
403
|
+
|
404
|
+
### Script execution
|
405
|
+
|
406
|
+
The FM Data API allows running scripts as part of many types of requests, and
|
407
|
+
`fmrest-spyke` provides mechanisms for all of them.
|
408
|
+
|
409
|
+
See the [main document on script execution](docs/ScriptExecution.md) for
|
410
|
+
details.
|
411
|
+
|
412
|
+
### Setting global field values
|
413
|
+
|
414
|
+
You can call `.set_globals` on any `FmRest::Spyke::Base` model to set global
|
415
|
+
field values on the database that model is configured for.
|
416
|
+
|
417
|
+
See the [main document on setting global field values](docs/GlobalFields.md)
|
418
|
+
for details.
|
419
|
+
|
420
|
+
## Logging
|
421
|
+
|
422
|
+
If using `fmrest-spyke` with Rails then pretty log output will be set up for
|
423
|
+
you automatically by Spyke (see [their
|
424
|
+
README](https://github.com/balvig/spyke#log-output)).
|
425
|
+
|
426
|
+
You can also enable simple Faraday STDOUT logging of raw requests (useful for
|
427
|
+
debugging) by passing `log: true` in the options hash for either
|
428
|
+
`FmRest.default_connection_settings=` or your models' `fmrest_config=`, e.g.:
|
429
|
+
|
430
|
+
```ruby
|
431
|
+
FmRest.default_connection_settings = {
|
432
|
+
host: "…",
|
433
|
+
…
|
434
|
+
log: true
|
435
|
+
}
|
436
|
+
|
437
|
+
# Or in your model
|
438
|
+
class LoggyBee < FmRest::Spyke::Base
|
439
|
+
self.fmrest_config = {
|
440
|
+
host: "…",
|
441
|
+
…
|
442
|
+
log: true
|
443
|
+
}
|
444
|
+
end
|
445
|
+
```
|
446
|
+
|
447
|
+
If you need to set up more complex logging for your models can use the
|
448
|
+
`faraday` block inside your class to inject your own logger middleware into the
|
449
|
+
Faraday connection, e.g.:
|
450
|
+
|
451
|
+
```ruby
|
452
|
+
class LoggyBee < FmRest::Spyke::Base
|
453
|
+
faraday do |conn|
|
454
|
+
conn.response :logger, MyApp.logger, bodies: true
|
455
|
+
end
|
456
|
+
end
|
457
|
+
```
|
458
|
+
|
459
|
+
## API implementation completeness table
|
460
|
+
|
461
|
+
FM Data API reference: https://fmhelp.filemaker.com/docs/18/en/dataapi/
|
462
|
+
|
463
|
+
| FM 18 Data API feature | Supported by basic connection | Supported by FmRest::Spyke::Base |
|
464
|
+
|-------------------------------------|-------------------------------|----------------------------------|
|
465
|
+
| Log in using HTTP Basic Auth | Yes | Yes |
|
466
|
+
| Log in using OAuth | No | No |
|
467
|
+
| Log in to an external data source | No | No |
|
468
|
+
| Log in using a FileMaker ID account | No | No |
|
469
|
+
| Log out | Yes | Yes |
|
470
|
+
| Get product information | Manual* | No |
|
471
|
+
| Get database names | Manual* | No |
|
472
|
+
| Get script names | Manual* | No |
|
473
|
+
| Get layout names | Manual* | No |
|
474
|
+
| Get layout metadata | Manual* | No |
|
475
|
+
| Create a record | Manual* | Yes |
|
476
|
+
| Edit a record | Manual* | Yes |
|
477
|
+
| Duplicate a record | Manual* | No |
|
478
|
+
| Delete a record | Manual* | Yes |
|
479
|
+
| Edit portal records | Manual* | Yes |
|
480
|
+
| Get a single record | Manual* | Yes |
|
481
|
+
| Get a range of records | Manual* | Yes |
|
482
|
+
| Get container data | Manual* | Yes |
|
483
|
+
| Upload container data | Manual* | Yes |
|
484
|
+
| Perform a find request | Manual* | Yes |
|
485
|
+
| Set global field values | Manual* | Yes |
|
486
|
+
| Run a script | Manual* | Yes |
|
487
|
+
| Run a script with another request | Manual* | Yes |
|
488
|
+
|
489
|
+
\* You can manually supply the URL and JSON to a `FmRest` connection.
|
490
|
+
|
491
|
+
## Supported Ruby versions
|
492
|
+
|
493
|
+
fmrest-ruby aims to support and is [tested against](https://github.com/beezwax/fmrest-ruby/actions?query=workflow%3ACI)
|
494
|
+
the following Ruby implementations:
|
495
|
+
|
496
|
+
* Ruby 2.5
|
497
|
+
* Ruby 2.6
|
498
|
+
* Ruby 2.7
|
499
|
+
|
500
|
+
## Gem development
|
501
|
+
|
502
|
+
After checking out the repo, run `bin/setup` to install dependencies. Then, run
|
503
|
+
`rake spec` to run the tests. You can also run `bin/console` for an interactive
|
504
|
+
prompt that will allow you to experiment (it will auto-load all fixtures in
|
505
|
+
spec/fixtures).
|
506
|
+
|
507
|
+
To install all gems onto your local machine, run
|
508
|
+
`bundle exec rake all:install`. To release a new version, update the version
|
509
|
+
number in `lib/fmrest/version.rb`, and then run `bundle exec rake all:release`,
|
510
|
+
which will create a git tag for the version, push git commits and tags, and
|
511
|
+
push the `.gem` files to [rubygems.org](https://rubygems.org).
|
512
|
+
|
513
|
+
## License
|
514
|
+
|
515
|
+
The gem is available as open source under the terms of the
|
516
|
+
[MIT License](https://opensource.org/licenses/MIT).
|
517
|
+
See [LICENSE.txt](LICENSE.txt).
|
518
|
+
|
519
|
+
## Disclaimer
|
520
|
+
|
521
|
+
This project is not sponsored by or otherwise affiliated with FileMaker, Inc,
|
522
|
+
an Apple subsidiary. FileMaker is a trademark of FileMaker, Inc., registered in
|
523
|
+
the U.S. and other countries.
|