paperclip
Version 6.1.0
Penjepit kertas sudah tidak digunakan lagi .
Untuk proyek baru, kami merekomendasikan ActiveStorage milik Rails.
Untuk proyek yang sudah ada, silakan berkonsultasi dan berkontribusi pada panduan migrasi, tersedia dalam bahasa Inggris, en español, dan dalam bentuk video yang direkam di RailsConf 2019. Anda mungkin juga lebih memilih tutorial migrasi alternatif yang digunakan oleh Doorkeeper.
Sebagai alternatif, untuk proyek yang sudah ada, Kreeti mempertahankan kt-paperclip, sebuah cabang dari Paperclip yang sedang berjalan.
Kami akan membiarkan Masalah ini terbuka sebagai forum diskusi saja . Kami tidak menjamin tanggapan dari kami dalam Masalah ini. Semua laporan bug harus dikirim ke kt-paperclip.
Kami tidak lagi menerima permintaan penarikan kecuali permintaan penarikan yang bertentangan dengan panduan migrasi. Semua permintaan penarikan lainnya akan ditutup tanpa penggabungan.
masterSilakan periksa dokumentasi untuk versi penjepit kertas yang Anda gunakan: https://github.com/thinkbot/paperclip/releases
Persyaratan
Ruby dan Rel
Pemroses Gambar
file
Instalasi
Mulai Cepat
Model
Migrasi
Edit dan Tampilan Baru
Edit dan Tampilan Baru dengan Bentuk Sederhana
Pengendali
Lihat Pembantu
Memeriksa File yang Ada
Menghapus Lampiran
Penggunaan
Validasi
Internasionalisasi (I18n)
Validasi Keamanan
Default
Migrasi
Tambahkan Kolom Lampiran Ke Tabel
Definisi Skema
Sintaks Antik
Penyimpanan
Memahami Penyimpanan
Adaptor IO
Pasca Pemrosesan
Prosesor Lampiran Khusus
Acara
Kebingungan URI
Checksum / Sidik Jari
Pelestarian File untuk Soft-Delete
Konfigurasi Dinamis
Gaya Dinamis:
Prosesor Dinamis:
Pencatatan
Penyebaran
Gaya Lampiran
Pengujian
Berkontribusi
Lisensi
Tentang bot pemikiran
Penjepit Kertas dimaksudkan sebagai perpustakaan lampiran file yang mudah untuk ActiveRecord. Maksud di baliknya adalah untuk menjaga pengaturan semudah mungkin dan memperlakukan file seperti atribut lainnya. Artinya, data tersebut tidak disimpan ke lokasi akhirnya di disk, juga tidak dihapus jika disetel ke nihil, hingga ActiveRecord::Base#save dipanggil. Ia mengelola validasi berdasarkan ukuran dan kehadiran, jika diperlukan. Ia dapat mengubah gambar yang ditugaskan menjadi thumbnail jika diperlukan, dan prasyaratnya semudah menginstal ImageMagick (yang, untuk sebagian besar sistem berbasis Unix modern, semudah menginstal paket yang tepat). File terlampir disimpan ke sistem file dan direferensikan di browser dengan spesifikasi yang mudah dimengerti, yang memiliki default yang masuk akal dan berguna.
Lihat dokumentasi has_attached_file di Paperclip::ClassMethods untuk opsi lebih detail.
RDoc lengkap sedang online.
Paperclip sekarang memerlukan Ruby versi >= 2.1 dan Rails versi >= 4.2 (hanya jika Anda akan menggunakan Paperclip dengan Ruby on Rails).
ImageMagick harus diinstal dan Paperclip harus memiliki akses ke sana. Untuk memastikannya, pada baris perintah Anda, jalankan which convert (salah satu utilitas ImageMagick). Ini akan memberi Anda jalur di mana utilitas tersebut diinstal. Misalnya, mungkin mengembalikan /usr/local/bin/convert .
Kemudian, di file konfigurasi lingkungan Anda, beri tahu Paperclip untuk mencari di sana dengan menambahkan direktori tersebut ke jalurnya.
Dalam mode pengembangan, Anda dapat menambahkan baris ini ke config/environments/development.rb) :
Penjepit Kertas.options[:command_path] = "/usr/local/bin/"
Jika Anda menggunakan Mac OS X, Anda dapat menjalankan perintah berikut dengan Homebrew:
brew install imagemagick
Jika Anda berurusan dengan unggahan pdf atau menjalankan rangkaian pengujian, Anda juga perlu menginstal GhostScript. Di Mac OS X, Anda juga dapat menginstalnya menggunakan Homebrew:
brew install gs
Jika Anda menggunakan Ubuntu (atau distribusi Linux berbasis Debian apa pun), Anda dapat menjalankan perintah berikut dengan apt-get:
sudo apt-get install imagemagick -y
file Perintah file Unix diperlukan untuk pemeriksaan tipe konten. Utilitas ini tidak tersedia di Windows, tetapi dibundel dengan Ruby Devkit, jadi pengguna Windows harus memastikan bahwa devkit diinstal dan ditambahkan ke sistem PATH .
Instalasi Manual
Jika Anda menggunakan Windows 7+ sebagai lingkungan pengembangan, Anda mungkin perlu menginstal aplikasi file.exe secara manual. Sistem file spoofing di Paperclip 4+ bergantung pada ini; jika tidak berfungsi, Anda akan menerima Validation failed: Upload file has an extension that does not match its contents. kesalahan.
Untuk menginstal secara manual, Anda harus melakukan hal berikut:
Unduh & instal
filedari URL ini
Untuk mengujinya, Anda dapat menggunakan gambar di bawah ini:
Selanjutnya, Anda perlu berintegrasi dengan lingkungan Anda - sebaiknya melalui variabel PATH , atau dengan mengubah file config/environments/development.rb Anda
JALUR
1. Click "Start" 2. On "Computer", right-click and select "Properties" 3. In Properties, select "Advanced System Settings" 4. Click the "Environment Variables" button 5. Locate the "PATH" var - at the end, add the path to your newly installed `file.exe` (typically `C:Program Files (x86)GnuWin32bin`) 6. Restart any CMD shells you have open & see if it works
ATAU
Lingkungan
1. Open `config/environments/development.rb` 2. Add the following line: `Paperclip.options[:command_path] = 'C:Program Files (x86)GnuWin32bin'` 3. Restart your Rails server
Salah satu dari metode ini akan memberikan akses pengaturan Rails Anda ke fungsionalitas file.exe , sehingga memberikan kemampuan untuk memeriksa konten file (memperbaiki masalah spoofing)
Penjepit Kertas didistribusikan sebagai permata, begitulah seharusnya digunakan di aplikasi Anda.
Sertakan permata di Gemfile Anda:
permata "penjepit kertas", "~> 6.0.0"
Atau, jika Anda ingin mendapatkan yang terbaru, Anda bisa mendapatkan master dari repositori utama penjepit kertas:
permata "penjepit kertas", git: "git://github.com/thinkbot/paperclip.git"
Jika Anda mencoba menggunakan fitur yang tampaknya tidak ada dalam permata terbaru yang dirilis, namun disebutkan dalam README ini, maka Anda mungkin perlu menentukan cabang master jika ingin menggunakannya. README ini mungkin lebih awal dari versi rilis terbaru jika Anda membacanya di GitHub.
Untuk penggunaan Non-Rail:
kelas ModuleName < ActiveRecord::Base termasuk Penjepit Kertas::Lem ...akhir
kelas Pengguna < ActiveRecord::Base has_attached_file :avatar, gaya: { medium: "300x300>", ibu jari: "100x100>" }, default_url: "/images/:style/missing.png" validasi_attachment_content_type :avatar, content_type: / Gambar/.*z/end Dengan asumsi Anda memiliki tabel users , tambahkan kolom avatar ke tabel users :
kelas AddAvatarColumnsToUsers < ActiveRecord::Migrasi def up add_attachment :pengguna, :avatar end def down delete_attachment :pengguna, :avatar endend
(Atau Anda dapat menggunakan generator migrasi Rails: rails generate paperclip user avatar )
Pastikan Anda memiliki metode yang sesuai di pengontrol Anda:
<%= form_for @pengguna, url: jalur_pengguna, html: { multibagian: benar } lakukan |form| %> <%= form.file_field :avatar %> <%= form.kirim %><% end %><%= simple_form_for @user, url: jalur_pengguna melakukan |form| %> <%= form.input :avatar, sebagai: :file %> <%= form.submit %><% end %>
def create @user = User.create(user_params)endprivate# Gunakan strong_parameters untuk memasukkan atribut ke daftar putih# Pastikan untuk memperbarui metode pengontrol create() dan update() Anda.def user_params params.require(:user).permit(:avatar)end
Tambahkan ini ke tampilan tempat Anda ingin gambar Anda ditampilkan:
<%= image_tag @pengguna.avatar.url %><%= image_tag @pengguna.avatar.url(:medium) %><%= image_tag @pengguna.avatar.url(:ibu jari) %>
Ada dua metode untuk memeriksa apakah suatu file ada:
file? dan present? memeriksa apakah bidang _file_name terisi
exists? memeriksa apakah file tersebut ada (akan melakukan koneksi TCP jika disimpan di cloud)
Ingatlah hal ini jika Anda memeriksa apakah ada file dalam satu lingkaran. Versi pertama secara signifikan lebih berperforma, tetapi memiliki semantik yang berbeda.
Atur atribut ke nil dan simpan.
@pengguna.avatar = [email protected]
Dasar-dasar Paperclip cukup sederhana: Nyatakan bahwa model Anda memiliki lampiran dengan metode has_attached_file , dan beri nama.
Penjepit Kertas akan membungkus hingga empat atribut (semua diawali dengan nama lampiran tersebut, sehingga Anda dapat memiliki beberapa lampiran per model jika diinginkan) dan memberikan tampilan depan yang ramah. Atribut-atribut tersebut adalah:
<attachment>_file_name
<attachment>_file_size
<attachment>_content_type
<attachment>_updated_at
Secara default, hanya <attachment>_file_name yang diperlukan agar Penjepit Kertas dapat beroperasi. Anda harus menambahkan <attachment>_content_type jika Anda ingin menggunakan validasi tipe konten.
Informasi lebih lanjut tentang opsi yang diteruskan ke has_attached_file tersedia di dokumentasi Paperclip::ClassMethods .
Untuk validasi, Paperclip memperkenalkan beberapa validator untuk memvalidasi lampiran Anda:
AttachmentContentTypeValidator
AttachmentPresenceValidator
AttachmentSizeValidator
Contoh Penggunaan:
memvalidasi :avatar, attachment_presence: truevalidates_with AttachmentPresenceValidator, atribut: :avatarvalidates_with AttachmentSizeValidator, atribut: :avatar, less_than: 1.megabytes
Validator juga dapat ditentukan menggunakan gaya pembantu lama:
validates_attachment_presence
validates_attachment_content_type
validates_attachment_size
Contoh Penggunaan:
validasi_attachment_presence :avatar
Terakhir, Anda juga dapat menentukan beberapa validasi pada satu lampiran menggunakan validates_attachment :
validasi_attachment :avatar, kehadiran: true, content_type: "image/jpeg", ukuran: { dalam: 0..10.kilobytes }CATATAN: Pasca-pemrosesan bahkan tidak akan dimulai jika lampiran tidak valid menurut validasi. Callback dan prosesor Anda hanya akan dipanggil dengan lampiran yang valid.
pesan kelas < ActiveRecord::Base has_attached_file :aset, gaya: { ibu jari: "100x100#" } before_post_process :skip_for_audio def skip_for_audio
! %w(audio/ogg application/ogg).include?(asset_content_type) akhirJika Anda memiliki validasi lain yang bergantung pada urutan penetapan, tindakan yang disarankan adalah mencegah penetapan lampiran hingga setelahnya, lalu tetapkan secara manual:
class Book < ActiveRecord::Base has_attached_file :document, style: { thumbnail: "60x60#" } validasi_attachment :document, content_type: "application/pdf" validasi_something_else # Validasi lain yang bertentangan dengan Paperclip'sendclass BooksController < ApplicationController def create @book = Buku.baru(book_params) @buku.dokumen = params[:book][:document] @book.save respond_with @book end private def book_params params.require(:book).permit(:title, :author) endendCatatan tentang validasi dan keamanan content_type
Anda harus memastikan bahwa Anda memvalidasi file hanya menjadi tipe MIME yang ingin Anda dukung secara eksplisit. Jika tidak, Anda bisa terkena serangan XSS jika pengguna mengunggah file dengan muatan HTML berbahaya.
Jika Anda hanya tertarik pada gambar, batasi content_types yang diizinkan hanya pada gambar:
validasi_attachment :avatar, content_type: ["gambar/jpeg", "gambar/gif", "gambar/png"]
Paperclip::ContentTypeDetector akan mencoba mencocokkan ekstensi file dengan tipe_konten yang disimpulkan, terlepas dari konten sebenarnya dari file tersebut.
Untuk menggunakan atau menambahkan file lokal dalam berbagai bahasa, periksa proyek https://github.com/thinkbot/paperclip-i18n.
Berkat laporan dari Egor Homakov kami telah mengambil langkah-langkah untuk mencegah orang melakukan spoofing Tipe Konten dan memasukkan data yang tidak Anda harapkan ke server Anda.
CATATAN: Mulai versi 4.0.0, semua lampiran harus menyertakan validasi tipe_konten, validasi nama_file, atau secara eksplisit menyatakan bahwa mereka tidak akan memiliki keduanya. Penjepit Kertas akan memunculkan kesalahan jika Anda tidak melakukan ini.
class ActiveRecord::Base has_attached_file :avatar # Validasi tipe konten validasi_attachment_content_type :avatar, content_type: /Aimage/ # Validasi nama file validasi_attachment_file_name :avatar, cocok: [/pngz/, /jpe?gz/] # Secara eksplisit jangan validasi do_not_validate_attachment_file_type :avatarend
Hal ini membuat Paperclip tetap aman secara default, dan akan mencegah orang mencoba mengacaukan sistem file Anda.
CATATAN: Juga mulai versi 4.0.0, Penjepit Kertas memiliki validasi lain yang tidak dapat dimatikan. Validasi ini akan mencegah spoofing tipe konten. Artinya, mengunggah dokumen PHP (misalnya) sebagai bagian dari tag EXIF dari JPEG yang dibuat dengan baik. Pemeriksaan ini terbatas pada tipe media (bagian pertama dari tipe MIME, jadi, 'text' dalam text/plain ). Ini akan mencegah dokumen HTML diunggah sebagai JPEG, namun tidak akan mencegah GIF diunggah dengan ekstensi .jpg . Validasi ini hanya akan menambah kesalahan validasi pada formulir. Itu tidak akan menyebabkan kesalahan dimunculkan.
Hal ini terkadang dapat menyebabkan kesalahan validasi palsu pada aplikasi yang menggunakan ekstensi file khusus. Dalam kasus ini Anda mungkin ingin menambahkan ekstensi khusus Anda ke daftar pemetaan tipe konten dengan membuat config/initializers/paperclip.rb :
# Izinkan ".foo" sebagai ekstensi untuk file dengan tipe MIME "text/plain".Paperclip.options[:content_type_mappings] = { foo: %w(text/plain)} Default global untuk semua lampiran Paperclip Anda dapat ditentukan dengan mengubah Hash Paperclip::Attachment.default_options. Ini bisa berguna untuk mengatur pengaturan penyimpanan default Anda per contoh sehingga Anda tidak perlu mendefinisikannya di setiap definisi has_attached_file .
Jika Anda menggunakan Rails, Anda dapat menentukan Hash dengan opsi default di config/application.rb atau di file config/environments/*.rb mana pun di config.paperclip_defaults. Ini akan digabungkan ke dalam Paperclip::Attachment.default_options saat aplikasi Rails Anda melakukan booting. Contoh:
modul Aplikasi Kelas Aplikasi Anda < Rails::Aplikasi # Kode lain... config.paperclip_defaults = { penyimpanan: :fog, fog_credentials: { penyedia: "Lokal", local_root: "#{Rails.root}/public"}, fog_directory: "", fog_host: "localhost"} berakhir Pilihan lainnya adalah dengan langsung memodifikasi Hash Paperclip::Attachment.default_options - metode ini berfungsi untuk aplikasi non-Rails atau merupakan opsi jika Anda lebih suka menempatkan pengaturan default Paperclip di penginisialisasi.
Contoh penginisialisasi Rails akan terlihat seperti ini:
Penjepit Kertas::Lampiran.default_options[:penyimpanan] = :fogPaperclip::Attachment.default_options[:fog_credentials] = { penyedia: "Lokal", local_root: "#{Rails.root}/public"}Penjepit Kertas::Lampiran.default_options[ :direktori_kabut] = ""Penjepit Kertas::Attachment.default_options[:fog_host] = "http://localhost:3000"Penjepit Kertas mendefinisikan beberapa metode migrasi yang dapat digunakan untuk membuat kolom yang diperlukan dalam model Anda. Ada dua jenis metode pembantu untuk membantu hal ini, sebagai berikut:
Pembantu attachment dapat digunakan saat membuat tabel:
class CreateUsersWithAttachments < ActiveRecord::Migrasi def up create_table :pengguna melakukan |t| t.attachment :avatar end end # Ini dengan asumsi Anda hanya menggunakan tabel pengguna untuk lampiran Paperclip. Jatuhkan dengan hati-hati! def down drop_table : pengguna akhir
Anda juga dapat menggunakan metode change , sebagai pengganti kombinasi up / down di atas, seperti yang ditunjukkan di bawah ini:
kelas CreateUsersWithAttachments < ActiveRecord::Migrasi pasti berubah create_table :pengguna melakukan |t| t.attachment : akhir avatar
Alternatifnya, metode add_attachment dan remove_attachment dapat digunakan untuk menambahkan kolom Paperclip baru ke tabel yang sudah ada:
kelas AddAttachmentColumnsToUsers < ActiveRecord::Migrasi def up add_attachment :pengguna, :avatar end def down delete_attachment :pengguna, :avatar endend
Atau Anda dapat melakukannya dengan metode change :
kelas AddAttachmentColumnsToUsers < ActiveRecord::Migrasi pasti berubah add_attachment :pengguna, :avatar endend
Sintaks vintage (seperti t.has_attached_file dan drop_attached_file ) masih didukung di Paperclip 3.x, namun Anda disarankan untuk memperbarui file migrasi tersebut untuk menggunakan sintaksis baru ini.
Penjepit Kertas dikirimkan dengan 3 adaptor penyimpanan:
Penyimpanan Berkas
Penyimpanan S3 (melalui aws-sdk-s3 )
Penyimpanan Kabut
Jika Anda ingin menggunakan Penjepit Kertas dengan penyimpanan lain, Anda dapat memasang permata ini bersama dengan Penjepit Kertas:
penjepit kertas-biru
penyimpanan-penjepit kertas-biru
penjepit kertas-dropbox
File yang ditetapkan sebagai lampiran, secara default, ditempatkan di direktori yang ditentukan oleh opsi :path ke has_attached_file . Secara default, lokasi ini adalah :rails_root/public/system/:class/:attachment/:id_partition/:style/:filename . Lokasi ini dipilih karena, pada penerapan Capistrano standar, direktori public/system dapat disinkronkan ke direktori bersama aplikasi, yang berarti direktori tersebut tetap bertahan di antara penerapan. Misalnya, dengan menggunakan :path , Anda mungkin memiliki file di
/data/myapp/releases/20081229172410/public/system/users/avatar/000/000/013/small/my_pic.png
CATATAN : Ini merupakan perubahan dari versi Paperclip sebelumnya, namun secara keseluruhan merupakan pilihan yang lebih aman untuk penyimpanan file default.
Anda juga dapat memilih untuk menyimpan file Anda menggunakan layanan S3 Amazon. Untuk melakukannya, sertakan permata aws-sdk-s3 di Gemfile Anda:
permata 'aws-sdk-s3'
Dan kemudian Anda dapat menentukan menggunakan S3 dari has_attached_file . Anda dapat menemukan informasi selengkapnya tentang mengonfigurasi dan menggunakan penyimpanan S3 di dokumentasi Paperclip::Storage::S3 .
File di sistem file lokal (dan di direktori publik aplikasi Rails) akan tersedia di internet secara luas. Jika Anda memerlukan kontrol akses, Anda dapat menempatkan file Anda di lokasi yang berbeda. Anda perlu mengubah opsi :path dan :url untuk memastikan file tidak tersedia untuk umum. Baik :path dan :url mengizinkan kumpulan variabel interpolasi yang sama.
Ketika sebuah file diunggah atau dilampirkan, itu bisa dalam salah satu dari beberapa bentuk input yang berbeda, dari objek UploadedFile Rails ke StringIO ke Tempfile atau bahkan String sederhana yang merupakan URL yang menunjuk ke sebuah gambar.
Penjepit Kertas akan menerima, secara default, banyak dari sumber-sumber ini. Ia juga mampu menangani lebih banyak lagi dengan sedikit konfigurasi. Adaptor IO yang menangani gambar dari sumber non-lokal tidak diaktifkan secara default. Mereka dapat diaktifkan dengan menambahkan baris yang mirip dengan berikut ke config/initializers/paperclip.rb :
Penjepit Kertas::DataUriAdapter.register
Sebaiknya aktifkan adaptor pemuatan jarak jauh hanya jika Anda membutuhkannya. Jika tidak, ada kemungkinan seseorang dapat memperoleh wawasan tentang struktur jaringan internal Anda dengan menggunakannya sebagai vektor.
Adaptor berikut tidak dimuat secara default:
Paperclip::UriAdapter - yang menerima instance URI .
Paperclip::HttpUrlProxyAdapter - yang menerima string http .
Paperclip::DataUriAdapter - yang menerima data: string yang dikodekan Base64.
Penjepit Kertas mendukung pilihan pasca-prosesor yang dapat diperluas. Saat Anda menentukan sekumpulan gaya untuk lampiran, secara default diharapkan "gaya" tersebut sebenarnya adalah "thumbnail". Ini diproses oleh Paperclip::Thumbnail . Untuk alasan kompatibilitas mundur, Anda dapat meneruskan string geometri tunggal, atau larik yang berisi geometri dan format file yang akan dikonversi, seperti:
has_attached_file :avatar, gaya: { ibu jari: ["32x32#", :png] } Ini akan mengonversi gaya "jempol" menjadi persegi berukuran 32x32 dalam format PNG, apa pun yang diunggah. Jika formatnya tidak ditentukan, formatnya akan tetap sama (misalnya JPG akan tetap JPG). Paperclip::Thumbnail menggunakan ImageMagick untuk memproses gambar; Dokumentasi geometri ImageMagick memiliki lebih banyak informasi tentang format gaya yang diterima.
Untuk kontrol proses konversi yang lebih detail, source_file_options dan convert_options dapat digunakan untuk meneruskan tanda dan pengaturan langsung ke alat Konversi ImageMagick yang canggih, yang didokumentasikan di sini. Misalnya:
has_attached_file :gambar, gaya: { reguler: ['800x800>', :png]},
source_file_options: { reguler: "-densitas 96 -kedalaman 8 -kualitas 85" }, convert_options: { reguler: "-posterize 3"}ImageMagick mendukung sejumlah variabel lingkungan untuk mengendalikan batas sumber dayanya. Misalnya, Anda dapat menerapkan batas waktu memori atau eksekusi dengan mengatur variabel berikut di lingkungan proses aplikasi Anda:
MAGICK_MEMORY_LIMIT=128MiB
MAGICK_MAP_LIMIT=64MiB
MAGICK_TIME_LIMIT=30
Untuk daftar lengkap variabel dan deskripsi, lihat dokumentasi sumber daya ImageMagick.
Anda dapat menulis pemroses lampiran khusus Anda sendiri untuk melakukan tugas seperti menambahkan tanda air, mengompresi gambar, atau mengenkripsi file. Prosesor khusus harus ditentukan dalam modul Paperclip , mewarisi dari Paperclip::Processor (lihat lib/paperclip/processor.rb ), dan mengimplementasikan metode make yang mengembalikan File . Semua file di direktori lib/paperclip dan lib/paperclip_processors aplikasi Rails Anda akan dimuat secara otomatis oleh Paperclip. Prosesor ditentukan menggunakan opsi :processors ke has_attached_file :
has_attached_file :scan, gaya: { teks: { kualitas: :lebih baik } }, prosesor: [:ocr] Ini akan memuat kelas hipotetis Paperclip::Ocr , dan meneruskannya opsi hash { quality: :better } , bersama dengan file yang diunggah.
Beberapa prosesor dapat ditentukan, dan mereka akan dipanggil sesuai urutan yang ditentukan dalam :processors array. Setiap prosesor yang berurutan diberikan hasil dari prosesor sebelumnya. Semua prosesor menerima parameter yang sama, yang ditentukan dalam hash :styles . Misalnya, dengan asumsi kita memiliki definisi ini:
has_attached_file :scan, gaya: { teks: { kualitas: :lebih baik } }, prosesor: [:rotator, :ocr] Baik prosesor :rotator maupun prosesor :ocr akan menerima opsi { quality: :better } . Jika prosesor menerima opsi yang tidak dikenalinya, prosesor diharapkan mengabaikannya.
CATATAN: Karena prosesor beroperasi dengan mengubah lampiran asli menjadi gaya, tidak ada prosesor yang akan dijalankan jika tidak ada gaya yang ditentukan.
Jika Anda tertarik untuk menyimpan lebar, tinggi, dan ukuran thumbnail Anda di database, lihat permata paperclip-meta.
Selain itu, jika Anda tertarik untuk membuat thumbnail saat itu juga, Anda mungkin ingin melihat permata attachment_on_the_fly.
Generator thumbnail Paperclip (lihat lib/paperclip/thumbnail.rb ) diimplementasikan sebagai prosesor, dan mungkin merupakan referensi yang baik untuk menulis prosesor Anda sendiri.
Sebelum dan sesudah langkah Pasca Pemrosesan, Penjepit Kertas memanggil kembali model dengan beberapa panggilan balik, sehingga model dapat mengubah atau membatalkan langkah pemrosesan. Callbacknya adalah before_post_process dan after_post_process (yang dipanggil sebelum dan sesudah pemrosesan setiap lampiran), dan khusus lampiran before_<attachment>_post_process dan after_<attachment>_post_process . Callback dimaksudkan agar sedekat mungkin dengan callback ActiveRecord normal, jadi jika Anda mengembalikan false (khususnya - mengembalikan nil tidak sama) dalam before_filter , langkah pemrosesan postingan akan terhenti. Mengembalikan false di after_filter tidak akan menghentikan apa pun, tetapi Anda dapat mengakses model dan lampirannya jika perlu.
CATATAN: Pemrosesan pasca bahkan tidak akan dimulai jika lampiran tidak valid sesuai validasi. Callback dan prosesor Anda hanya akan dipanggil dengan lampiran yang valid.
pesan kelas < ActiveRecord::Base has_attached_file :aset, gaya: { ibu jari: "100x100#" } before_post_process :skip_for_audio def skip_for_audio
! %w(audio/ogg application/ogg).include?(asset_content_type) akhir Paperclip memiliki interpolasi yang disebut :hash untuk mengaburkan nama file dari file yang tersedia untuk umum.
Contoh Penggunaan:
has_attached_file :avatar, { url: "/system/:hash.:extension", hash_secret: "longSecretString"} Interpolasi :hash akan diganti dengan hash unik yang terdiri dari apa pun yang ditentukan dalam :hash_data . Nilai default untuk :hash_data adalah ":class/:attachment/:id/:style/:updated_at" .
:hash_secret diperlukan - pengecualian akan dimunculkan jika :hash digunakan tanpa kehadiran :hash_secret .
Untuk lebih lanjut mengenai fitur ini, bacalah penjelasan penulis sendiri
Checksum dari file asli yang ditetapkan akan ditempatkan dalam model jika memiliki atribut bernama sidik jari. Mengikuti contoh migrasi model pengguna di atas, migrasi akan terlihat seperti berikut:
kelas AddAvatarFingerprintColumnToUser < ActiveRecord::Migrasi def up add_column :users, :avatar_fingerprint, :string end def down delete_column :users, :avatar_fingerprint endend
Algoritme dapat ditentukan menggunakan opsi konfigurasi; defaultnya adalah MD5 untuk kompatibilitas dengan Paperclip 5 dan versi lebih lama.
has_attached_file :some_attachment, adapter_options: { hash_digest: Intisari::SHA256 } Jalankan CLASS=User ATTACHMENT=avatar rake paperclip:refresh:fingerprints setelah mengubah intisari pada lampiran yang ada untuk memperbarui sidik jari di database.
Tersedia opsi untuk menyimpan lampiran agar dapat berfungsi dengan baik dengan model yang dihapus sementara. (acts_as_paranoid, paranoia, dll.)
has_attached_file :some_attachment, { melestarikan_files: benar,} Ini akan mencegah some_attachment dihapus ketika model dihancurkan, sehingga model tersebut akan tetap ada ketika objek dipulihkan nanti.
Objek yang dapat dipanggil (lambdas, Procs) dapat digunakan di sejumlah tempat untuk konfigurasi dinamis di seluruh Penjepit Kertas. Strategi ini ada di sejumlah komponen perpustakaan, tetapi yang paling signifikan adalah kemungkinan mengizinkan gaya dan pemroses khusus diterapkan untuk contoh model tertentu, daripada menerapkan gaya dan pemroses yang ditentukan di semua contoh.
Bayangkan model pengguna yang memiliki gaya berbeda berdasarkan peran pengguna. Mungkin beberapa pengguna adalah bos (misalnya contoh model Pengguna merespons #boss? ) dan pantas mendapatkan thumbnail avatar yang lebih besar daripada pengguna biasa. Konfigurasi untuk menentukan parameter gaya apa yang akan digunakan berdasarkan peran pengguna mungkin terlihat sebagai berikut di mana bos akan menerima thumbnail 300x300 jika tidak, thumbnail 100x100 akan dibuat.
kelas Pengguna < ActiveRecord::Base has_attached_file :avatar, gaya: lambda { |attachment| { ibu jari: (attachment.instance.boss? ? "300x300>" : "100x100>") } }akhir Contoh lain yang dibuat-buat adalah model pengguna yang mengetahui pemroses file mana yang harus diterapkan padanya (di luar prosesor thumbnail tersirat yang dipanggil ketika :styles ditentukan). Mungkin kami memiliki prosesor tanda air dan hanya digunakan pada avatar model tertentu. Konfigurasi untuk ini mungkin adalah saat instance ditanyai prosesor mana yang harus diterapkan padanya. Agaknya beberapa pengguna mungkin mengembalikan [:thumbnail, :watermark] untuk prosesornya, di mana prosesor watermark yang ditentukan dipanggil setelah prosesor thumbnail sudah ditentukan oleh Paperclip.
kelas Pengguna < ActiveRecord::Base has_attached_file :avatar, prosesor: lambda { |instance| instance.prosesor } attr_accessor :prosesorkirimSecara default, Paperclip mengeluarkan logging sesuai dengan level logger Anda. Jika Anda ingin menonaktifkan logging (misalnya selama pengujian) tambahkan ini ke dalam konfigurasi lingkungan Anda:
Anda::Application.configure lakukan... Penjepit Kertas.options[:log] = false...end
Informasi lebih lanjut di rdocs
Untuk membuat Capistrano menghubungkan direktori public/system sehingga lampiran dapat bertahan dalam penerapan baru, setel opsi linked_dirs di file config/deploy.rb Anda:
set :linked_dirs, ambil(:linked_dirs, []).push('publik/sistem') Paperclip mengetahui gaya lampiran baru yang telah Anda tambahkan pada penerapan sebelumnya. Satu-satunya hal yang harus Anda lakukan setelah setiap penerapan adalah memanggil rake paperclip:refresh:missing_styles . Ini akan menyimpan gaya lampiran saat ini di RAILS_ROOT/public/system/paperclip_attachments.yml secara default. Anda dapat mengubahnya dengan:
Penjepit Kertas.registered_attachments_styles_path = '/tmp/config/paperclip_attachments.yml'
Berikut ini contoh untuk Capistrano:
namespace :penjepit kertas lakukan desc "buat gaya penjepit kertas yang hilang" tugas :build_missing_styles lakukan pada peran(:aplikasi) lakukan dalam jalur_rilis lakukan dengan Rails_env: ambil(:rails_env) lakukan eksekusi :rake, "penjepit kertas:refresh:missing_styles" end end end endendafter( "deploy:compile_assets", "penjepit kertas:build_missing_styles")
Sekarang Anda tidak perlu mengingat untuk menyegarkan thumbnail dalam produksi setiap kali Anda menambahkan gaya baru. Sayangnya, ini tidak berfungsi dengan gaya dinamis - ia hanya mengabaikannya.
Jika Anda sudah memiliki aplikasi yang berfungsi dan tidak ingin rake paperclip:refresh:missing_styles menyegarkan gambar lama, Anda perlu memberi tahu Paperclip tentang gaya yang ada. Cukup buat file paperclip_attachments.yml dengan tangan. Misalnya:
kelas Pengguna < ActiveRecord::Base has_attached_file :avatar, gaya: { jempol: 'x100', dapat dipotong: '600x600>', besar: '1000x1000>' }Buku kelas akhir < ActiveRecord::Base has_attached_file :cover, style: { kecil: 'x100', besar: '1000x1000>' } has_attached_file :sampel, gaya: { jempol: 'x100' }akhir Kemudian di RAILS_ROOT/public/system/paperclip_attachments.yml :
---:Pengguna: :avatar: - : jempol - :dapat dipotong - :besar:Buku: :sampul: - :kecil - :besar :contoh: - : jempol
Paperclip menyediakan pencocokan yang kompatibel dengan rspec untuk menguji lampiran. Lihat dokumentasi di Paperclip::Shoulda::Matchers untuk informasi lebih lanjut.
Tes Paralel
Karena path default untuk penyimpanan Paperclip, jika Anda mencoba menjalankan pengujian secara paralel, Anda mungkin menemukan bahwa file akan ditimpa karena jalur yang sama dihitung untuk file tersebut di setiap proses pengujian. Meskipun perbaikan ini berfungsi untuk parallel_tests, konsep serupa harus digunakan untuk mekanisme lain untuk menjalankan pengujian secara bersamaan.
if ENV['PARALLEL_TEST_GROUPS'] Penjepit Kertas::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/#{ENV['TEST_ENV_NUMBER'].to_i}/:class/:attachment/:id_partition/ :namafile"lainnya Penjepit Kertas::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/:class/:attachment/:id_partition/:filename"end Bagian penting di sini adalah penyertaan ENV['TEST_ENV_NUMBER'] , atau mekanisme serupa untuk pustaka pengujian paralel mana pun yang Anda gunakan.
Tes Integrasi
Menggunakan pengujian integrasi dengan FactoryBot dapat menyimpan banyak salinan file pengujian Anda di dalam aplikasi. Untuk menghindari hal ini, tentukan jalur khusus di config/environments/test.rb seperti:
Penjepit Kertas::Attachment.default_options[:path] = "#{Rails.root}/spec/test_files/:class/:id_partition/:style.:extension" Kemudian, pastikan untuk menghapus direktori tersebut setelah rangkaian pengujian dijalankan dengan menambahkan ini ke spec_helper.rb .
config.after(:suite) melakukan FileUtils.rm_rf(Dir["#{Rails.root}/spec/test_files/"])endContoh konfigurasi pengujian dengan Bot Pabrik
FactoryBot.define melakukan pabrik :pengguna melakukan avatar { File.new("#{Rails.root}/spec/support/fixtures/image.jpg") } akhirJika Anda ingin menyumbangkan fitur atau perbaikan bug: Terima kasih! Untuk memastikan perbaikan/fitur Anda berpeluang besar untuk disertakan, harap baca panduan berikut:
Posting permintaan tarik.
Pastikan ada tes! Kami tidak akan menerima patch apa pun yang tidak diuji. Jarang sekali tes eksplisit tidak diperlukan. Jika Anda memiliki pertanyaan tentang menulis tes untuk penjepit kertas, silakan buka terbitan GitHub.
Silakan lihat CONTRIBUTING.md untuk rincian lebih lanjut tentang kontribusi dan menjalankan tes.
Terima kasih kepada semua kontributor!
Penjepit Kertas adalah Hak Cipta © 2008-2017 thoughtbot, inc. Ini adalah perangkat lunak gratis, dan dapat didistribusikan ulang berdasarkan ketentuan yang ditentukan dalam file MIT-LICENSE.
Penjepit Kertas dikelola dan didanai oleh thinkbot. Nama dan logo untuk thinkbot adalah merek dagang dari thinkbot, inc.
Kami menyukai perangkat lunak sumber terbuka! Lihat proyek kami yang lain atau pekerjakan kami untuk merancang, mengembangkan, dan mengembangkan produk Anda.
