paperclip
Version 6.1.0
Paperclip ist veraltet .
Für neue Projekte empfehlen wir Rails eigenen ActiveStorage.
Für bestehende Projekte konsultieren Sie bitte den Migrationsleitfaden und tragen Sie dazu bei. Dieser ist auf Englisch, auf Spanisch und als auf der RailsConf 2019 aufgezeichnetes Video verfügbar. Möglicherweise bevorzugen Sie auch ein alternatives Migrations-Tutorial, das von Doorkeeper verwendet wird.
Alternativ unterhält Kreeti für bestehende Projekte kt-paperclip, eine fortlaufende Abzweigung von Paperclip.
Wir werden die Themen nur als Diskussionsforum offen lassen. Wir garantieren keine Antwort von uns auf die Probleme. Alle Fehlerberichte sollten an kt-paperclip gesendet werden.
Wir akzeptieren keine Pull-Requests mehr, außer Pull-Requests gegen den Migrationsleitfaden. Alle anderen Pull-Anfragen werden ohne Zusammenführung geschlossen.
masterBitte überprüfen Sie die Dokumentation für die von Ihnen verwendete Paperclip-Version: https://github.com/thoughtbot/paperclip/releases
Anforderungen
Ruby und Rails
Bildprozessor
file
Installation
Schnellstart
Modelle
Migrationen
Bearbeiten und neue Ansichten
Bearbeiten und neue Ansichten mit Simple Form
Regler
Helfer anzeigen
Überprüfen, ob eine Datei vorhanden ist
Einen Anhang löschen
Verwendung
Validierungen
Internationalisierung (I18n)
Sicherheitsvalidierungen
Standardeinstellungen
Migrationen
Anhangspalte zu einer Tabelle hinzufügen
Schemadefinition
Vintage-Syntax
Lagerung
Speicher verstehen
IO-Adapter
Nachbearbeitung
Benutzerdefinierte Anhangsprozessoren
Veranstaltungen
URI-Verschleierung
Prüfsumme / Fingerabdruck
Dateiaufbewahrung für Soft-Delete
Dynamische Konfiguration
Dynamische Stile:
Dynamische Prozessoren:
Protokollierung
Einsatz
Anhangsstile
Testen
Mitwirken
Lizenz
Über Thoughtbot
Paperclip ist als einfache Dateianhangsbibliothek für ActiveRecord gedacht. Die Absicht dahinter war, die Einrichtung so einfach wie möglich zu halten und Dateien möglichst wie andere Attribute zu behandeln. Dies bedeutet, dass sie nicht an ihrem endgültigen Speicherort auf der Festplatte gespeichert werden und auch nicht gelöscht werden, wenn sie auf Null gesetzt sind, bis ActiveRecord::Base#save aufgerufen wird. Bei Bedarf verwaltet es Validierungen basierend auf Größe und Präsenz. Es kann das zugewiesene Bild bei Bedarf in Miniaturansichten umwandeln und die Voraussetzungen sind so einfach wie die Installation von ImageMagick (was bei den meisten modernen Unix-basierten Systemen so einfach ist wie die Installation der richtigen Pakete). Angehängte Dateien werden im Dateisystem gespeichert und im Browser durch eine leicht verständliche Spezifikation referenziert, die über sinnvolle und nützliche Standardeinstellungen verfügt.
Ausführlichere Optionen finden Sie in der Dokumentation zu has_attached_file in Paperclip::ClassMethods .
Das komplette RDoc ist online.
Paperclip erfordert jetzt Ruby-Version >= 2.1 und Rails-Version >= 4.2 (nur wenn Sie Paperclip mit Ruby on Rails verwenden möchten).
ImageMagick muss installiert sein und Paperclip muss Zugriff darauf haben. Um sicherzustellen, dass dies der Fall ist, führen Sie in Ihrer Befehlszeile which convert aus (eines der ImageMagick-Dienstprogramme). Dadurch erhalten Sie den Pfad, in dem dieses Dienstprogramm installiert ist. Beispielsweise könnte /usr/local/bin/convert zurückgegeben werden.
Teilen Sie Paperclip dann in Ihrer Umgebungskonfigurationsdatei mit, dass es dort suchen soll, indem Sie dieses Verzeichnis zu seinem Pfad hinzufügen.
Im Entwicklungsmodus können Sie diese Zeile zu config/environments/development.rb) hinzufügen:
Paperclip.options[:command_path] = "/usr/local/bin/"
Wenn Sie Mac OS X verwenden, sollten Sie Folgendes mit Homebrew ausführen:
brew install imagemagick
Wenn Sie PDF-Uploads durchführen oder die Testsuite ausführen, müssen Sie auch GhostScript installieren. Unter Mac OS X können Sie das auch mit Homebrew installieren:
brew install gs
Wenn Sie Ubuntu (oder eine andere Debian-Basis-Linux-Distribution) verwenden, sollten Sie Folgendes mit apt-get ausführen:
sudo apt-get install imagemagick -y
file Für die Inhaltstypprüfung ist der Unix- file erforderlich. Dieses Dienstprogramm ist in Windows nicht verfügbar, wird aber im Lieferumfang von Ruby Devkit geliefert. Windows-Benutzer müssen daher sicherstellen, dass das Devkit installiert und dem Systempfad PATH hinzugefügt ist.
Manuelle Installation
Wenn Sie Windows 7+ als Entwicklungsumgebung verwenden, müssen Sie die Anwendung file.exe möglicherweise manuell installieren. Das file spoofing -System in Paperclip 4+ basiert darauf; Wenn es nicht funktioniert, erhalten Sie Validation failed: Upload file has an extension that does not match its contents. Fehler.
Zur manuellen Installation sollten Sie Folgendes durchführen:
Laden Sie
filevon dieser URL herunter und installieren Sie sie
Zum Testen können Sie das Bild unten verwenden:
Als nächstes müssen Sie die Integration in Ihre Umgebung durchführen – vorzugsweise über die PATH Variable oder durch Ändern Ihrer Datei config/environments/development.rb
WEG
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
ODER
Umfeld
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
Mit beiden Methoden erhält Ihr Rails-Setup Zugriff auf die file.exe Funktionalität und bietet so die Möglichkeit, den Inhalt einer Datei zu überprüfen (um das Spoofing-Problem zu beheben).
Paperclip wird als Edelstein verteilt und sollte daher in Ihrer App verwendet werden.
Fügen Sie den Edelstein in Ihre Gemfile ein:
gem „paperclip“, „~> 6.0.0“
Oder, wenn Sie die neueste Version erhalten möchten, können Sie den Master aus dem Hauptrepository von Paperclip herunterladen:
gem „paperclip“, git: „git://github.com/thoughtbot/paperclip.git“
Wenn Sie versuchen, Funktionen zu verwenden, die scheinbar nicht im neuesten veröffentlichten Gem enthalten sind, aber in dieser README-Datei erwähnt werden, müssen Sie wahrscheinlich den Hauptzweig angeben, wenn Sie sie verwenden möchten. Diese README-Datei ist wahrscheinlich der neuesten veröffentlichten Version voraus, wenn Sie sie auf GitHub lesen.
Für die Nutzung außerhalb der Schiene:
Klasse ModuleName < ActiveRecord::Base include Paperclip::Glue ...Ende
Klasse Benutzer < ActiveRecord::Base has_attached_file :avatar, Styles: { medium: "300x300>", Thumb: "100x100>" }, default_url: "/images/:style/missing.png" valides_attachment_content_type :avatar, content_type: / Aimage/.*z/end Angenommen, Sie haben eine users , fügen Sie der users eine avatar Spalte hinzu:
Klasse AddAvatarColumnsToUsers < ActiveRecord::Migration def up add_attachment :users, :avatar end def down remove_attachment :users, :avatar endend
(Oder Sie können den Rails-Migrationsgenerator verwenden: rails generate paperclip user avatar )
Stellen Sie sicher, dass Ihr Controller über entsprechende Methoden verfügt:
<%= form_for @user, url: users_path, html: { multipart: true } do |form| %> <%= form.file_field :avatar %> <%= form.submit %><% end %><%= simple_form_for @user, URL:user_path do |form| %> <%= form.input :avatar, as: :file %> <%= form.submit %><% end %>
def create @user = User.create(user_params)endprivate# Verwenden Sie strong_parameters für Attribut-Whitelisting# Stellen Sie sicher, dass Sie Ihre create()- und update()-Controllermethoden aktualisieren.def user_params params.require(:user).permit(:avatar)end
Fügen Sie diese der Ansicht hinzu, in der Ihre Bilder angezeigt werden sollen:
<%= image_tag @user.avatar.url %><%= image_tag @user.avatar.url(:medium) %><%= image_tag @user.avatar.url(:thumb) %>
Es gibt zwei Methoden, um zu prüfen, ob eine Datei vorhanden ist:
file? und present? prüft, ob das Feld _file_name ausgefüllt ist
exists? prüft, ob die Datei existiert (stellt eine TCP-Verbindung her, wenn sie in der Cloud gespeichert ist)
Beachten Sie dies, wenn Sie prüfen, ob Dateien in einer Schleife vorhanden sind. Die erste Version ist deutlich performanter, hat aber eine andere Semantik.
Setzen Sie das Attribut auf nil und speichern Sie.
@user.avatar = [email protected]
Die Grundlagen von Paperclip sind recht einfach: Deklarieren Sie mit der Methode has_attached_file , dass Ihr Modell einen Anhang hat, und geben Sie ihm einen Namen.
Paperclip verpackt bis zu vier Attribute (alle mit dem Namen des Anhangs vorangestellt, sodass Sie bei Bedarf mehrere Anhänge pro Modell haben können) und gibt ihnen ein benutzerfreundliches Frontend. Diese Attribute sind:
Standardmäßig ist nur
Weitere Informationen zu den an has_attached_file übergebenen Optionen finden Sie in der Dokumentation von Paperclip::ClassMethods .
Für Validierungen führt Paperclip mehrere Validatoren ein, um Ihren Anhang zu validieren:
AttachmentContentTypeValidator
AttachmentPresenceValidator
AttachmentSizeValidator
Beispielverwendung:
validiert :avatar, attachment_presence: truevalidates_with AttachmentPresenceValidator, Attribute: :avatarvalidates_with AttachmentSizeValidator, Attribute: :avatar, weniger als: 1 Megabyte
Validatoren können auch mit dem alten Hilfsstil definiert werden:
validates_attachment_presence
validates_attachment_content_type
validates_attachment_size
Beispielverwendung:
validiert_attachment_presence :avatar
Schließlich können Sie mit validates_attachment auch mehrere Validierungen für einen einzelnen Anhang definieren:
validiert_attachment: Avatar, Präsenz: wahr, Inhaltstyp: „image/jpeg“, Größe: {in: 0..10.kilobytes}HINWEIS: Die Nachbearbeitung wird nicht einmal gestartet , wenn der Anhang gemäß den Validierungen ungültig ist. Ihre Rückrufe und Bearbeiter werden nur mit gültigen Anhängen aufgerufen.
Klasse Message < ActiveRecord::Base has_attached_file :asset, Styles: { Thumb: "100x100#" } before_post_process :skip_for_audio def skip_for_audio
! %w(audio/ogg application/ogg).include?(asset_content_type) endendWenn Sie andere Validierungen haben, die von der Zuweisungsreihenfolge abhängen, besteht die empfohlene Vorgehensweise darin, die Zuweisung des Anhangs erst später zu verhindern und dann manuell zuzuweisen:
class Book < ActiveRecord::Base has_attached_file :document, Styles: { Thumbnail: "60x60#" } valides_attachment :document, content_type: "application/pdf" valides_something_else # Andere Validierungen, die mit Paperclipsendclass BooksController < ApplicationController def create @book = in Konflikt stehen Book.new(book_params) @book.document = params[:book][:document] @book.saverespond_with @book end private def book_params params.require(:book).permit(:title, :author) endendEin Hinweis zu Content-Type-Validierungen und Sicherheit
Sie sollten sicherstellen, dass Sie die Dateien nur auf die MIME-Typen validieren, die Sie ausdrücklich unterstützen möchten. Wenn Sie dies nicht tun, könnten Sie XSS-Angriffen ausgesetzt sein, wenn ein Benutzer eine Datei mit einer bösartigen HTML-Nutzlast hochlädt.
Wenn Sie nur an Bildern interessiert sind, beschränken Sie die zulässigen Inhaltstypen auf bildartige:
validiert_attachment :avatar, content_type: ["image/jpeg", "image/gif", "image/png"]
Paperclip::ContentTypeDetector versucht, die Erweiterung einer Datei einem abgeleiteten Inhaltstyp zuzuordnen, unabhängig vom tatsächlichen Inhalt der Datei.
Informationen zum Verwenden oder Hinzufügen von Gebietsschemadateien in verschiedenen Sprachen finden Sie im Projekt https://github.com/thoughtbot/paperclip-i18n.
Dank eines Berichts von Egor Homakov haben wir Maßnahmen ergriffen, um zu verhindern, dass Personen Inhaltstypen fälschen und unerwartete Daten auf Ihren Server übertragen.
HINWEIS: Ab Version 4.0.0 müssen alle Anhänge eine Content-Type-Validierung oder eine File-Name-Validierung enthalten oder explizit angeben, dass sie keines davon haben werden. Wenn Sie dies nicht tun, gibt Paperclip einen Fehler aus .
class ActiveRecord::Base has_attached_file :avatar # Inhaltstyp validieren valides_attachment_content_type :avatar, content_type: /Aimage/ # Dateinamen validieren validiert_attachment_file_name :avatar, Übereinstimmungen: [/pngz/, /jpe?gz/] # Ausdrücklich nicht tun validieren do_not_validate_attachment_file_type :avatarend
Dadurch bleibt Paperclip standardmäßig sicher und verhindert, dass Personen versuchen, Ihr Dateisystem zu manipulieren.
HINWEIS: Ab Version 4.0.0 verfügt Paperclip außerdem über eine weitere Validierung, die nicht deaktiviert werden kann. Diese Validierung verhindert das Spoofing von Inhaltstypen. Das heißt, das Hochladen eines PHP-Dokuments (zum Beispiel) als Teil der EXIF-Tags eines wohlgeformten JPEG. Diese Prüfung ist auf den Medientyp beschränkt (der erste Teil des MIME-Typs, also „text“ in text/plain ). Dadurch wird verhindert, dass HTML-Dokumente als JPEGs hochgeladen werden, GIFs jedoch nicht mit der Erweiterung .jpg . Durch diese Validierung werden dem Formular lediglich Validierungsfehler hinzugefügt. Es werden keine Fehler ausgelöst.
Dies kann manchmal zu falschen Validierungsfehlern in Anwendungen führen, die benutzerdefinierte Dateierweiterungen verwenden. In diesen Fällen möchten Sie möglicherweise Ihre benutzerdefinierte Erweiterung zur Liste der Inhaltstypzuordnungen hinzufügen, indem Sie config/initializers/paperclip.rb erstellen:
# „.foo“ als Erweiterung für Dateien mit dem MIME-Typ „text/plain“ zulassen.Paperclip.options[:content_type_mappings] = { foo: %w(text/plain)} Globale Standardwerte für alle Ihre Paperclip-Anhänge können durch Ändern des Paperclip::Attachment.default_options-Hashs definiert werden. Dies kann nützlich sein, um beispielsweise Ihre Standardspeichereinstellungen festzulegen, sodass Sie sie nicht in jeder has_attached_file -Definition definieren müssen.
Wenn Sie Rails verwenden, können Sie einen Hash mit Standardoptionen in config/application.rb oder in einer der config/environments/*.rb Dateien in config.paperclip_defaults definieren. Diese werden beim Booten Ihrer Rails-App in Paperclip::Attachment.default_options zusammengeführt. Ein Beispiel:
module YourApp class Application < Rails::Application # Anderer Code... config.paperclip_defaults = { storage: :fog, fog_credentials: {provider: "Local", local_root: "#{Rails.root}/public"}, fog_directory: "", fog_host: "localhost"} endend Eine weitere Option besteht darin, den Paperclip::Attachment.default_options -Hash direkt zu ändern. Diese Methode funktioniert für Nicht-Rails-Anwendungen oder ist eine Option, wenn Sie die Paperclip-Standardeinstellungen lieber in einem Initialisierer platzieren möchten.
Ein Beispiel für einen Rails-Initialisierer würde etwa so aussehen:
Paperclip::Attachment.default_options[:storage] = :fogPaperclip::Attachment.default_options[:fog_credentials] = { Anbieter: "Local", local_root: "#{Rails.root}/public"}Paperclip::Attachment.default_options[ :fog_directory] = ""Paperclip::Attachment.default_options[:fog_host] = "http://localhost:3000"Paperclip definiert mehrere Migrationsmethoden, mit denen Sie die erforderlichen Spalten in Ihrem Modell erstellen können. Es gibt zwei Arten von Hilfsmethoden, die dabei helfen:
Beim Erstellen einer Tabelle kann der attachment verwendet werden:
Klasse CreateUsersWithAttachments < ActiveRecord::Migration def up create_table :users do |t| t.attachment :avatar end end # Dies setzt voraus, dass Sie nur die Benutzertabelle für den Büroklammeranhang verwenden. Vorsichtig fallen lassen! def down drop_table :users endend
Sie können anstelle der oben/ up down Kombination auch die change verwenden, wie unten gezeigt:
Klasse CreateUsersWithAttachments < ActiveRecord::Migration def change create_table :users do |t| t.attachment :avatar end endend
Alternativ können die Methoden add_attachment und remove_attachment verwendet werden, um neue Paperclip-Spalten zu einer vorhandenen Tabelle hinzuzufügen:
Klasse AddAttachmentColumnsToUsers < ActiveRecord::Migration def up add_attachment :users, :avatar end def down remove_attachment :users, :avatar endend
Oder Sie können dies mit der change tun:
Klasse AddAttachmentColumnsToUsers < ActiveRecord::Migration def change add_attachment :users, :avatar endend
Vintage-Syntax (wie t.has_attached_file und drop_attached_file ) wird in Paperclip 3.x weiterhin unterstützt, es wird jedoch empfohlen, diese Migrationsdateien zu aktualisieren, um diese neue Syntax zu verwenden.
Paperclip wird mit 3 Speicheradaptern geliefert:
Dateispeicherung
S3-Speicher (über aws-sdk-s3 )
Nebelspeicher
Wenn Sie Paperclip mit einem anderen Speicher verwenden möchten, können Sie diese Juwelen zusammen mit Paperclip installieren:
Büroklammer-Azurblau
Büroklammer-Azure-Speicher
Büroklammer-Dropbox
Die als Anhänge zugewiesenen Dateien werden standardmäßig in dem Verzeichnis abgelegt, das durch die Option :path für has_attached_file angegeben wird. Standardmäßig ist dieser Speicherort :rails_root/public/system/:class/:attachment/:id_partition/:style/:filename . Dieser Speicherort wurde gewählt, weil bei standardmäßigen Capistrano-Bereitstellungen das Verzeichnis public/system mit dem freigegebenen Verzeichnis der App verknüpft werden kann, was bedeutet, dass es zwischen Bereitstellungen bestehen bleibt. Wenn Sie beispielsweise diesen :path verwenden, haben Sie möglicherweise eine Datei unter
/data/myapp/releases/20081229172410/public/system/users/avatar/000/000/013/small/my_pic.png
HINWEIS : Dies ist eine Änderung gegenüber früheren Versionen von Paperclip, stellt jedoch insgesamt eine sicherere Wahl für den Standarddateispeicher dar.
Sie können Ihre Dateien auch über den S3-Dienst von Amazon speichern. Fügen Sie dazu das Gem aws-sdk-s3 in Ihre Gemfile ein:
gem 'aws-sdk-s3'
Und dann können Sie die Verwendung von S3 aus has_attached_file angeben. Weitere Informationen zur Konfiguration und Verwendung von S3-Speicher finden Sie in der Paperclip::Storage::S3 Dokumentation.
Dateien im lokalen Dateisystem (und im öffentlichen Verzeichnis der Rails-App) stehen dem gesamten Internet zur Verfügung. Wenn Sie eine Zugriffskontrolle benötigen, können Sie Ihre Dateien an einem anderen Ort ablegen. Sie müssen sowohl die Optionen :path als auch :url ändern, um sicherzustellen, dass die Dateien nicht für die Öffentlichkeit verfügbar sind. Sowohl :path als auch :url erlauben den gleichen Satz interpolierter Variablen.
Wenn eine Datei hochgeladen oder angehängt wird, kann sie in einer von mehreren verschiedenen Eingabeformen vorliegen, vom UploadedFile-Objekt von Rails über ein StringIO bis hin zu einer Tempfile oder sogar einem einfachen String, der eine URL ist, die auf ein Bild verweist.
Paperclip akzeptiert standardmäßig viele dieser Quellen. Mit ein wenig Konfiguration kann es sogar noch mehr bewältigen. Die E/A-Adapter, die Bilder von nicht lokalen Quellen verarbeiten, sind standardmäßig nicht aktiviert. Sie können aktiviert werden, indem Sie in config/initializers/paperclip.rb eine Zeile ähnlich der folgenden hinzufügen:
Paperclip::DataUriAdapter.register
Am besten aktivieren Sie einen Fernladeadapter nur, wenn Sie ihn benötigen. Andernfalls besteht die Möglichkeit, dass jemand Einblick in Ihre interne Netzwerkstruktur erhält und diese als Vektor nutzt.
Die folgenden Adapter werden standardmäßig nicht geladen:
Paperclip::UriAdapter – akzeptiert eine URI Instanz.
Paperclip::HttpUrlProxyAdapter – akzeptiert eine http Zeichenfolge.
Paperclip::DataUriAdapter – akzeptiert eine Base64-codierte data: .
Paperclip unterstützt eine erweiterbare Auswahl an Postprozessoren. Wenn Sie eine Reihe von Stilen für einen Anhang definieren, wird standardmäßig erwartet, dass es sich bei diesen „Stilen“ tatsächlich um „Miniaturansichten“ handelt. Diese werden von Paperclip::Thumbnail verarbeitet. Aus Gründen der Abwärtskompatibilität können Sie entweder eine einzelne Geometriezeichenfolge oder ein Array übergeben, das eine Geometrie und ein Format enthält, in das die Datei konvertiert wird, etwa so:
has_attached_file :avatar, Styles: { Thumb: ["32x32#", :png] } Dadurch wird der „Daumen“-Stil in ein 32x32-Quadrat im PNG-Format konvertiert, unabhängig davon, was hochgeladen wurde. Wenn das Format nicht angegeben wird, bleibt es gleich (z. B. JPGs bleiben JPGs). Paperclip::Thumbnail verwendet ImageMagick, um Bilder zu verarbeiten; Die Geometriedokumentation von ImageMagick enthält weitere Informationen zu den akzeptierten Stilformaten.
Für eine detailliertere Steuerung des Konvertierungsprozesses können source_file_options und convert_options verwendet werden, um Flags und Einstellungen direkt an das leistungsstarke Konvertierungstool von ImageMagick zu übergeben, das hier dokumentiert wird. Zum Beispiel:
has_attached_file :image, Styles: { Regular: ['800x800>', :png]},
source_file_options: {regular: "-density 96 - Depth 8 -quality 85" }, Convert_options: {regular: "-posterize 3"}ImageMagick unterstützt eine Reihe von Umgebungsvariablen zur Steuerung seiner Ressourcengrenzen. Sie können beispielsweise Speicher- oder Ausführungszeitlimits erzwingen, indem Sie die folgenden Variablen in der Prozessumgebung Ihrer Anwendung festlegen:
MAGICK_MEMORY_LIMIT=128MiB
MAGICK_MAP_LIMIT=64MiB
MAGICK_TIME_LIMIT=30
Eine vollständige Liste der Variablen und Beschreibungen finden Sie in der Ressourcendokumentation von ImageMagick.
Sie können Ihre eigenen benutzerdefinierten Anhangsprozessoren schreiben, um Aufgaben wie das Hinzufügen von Wasserzeichen, das Komprimieren von Bildern oder das Verschlüsseln von Dateien auszuführen. Benutzerdefinierte Prozessoren müssen im Paperclip Modul definiert werden, von Paperclip::Processor erben (siehe lib/paperclip/processor.rb ) und eine make -Methode implementieren, die eine File zurückgibt. Alle Dateien in den Verzeichnissen lib/paperclip und lib/paperclip_processors Ihrer Rails-App werden automatisch von Paperclip geladen. Prozessoren werden mit der Option :processors für has_attached_file angegeben:
has_attached_file :scan, Stile: { text: { qualität: :better } }, Prozessoren: [:ocr] Dies würde die hypothetische Klasse Paperclip::Ocr laden und ihr zusammen mit der hochgeladenen Datei die Optionen hash { quality: :better } übergeben.
Es können mehrere Prozessoren angegeben werden, die in der Reihenfolge aufgerufen werden, in der sie im Array :processors definiert sind. Jeder nachfolgende Prozessor erhält das Ergebnis des vorherigen Prozessors. Alle Prozessoren erhalten die gleichen Parameter, die im :styles Hash definiert sind. Angenommen, wir hätten diese Definition:
has_attached_file :scan, Stile: { text: { qualität: :better } }, Prozessoren: [:rotator, :ocr] Sowohl der :rotator -Prozessor als auch der :ocr -Prozessor würden die Optionen { quality: :better } erhalten. Wenn ein Prozessor eine Option erhält, die er nicht erkennt, wird von ihm erwartet, dass er sie ignoriert.
HINWEIS: Da Prozessoren den ursprünglichen Anhang in Stile umwandeln, werden keine Prozessoren ausgeführt, wenn keine Stile definiert sind.
Wenn Sie daran interessiert sind, die Breite, Höhe und Größe Ihres Miniaturbilds in der Datenbank zwischenzuspeichern, schauen Sie sich das Juwel „paperclip-meta“ an.
Wenn Sie daran interessiert sind, die Miniaturansicht im laufenden Betrieb zu erstellen, sollten Sie sich vielleicht auch das Juwel „attachment_on_the_fly“ ansehen.
Der Miniaturbildgenerator von Paperclip (siehe lib/paperclip/thumbnail.rb ) ist als Prozessor implementiert und kann eine gute Referenz zum Schreiben eigener Prozessoren sein.
Vor und nach dem Nachverarbeitungsschritt ruft Paperclip das Modell mit einigen Rückrufen zurück, sodass das Modell den Verarbeitungsschritt ändern oder abbrechen kann. Die Rückrufe sind before_post_process und after_post_process (die vor und nach der Verarbeitung jedes Anhangs aufgerufen werden) sowie die anhangspezifischen before_ und after_ . Die Rückrufe sollen den normalen ActiveRecord-Rückrufen so nahe wie möglich kommen. Wenn Sie also in einem before_filter „false“ zurückgeben (genauer gesagt, „nil“ ist nicht dasselbe), wird der Nachbearbeitungsschritt angehalten. Die Rückgabe von „false“ in einem after_filter stoppt nichts, aber Sie können bei Bedarf auf das Modell und den Anhang zugreifen.
HINWEIS: Die Nachbearbeitung wird nicht einmal gestartet , wenn der Anhang gemäß den Validierungen ungültig ist. Ihre Rückrufe und Bearbeiter werden nur mit gültigen Anhängen aufgerufen.
Klasse Message < ActiveRecord::Base has_attached_file :asset, Styles: { Thumb: "100x100#" } before_post_process :skip_for_audio def skip_for_audio
! %w(audio/ogg application/ogg).include?(asset_content_type) endend Paperclip verfügt über eine Interpolation namens :hash zur Verschleierung von Dateinamen öffentlich verfügbarer Dateien.
Beispielverwendung:
has_attached_file :avatar, { url: "/system/:hash.:extension", hash_secret: "longSecretString"} Die :hash -Interpolation wird durch einen eindeutigen Hash ersetzt, der aus dem besteht, was in :hash_data angegeben ist. Der Standardwert für :hash_data ist ":class/:attachment/:id/:style/:updated_at" .
:hash_secret ist erforderlich – eine Ausnahme wird ausgelöst, wenn :hash verwendet wird, ohne dass :hash_secret vorhanden ist.
Weitere Informationen zu dieser Funktion finden Sie in der Erklärung des Autors
Eine Prüfsumme der zugewiesenen Originaldatei wird in das Modell eingefügt, wenn diese über ein Attribut namens „Fingerabdruck“ verfügt. Nach dem obigen Beispiel für die Benutzermodellmigration würde die Migration wie folgt aussehen:
Klasse AddAvatarFingerprintColumnToUser < ActiveRecord::Migration def up add_column :users, :avatar_fingerprint, :string end def down remove_column :users, :avatar_fingerprint endend
Der Algorithmus kann über eine Konfigurationsoption spezifiziert werden; Aus Gründen der Abwärtskompatibilität mit Paperclip 5 und früheren Versionen wird standardmäßig MD5 verwendet.
has_attached_file :some_attachment, adapter_options: { hash_digest: Digest::SHA256 } Führen Sie CLASS=User ATTACHMENT=avatar rake paperclip:refresh:fingerprints aus, nachdem Sie den Digest für vorhandene Anhänge geändert haben, um die Fingerabdrücke in der Datenbank zu aktualisieren.
Es besteht die Möglichkeit, Anhänge beizubehalten, um mit vorläufig gelöschten Modellen gut zu spielen. (wirkt_als_paranoid, Paranoia usw.)
has_attached_file :some_attachment, { Preserve_files: true,} Dadurch wird verhindert, dass some_attachment gelöscht wird, wenn das Modell zerstört wird, sodass es weiterhin vorhanden ist, wenn das Objekt später wiederhergestellt wird.
Aufrufbare Objekte (Lambdas, Procs) können an mehreren Stellen zur dynamischen Konfiguration in Paperclip verwendet werden. Diese Strategie existiert in einer Reihe von Komponenten der Bibliothek, ist jedoch vor allem in den Möglichkeiten bedeutsam, die Anwendung benutzerdefinierter Stile und Prozessoren auf bestimmte Modellinstanzen zu ermöglichen, anstatt definierte Stile und Prozessoren auf alle Instanzen anzuwenden.
Stellen Sie sich ein Benutzermodell vor, das je nach Rolle des Benutzers unterschiedliche Stile hat. Möglicherweise sind einige Benutzer Chefs (z. B. reagiert eine Benutzermodellinstanz auf #boss? ) und verdienen ein größeres Avatar-Miniaturbild als normale Benutzer. Die Konfiguration zur Bestimmung, welche Stilparameter basierend auf der Benutzerrolle verwendet werden sollen, könnte wie folgt aussehen: Ein Chef erhält ein Miniaturbild im 300x300 andernfalls wird ein Miniaturbild 100x100 erstellt.
Klasse Benutzer < ActiveRecord::Base has_attached_file :avatar, Stile: lambda { |attachment| { thumb: (attachment.instance.boss? ? "300x300>" : "100x100>") } }end Ein weiteres erfundenes Beispiel ist ein Benutzermodell, das weiß, welche Dateiprozessoren darauf angewendet werden sollen (über den impliziten thumbnail hinaus, der aufgerufen wird, wenn :styles definiert werden). Möglicherweise verfügen wir über einen Wasserzeichenprozessor, der nur bei den Avataren bestimmter Modelle verwendet wird. Die Konfiguration hierfür könnte darin bestehen, dass die Instanz abgefragt wird, welche Prozessoren auf sie angewendet werden sollen. Vermutlich geben einige Benutzer möglicherweise [:thumbnail, :watermark] für seine Prozessoren zurück, wobei ein definierter watermark nach dem bereits von Paperclip definierten thumbnail aufgerufen wird.
Klasse Benutzer < ActiveRecord::Base has_attached_file :avatar, Prozessoren: lambda { |instance| Instanz.Prozessoren } attr_accessor :processorsendStandardmäßig gibt Paperclip die Protokollierung entsprechend Ihrer Loggerstufe aus. Wenn Sie die Protokollierung deaktivieren möchten (z. B. während des Testens), fügen Sie dies in die Konfiguration Ihrer Umgebung ein:
Your::Application.configure do... Paperclip.options[:log] = false...end
Weitere Informationen in den Rdocs
Um Capistrano mit dem Verzeichnis public/system zu verknüpfen, sodass Anhänge auch bei neuen Bereitstellungen Bestand haben, legen Sie die Option linked_dirs in Ihrer Datei config/deploy.rb fest:
set :linked_dirs, fetch(:linked_dirs, []).push('public/system') Paperclip erkennt neue Anhangsstile, die Sie in früheren Bereitstellungen hinzugefügt haben. Das Einzige, was Sie nach jeder Bereitstellung tun sollten, ist rake paperclip:refresh:missing_styles aufzurufen. Die aktuellen Anhangsstile werden standardmäßig in RAILS_ROOT/public/system/paperclip_attachments.yml gespeichert. Sie können es ändern, indem Sie:
Paperclip.registered_attachments_styles_path = '/tmp/config/paperclip_attachments.yml'
Hier ist ein Beispiel für Capistrano:
Namespace :paperclip do desc „fehlende Paperclip-Styles erstellen“ task :build_missing_styles do on Roles(:app) do without „deploy:compile_assets“, „paperclip:build_missing_styles“)
Jetzt müssen Sie nicht mehr daran denken, die Miniaturansichten in der Produktion jedes Mal zu aktualisieren, wenn Sie einen neuen Stil hinzufügen. Leider funktioniert es nicht mit dynamischen Stilen – es ignoriert sie einfach.
Wenn Sie bereits eine funktionierende App haben und nicht möchten rake paperclip:refresh:missing_styles alte Bilder aktualisiert, müssen Sie Paperclip über vorhandene Stile informieren. Erstellen Sie einfach manuell eine Datei paperclip_attachments.yml . Zum Beispiel:
class User < ActiveRecord::Base has_attached_file :avatar, Styles: { Thumb: 'x100', Croppable: '600x600>', Big: '1000x1000>' }endclass Book < ActiveRecord::Base has_attached_file :cover, Styles: { Small: 'x100', groß: '1000x1000>' } has_attached_file :sample, Styles: { Thumb: 'x100' }Ende Dann in RAILS_ROOT/public/system/paperclip_attachments.yml :
---:Benutzer: :avatar: - :Daumen - :zuschneidbar - :big:Buch: :cover: - :klein - :groß :Beispiel: - :Daumen
Paperclip bietet RSpec-kompatible Matcher zum Testen von Anhängen. Weitere Informationen finden Sie in der Dokumentation zu Paperclip::Shoulda::Matchers.
Parallele Tests
Wenn Sie versuchen, Tests parallel auszuführen, kann es aufgrund des path für die Paperclip-Speicherung vorkommen, dass Dateien überschrieben werden, da für sie in jedem Testprozess derselbe Pfad berechnet wird. Während dieser Fix für parallel_tests funktioniert, sollte ein ähnliches Konzept für alle anderen Mechanismen zum gleichzeitigen Ausführen von Tests verwendet werden.
if ENV['PARALLEL_TEST_GROUPS'] Paperclip::Attachment.default_options[:path] = ":rails_root/public/system/:rails_env/#{ENV['TEST_ENV_NUMBER'].to_i}/:class/:attachment/:id_partition/ :filename"else Paperclip::Attachment.default_options[:path] = „:rails_root/public/system/:rails_env/:class/:attachment/:id_partition/:filename“ende Der wichtige Teil hierbei ist die Einbindung von ENV['TEST_ENV_NUMBER'] oder eines ähnlichen Mechanismus für die von Ihnen verwendete parallele Testbibliothek.
Integrationstests
Durch die Verwendung von Integrationstests mit FactoryBot können mehrere Kopien Ihrer Testdateien in der App gespeichert werden. Um dies zu vermeiden, geben Sie in config/environments/test.rb einen benutzerdefinierten Pfad an, etwa so:
Paperclip::Attachment.default_options[:path] = "#{Rails.root}/spec/test_files/:class/:id_partition/:style.:extension" Stellen Sie dann sicher, dass Sie dieses Verzeichnis löschen, nachdem die Testsuite ausgeführt wird, indem Sie es zu spec_helper.rb hinzufügen.
config.after(:suite) do FileUtils.rm_rf(Dir["#{Rails.root}/spec/test_files/"])endBeispiel einer Testkonfiguration mit Factory Bot
FactoryBot.define für Factory :user für avatar { File.new("#{Rails.root}/spec/support/fixtures/image.jpg") } endendWenn Sie eine Funktion oder einen Bugfix beisteuern möchten: Danke! Um sicherzustellen, dass Ihr Fix/Feature eine hohe Chance hat, aufgenommen zu werden, lesen Sie bitte die folgenden Richtlinien:
Posten Sie eine Pull-Anfrage.
Stellen Sie sicher, dass es Tests gibt! Wir akzeptieren keine Patches, die nicht getestet wurden. Es kommt selten vor, dass explizite Tests nicht erforderlich sind. Wenn Sie Fragen zum Schreiben von Tests für Paperclip haben, öffnen Sie bitte eine GitHub-Ausgabe.
Weitere Informationen zum Mitwirken und Ausführen von Tests finden Sie unter CONTRIBUTING.md .
Vielen Dank an alle Mitwirkenden!
Paperclip unterliegt dem Urheberrecht © 2008–2017 Thoughtbot, Inc. Es handelt sich um kostenlose Software, die unter den in der MIT-LICENSE-Datei angegebenen Bedingungen weiterverbreitet werden darf.
Paperclip wird von Thoughtbot gepflegt und finanziert. Die Namen und Logos für Thoughtbot sind Marken von Thoughtbot, Inc.
Wir lieben Open-Source-Software! Sehen Sie sich unsere anderen Projekte an oder beauftragen Sie uns mit der Gestaltung, Entwicklung und Weiterentwicklung Ihres Produkts.
