apostrophe-pieces-submit-widgets - npm Package Compare versions

Comparing version 2.0.0 to 2.0.1

index.js

@@ -88,3 +88,4 @@ // in lib/modules/contact-form/index.js
 
-    self.pushAsset('script', 'always', { when: 'always' });
+    self.pushAsset('script', 'user', { when: 'always' });
+    self.pushAsset('stylesheet', 'user', { when: 'always' });
 
@@ -91,0 +92,0 @@ self.route('post', 'submit', function(req, res) {

package.json

 {
   "name": "apostrophe-pieces-submit-widgets",
-  "version": "2.0.0",
+  "version": "2.0.1",
   "description": "Submit user generated content to Apostrophe CMS sites",
@@ -5,0 +5,0 @@ "main": "index.js",

README.md

 # apostrophe-pieces-submit-widgets
 
-This module lets your site visitors submit new pieces of any type you wish. The feature is packaged as a widget, so you can easily add it to any page template, provided you take care of a few requirements as noted below.
+This module extends the [Apostrophe CMS](http://apostrophecms.org), allowing sie visitors to submit new [pieces](http://apostrophecms.org/docs/tutorials/getting-started/reusable-content-with-pieces.html) of any type you wish. The feature is packaged as a widget, so you can easily add it to any page template.
 
-Here's how to set it up:
+Here's how to set it up. Our example is based on the [apostrophe-events](https://www.npmjs.com/package/apostrophe-events) module, which extends pieces.
 
@@ -11,5 +11,14 @@ ```javascript
   // For example: we're using the "apostrophe-events" module
-  // and we'll want submissions of events
+  // and we'll want submissions of events. "apostrophe-events"
+  // extends apostrophe-pieces
   'apostrophe-events': {
-    // Any custom configuration for the events module
+    // Let's add an attachment field so the user can upload an image
+    addFields: [
+      {
+        name: 'image',
+        type: 'attachment',
+        group: 'images',
+        required: true
+      }
+    ]
   },
@@ -26,12 +35,6 @@ // ** The name you give this module is significant. **
     // of the "published" field, for instance
-    fields: [ 'title', 'body' ]
+    fields: [ 'title', 'body', 'image', 'startDate', 'endDate' ]
   },
-  'default-pages': {
-    extend: 'apostrophe-custom-pages',
-    // Necessary to allow use of the submit widget on this page type
-    scene: 'user'
-  },
-  // Optional: if you want to use attachment fields in widgets
-  // in your submission forms, you must allow the public to upload files.
-  // See below for how to define a widget that works well for this
+  // Optional: if you want to let the public attach files.
+  // See the `addFields` call above
   'apostrophe-permissions': {
@@ -41,19 +44,3 @@ construct: function(self, options) {
     }
-  },
-  // Here's a simple widget that contains an image attachment field.
-  // Use this in your schema for the submitted piece type,
-  // rather than apostrophe-images, to solve permissions problems and
-  // keep user content out of your media library
-  'submitted-image-widgets': {
-    extend: 'apostrophe-widgets',
-    label: 'Image',
-    addFields: [
-      {
-        name: 'image',
-        type: 'attachment',
-        group: 'images',
-        required: true
-      }
-    ]
-  }  
+  }
 }
@@ -64,4 +51,2 @@ ```
 
-**All page types that will display the submission form widget need to set the `scene` option to `user` when doing so.** You can do this when configuring `apostrophe-pieces-pages`, for instance, or in any subclass of `apostrophe-custom-pages`. The latter is the easiest way to add this capability to a "plain old page type" like `default`.
-
 Once you have the module set up, you can add a submission form widget to any `apos.area` or `apos.singleton` call:
@@ -79,2 +64,4 @@
 
+> This module also adds a `submitted: true` property. If you wish, you can add that to your pieces module's schema as a boolean field and configure a filter for it so you can always distinguish between visitor submissions and your own unpublished content.
+
 ## Contact forms
@@ -92,6 +79,8 @@
 
-**A `submitted-image-widgets` module is defined in the example `app.js` above.** You'll also need to create `lib/modules/submitted-image-widgets/widget.html`, to actually display it:
+**A `submitted-image-widgets` module is defined in the example `app.js` above.**
 
+In `lib/modules/apostrophe-events-pages/views/show.html`, or anywhere else you have access to the piece, you can display the image like this:
+
 ```
-<img src="{{ apos.attachments.url(data.widget.image, { size: 'full' }) }}" />
+<img src="{{ apos.attachments.url(data.piece.image, { size: 'full' }) }}" />
 ```
@@ -101,10 +90,6 @@
 
-When accepting user submissions, it's usually better to minimize the complexity of what users can do, so they don't become confused by the process. Rather than areas, offer them a rich text singleton, a submitted-image singleton, etc.
+When accepting user submissions, it's usually better to minimize the complexity of what users can do, so they don't become confused by the process. Rather than areas, offer them a rich text singleton, a clearly labeled attachment field, etc.
 
-## If it doesn't work
+## If it doesn't work: some tricky edge cases
 
-### Did you forget `scene: 'user'`?
-
-You probably haven't set `scene: 'user'` for your page type. The page type that will feature the widget must set that option to load all of the CSS and JavaScript normally reserved for logged-in users. See the example above.
-
 > Keep in mind that you can do this for an entire blog by setting the flag for the `apostrophe-blog-pages` module, and so on for any subclass of `apostrophe-pieces-pages`.
@@ -116,1 +101,24 @@
 
+### AJAX and assets: when the form is dynamically loaded
+
+This widget sets its `scene: 'user'` option, which automatically loads the extra user-oriented CSS and JavaScript it needs at the time the page containing the widget is loaded. 99% of the time, that's perfectly sufficient.
+
+However, if you are loading the widget into the page later via an "infinite scroll" plugin like [jQuery Bottomless](https://github.com/punkave/jquery-bottomless), Apostrophe won't know the extra assets are needed until too late.
+
+To address that scenario, set the `scene: 'user'` option for any page type that might load the widget via AJAX.
+
+This is pretty uncommon, but the most likely example is an `apostrophe-pieces-page` like our event index page. It's easy to configure that page to do it because there is already a module managing it:
+
+```javascript
+'apostrophe-events-pages': {
+  scene: 'user'
+}
+```
+
+*If the page type doing the extra AJAX loading is an "ordinary" page type like `home` or `default` with no module managing it so far, you'll need to create a module that extends `apostrophe-custom-pages` and sets its `name` option to `home` or `default` as appropriate.*
+
+## Changelog
+
+2.0.1: the documentation is complete and the examples are well-tested. Default styles are pushed to hide the "thank you" message until it replaces the form. Since `scene: 'user'` is set for the widget, we push the assets for the widget only for `scene: 'user'`, which saves overhead on pages that don't include it.
+
+2.0.0: initial release.

No alert changes

Improved metrics

Total package byte prevSize

13008

increased by9.85%

Lines of code

148

increased by0.68%

Number of lines in readme file

117

increased by7.34%

No dependency changes