Skip to content

Commit

Permalink
Upgrade website to Docusaurus v2
Browse files Browse the repository at this point in the history
  • Loading branch information
@janko
janko committed Jun 1, 2023
1 parent 004ffc8 commit fa5e0c5
Show file tree
Hide file tree
Showing 36 changed files with 13,067 additions and 8,542 deletions.
1 change: 1 addition & 0 deletions .gitignore
View file
Original file line number Diff line number Diff line change
Expand Up @@ -4,3 +4,4 @@ pkg/
website/build
coverage/
node_modules
.docusaurus
95 changes: 68 additions & 27 deletions doc/getting_started.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ id: getting-started
title: Getting Started
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

## Quick start

Add Shrine to the Gemfile and write an initializer which sets up the storage
Expand Down Expand Up @@ -32,32 +35,39 @@ Next decide how you will name the attachment attribute on your model, and run a
migration that adds an `<attachment>_data` text or JSON column, which Shrine
will use to store all information about the attachment:

<!--DOCUSAURUS_CODE_TABS-->
<!--Sequel-->
<Tabs>
<TabItem value="sequel" label="Sequel">

```rb
Sequel.migration do
change do
add_column :photos, :image_data, :text # or :jsonb
add_column :photos, :image_data, :text # or :jsonb
end
end
```

<!--ActiveRecord-->
</TabItem>
<TabItem value="activerecord" label="Active Record">

```rb
class AddImageDataToPhotos < ActiveRecord::Migration
def change
add_column :photos, :image_data, :text # or :jsonb
add_column :photos, :image_data, :text # or :jsonb
end
end
```

<!--Rails-->
</TabItem>
<TabItem value="rails" label="Rails">

```rb
$ rails generate migration add_image_data_to_photos image_data:text # or image_data:jsonb
$ rails generate migration add_image_data_to_photos image_data:text # or image_data:jsonb
```
If using `jsonb` consider adding a [gin index] for fast key-value pair searchability within `image_data`.

<!--END_DOCUSAURUS_CODE_TABS-->
</TabItem>
</Tabs>

If using `jsonb` consider adding a [gin index] for fast key-value pair searchability within `image_data`.

Now you can create an uploader class for the type of files you want to upload,
and add a virtual attribute for handling attachments using this uploader to
Expand All @@ -69,60 +79,79 @@ class ImageUploader < Shrine
# plugins and uploading logic
end
```
<!--DOCUSAURUS_CODE_TABS-->
<!--Sequel-->

<Tabs>
<TabItem value="sequel" label="Sequel">

```rb
class Photo < Sequel::Model
include ImageUploader::Attachment(:image) # adds an `image` virtual attribute
end
```
<!--ActiveRecord-->

</TabItem>
<TabItem value="activerecord" label="Active Record">

```rb
class Photo < ActiveRecord::Base
include ImageUploader::Attachment(:image) # adds an `image` virtual attribute
end
```
<!--END_DOCUSAURUS_CODE_TABS-->

</TabItem>
</Tabs>

Let's now add the form fields which will use this virtual attribute (NOT the
`<attachment>_data` column attribute). We need (1) a file field for choosing
files, and (2) a hidden field for retaining the uploaded file in case of
validation errors and for potential [direct uploads].

<!--DOCUSAURUS_CODE_TABS-->
<!--Rails form builder-->
<Tabs>
<TabItem value="rails" label="Rails form builder">

```rb
form_for @photo do |f|
f.hidden_field :image, value: @photo.cached_image_data, id: nil
f.file_field :image
f.submit
end
```
<!--Simple Form-->

</TabItem>
<TabItem value="simple_form" label="Simple Form">

```rb
simple_form_for @photo do |f|
f.input :image, as: :hidden, input_html: { value: @photo.cached_image_data }
f.input :image, as: :file
f.button :submit
end
```
<!--Forme-->

</TabItem>
<TabItem value="form" label="Forme">

```rb
form @photo, action: "/photos", enctype: "multipart/form-data" do |f|
f.input :image, type: :hidden, value: @photo.cached_image_data
f.input :image, type: :file
f.button "Create"
end
```
<!--HTML-->

</TabItem>
<TabItem value="html" label="HTML">

```erb
<form action="/photos" method="post" enctype="multipart/form-data">
<input name="photo[image]" type="hidden" value="<%= @photo.cached_image_data %>" />
<input name="photo[image] "type="file" />
<input type="submit" value="Create" />
</form>
```
<!--END_DOCUSAURUS_CODE_TABS-->

</TabItem>
</Tabs>

Note that the file field needs to go *after* the hidden field, so that
selecting a new file can always override the cached file in the hidden field.
Expand All @@ -133,8 +162,9 @@ will automatically generate this for you).
When the form is submitted, in your router/controller you can assign the file
from request params to the attachment attribute on the model.

<!--DOCUSAURUS_CODE_TABS-->
<!--Rails-->
<Tabs>
<TabItem value="rails" label="Rails">

```rb
class PhotosController < ApplicationController
def create
Expand All @@ -149,28 +179,39 @@ class PhotosController < ApplicationController
end
end
```
<!--Sinatra-->

</TabItem>
<TabItem value="sinatra" label="Sinatra">

```rb
post "/photos" do
Photo.create(params[:photo])
# ...
end
```
<!--END_DOCUSAURUS_CODE_TABS-->

</TabItem>
</Tabs>

Once a file is uploaded and attached to the record, you can retrieve a URL to
the uploaded file with `#<attachment>_url` and display it on the page:

<!--DOCUSAURUS_CODE_TABS-->
<!--Rails-->
<Tabs>
<TabItem value="rails" label="Rails">

```erb
<%= image_tag @photo.image_url %>
```
<!--HTML-->

</TabItem>
<TabItem value="html" label="HTML">

```erb
<img src="<%= @photo.image_url %>" />
```
<!--END_DOCUSAURUS_CODE_TABS-->

</TabItem>
</Tabs>

## Storage

Expand Down
77 changes: 56 additions & 21 deletions doc/multiple_files.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,9 @@ id: multiple-files
title: Multiple Files
---

import Tabs from '@theme/Tabs';
import TabItem from '@theme/TabItem';

There are times when you want to allow users to attach multiple files to a
single resource, like an album having many photos or a playlist having many
songs. Some file attachment libraries provide a special interface for multiple
Expand Down Expand Up @@ -67,8 +70,9 @@ files (or attachments) table will be the photos table.
Let's create a table for the main resource and attachments, and add a foreign
key in the attachment table for the main table:

<!--DOCUSAURUS_CODE_TABS-->
<!--Sequel-->
<Tabs>
<TabItem value="sequel" label="Sequel">

```rb
Sequel.migration do
change do
Expand All @@ -87,7 +91,10 @@ Sequel.migration do
end
end
```
<!--ActiveRecord-->

</TabItem>
<TabItem value="activerecord" label="Active Record">

```rb
class CreateAlbumsAndPhotos < ActiveRecord::Migration
def change
Expand All @@ -104,25 +111,33 @@ class CreateAlbumsAndPhotos < ActiveRecord::Migration
end
end
```
<!--END_DOCUSAURUS_CODE_TABS-->

</TabItem>
</Tabs>

In the Photo model, create a Shrine attachment attribute named `image`
(`:image` matches the `_data` column prefix above):

<!--DOCUSAURUS_CODE_TABS-->
<!--Sequel-->
<Tabs>
<TabItem value="sequel" label="Sequel">

```rb
class Photo < Sequel::Model
include ImageUploader::Attachment(:image)
end
```
<!--ActiveRecord-->

</TabItem>
<TabItem value="activerecord" label="Active Record">

```rb
class Photo < ActiveRecord::Base
include ImageUploader::Attachment(:image)
end
```
<!--END_DOCUSAURUS_CODE_TABS-->

</TabItem>
</Tabs>

### 2. Declare nested attributes

Expand All @@ -131,8 +146,9 @@ Using nested attributes is the easiest way to implement any dynamic
relationship to the photos table, and allow it to directly accept attributes
for the associated photo records by enabling nested attributes:

<!--DOCUSAURUS_CODE_TABS-->
<!--Sequel-->
<Tabs>
<TabItem value="sequel" label="Sequel">

```rb
class Album < Sequel::Model
one_to_many :photos
Expand All @@ -142,22 +158,30 @@ class Album < Sequel::Model
nested_attributes :photos, destroy: true
end
```
<!--ActiveRecord-->

</TabItem>
<TabItem value="activerecord" label="Active Record">

```rb
class Album < ActiveRecord::Base
has_many :photos, dependent: :destroy
accepts_nested_attributes_for :photos, allow_destroy: true
end
```
<!--Mongoid-->

</TabItem>
<TabItem value="mongoid" label="Mongoid">

```rb
class Album
include Mongoid::Document
embeds_many :photos
accepts_nested_attributes_for :photos
end
```
<!--END_DOCUSAURUS_CODE_TABS-->

</TabItem>
</Tabs>

Documentation on nested attributes:

Expand All @@ -174,8 +198,9 @@ already created photos, so that the same form can be used for updating the
album/photos as well (they will be submitted under the
`album[photos_attributes]` parameter).

<!--DOCUSAURUS_CODE_TABS-->
<!--Rails form builder-->
<Tabs>
<TabItem value="rails" label="Rails form builder">

```rb
form_for @album, html: { enctype: "multipart/form-data" } do |f|
f.text_field :title
Expand All @@ -188,7 +213,10 @@ form_for @album, html: { enctype: "multipart/form-data" } do |f|
f.submit "Create"
end
```
<!--Forme-->

</TabItem>
<TabItem value="forme" label="Forme">

```rb
form @album, action: "/photos", enctype: "multipart/form-data" do |f|
f.input :title
Expand All @@ -201,7 +229,9 @@ form @album, action: "/photos", enctype: "multipart/form-data" do |f|
f.button "Create"
end
```
<!--END_DOCUSAURUS_CODE_TABS-->

</TabItem>
</Tabs>

In your controller you should still be able to assign all the attributes to the
album, just remember to whitelist the new parameter for the nested attributes,
Expand Down Expand Up @@ -286,21 +316,26 @@ class ImageUploader < Shrine
end
end
```
<!--DOCUSAURUS_CODE_TABS-->
<!--Sequel-->
<Tabs>
<TabItem value="sequel" label="Sequel">

```rb
class Album < Sequel::Model
# ... (nested_attributes already enables validating associated photos) ...
end
```
<!--ActiveRecord-->

</TabItem>
<TabItem value="activerecord" label="Active Record">

```rb
class Album < ActiveRecord::Base
# ...
validates_associated :photos
end
```
<!--END_DOCUSAURUS_CODE_TABS-->
</TabItem>
</Tabs>

Note that by default only metadata set on the client side will be available for
validations. Shrine will not automatically run metadata extraction for directly
Expand Down
Loading

0 comments on commit fa5e0c5

Please sign in to comment.