Are you using Apostrophe for your projects? Tell us about it!

[Tom Boutell]

Hi folks,

We often talk to clients who want to make sure that Apostrophe's community is significantly larger than P'unk Avenue. Vendor lock-in is a big concern for everyone.

Of course Apostrophe is bigger than us! The apostrophe github repo alone has been starred over 1,000 times, and who bothers to star repos?

But: our clients ask for more proof. It's very important for our clients — and yours — to understand that Apostrophe is a safe choice with a developer community behind it.

So! Want to be listed in a public list of Apostrophe developers on the apostrophenow.org site? 

Please fill out a quick typeform:

https://tomboutell1.typeform.com/to/NeqckD

(We know it's sometimes not permissible to list the client sites you've created... so we're not requiring it. But, there's a space to showcase a link if you have an A2 site you're proud of.)

We reserve the right to leave out a listing if we see fit, but we'll try hard to limit that to obvious causes for concern. Clearly our goal here is to list more developers, not fewer.

Thanks for participating! We look forward to growing the Apostrophe community with you.

[Fotis Paraskevopoulos]

Hello All,

First of all I would like to express my gratitude to the Punkave team for their work, specially in 0.6 (2.0.0)

I read the developer docs and here are my notes:

Component Diagram

I think a brief introduction of the technologies used , the core modules and  how they fit together will go a long way understanding the documentation, something like a compoment diagram, where each rectangle is clickable to the github repo, and acts as a reference point.

* What is data? (Getting started before the Adding a section to the home page)

If someone is new to 0.5 it is really difficult to grasp that self.loader adds “stuff” to the nunjucks context. This used to be page and page.extras, and as I understand it now it is called “data”. There needs to be a small explanation of this, as well as the what the developer can expect out of the box for “data”, for example do we need data.extras? 

* What are the outerlayout sections which **can** be overriden?

data.outerLayout confused the hell out of me, but once I get into 0.6 its probably nothing. However what needs to be explained is what are the “overridable” sections of outerLayout if the frontend developer chooses not to override it. I am saying this because in the getting started guide you explicitly state that it is better **not** to override it.

* “The name of a module that provides widgets should end in -widgets.”? (http://unstable.apostrophenow.org/tutorials/getting-started/custom-widgets.html)

What if a module provides multiple features and not only widgets or is this not possible anymore?

How can we have default pieces widget value ( for example “all” by default)? (http://unstable.apostrophenow.org/tutorials/getting-started/reusable-content-with-pieces.html)

This is a bit unrelated, but since I had the question whilst reading, I am asking here. What if I want a widget which provides no option to the user, and it defaults to some options.

http://unstable.apostrophenow.org/reference/apostrophe-pieces/api.html -> 404

The API sections RULES! 

—-

One last thing….

I have never encountered a team so open to criticism as Punkave, and it is for this reason that I would like to state a few pain points in 0.5 which I hope will help them make the 0.6 version the defacto CMS for nodejs. 

The following has nothing to do with the manual, its has to do with working with the CMS. (Disclaimer: I haven’t touched 0.6) Many of these may have been solved in 0.6, so that is great. And it may seem like I am complaining, I am not, this is a just a categorization of concern/problems I have encountered whilst working with 0.5. 

Identity Crisis

The first pain point is the fact that it is not clear what exactly A2 is, is it a CMS on top of Nodejs, or is it a CMS **Platform” built with Nodejs. 

Option 1. A CMS on top of Nodejs -> Grab the Sandbox, create areas from the plethora of widget options, style it at your own content, and deploy

Options 2. A CMS **Platform** built with nodejs-> Forget the sandbox, create areas from your widget extensions, and custom widgets , customize routing through the platform, extend permissions, override core modules, etc, and deploy

If A2 is option 2, then there are several architecture concerns which need to be addressed, and I categorize them here. Many a times I had to go really deep to understand how a method works so I could safely monkeypatch it in a custom module, or in a hack.

Terminology

We had self.get, app.get, apos.pages.get, all three do something different, we have apos.pages (module), and app.pages(mongodb), try navigating through javascript code written by someone else  using any  IDE that can handle javascript.  We have self.middleware , self.dispatch, self.loader, which one should be used, in what scenario, try adding csrf to A2 and you see what I am talking about. 

We had data/local.js   lib/locals.js, I know one is plural but why do they have the same name? Do they differ in functionality?

Functionality

Getting the path of a file in self.loader for example was a pain in the butt, there is a thread here on that subject

apostrophe-blog-2, in my opinion was exactly what snippet editing should have looked like from the start, this really helped boost our UX with our clients.

Extensibility

There were many ocassions where I needed something a bit different form the defaults, I have one project which I keep my own apostrophe and apostrophe-pages versions, constantly merging from master, because I am overriding code which has been written inside express routes.

Another example of this is, try filtering the media assets differently, for example allowing a group of users to see/edit media, and you’ll see what I mean

In the front end, I want to add a button to the apos-ui-control section of a widget or area.

I want my own slug generation logic :)

Modifiability

apostrophe-schemas is magical, but try to get a bit out of its way. For example, sorting select options differently. Or making the modal dialog a bit taller, remove the side space added by the apostrophe-has-tabs logic even though it didn’t have any, these shouldn’t be that hard to do.

Something a bit more complicated, change the way you select pages, instead of autocomplete, allow the user to pick snippets using a paginated checked list. Customizing this should not mean re-writting like 90% of the code (server side as well!), this should entail modifying only small portions of  manager.html and content.js.

Intrusiveness

The markup gets in the way a lot of the times. I worked around this by hacking the default *.html (slideshow.html) and widget.players (btw- this is barely documented), to provide markup which was simpler or more apt to some frontend library like isotope for example.

The same is true for css. All apos-areas have an “apos-content” class which has “text-align:center” rule, this one really got under our skin, sure we can override it, but we always wondered what are we breaking by doing so, why did the content have to be aligned center? No-one knows.

Longevity

I only read the manual for 0.6 and I can already see that it is a no go for BC, and that is ok, however architecturally this needs to be considered moving forward, we can’t have a 0.7 in a year which is yet another complete re-write.

You will be right to say that I should do something about this, like a pull request (right Tom?), however unless you are there in the decision process for a piece of code(transparency), it is almost impossible to understand all the edge cases that were discussed, and how your change will break the entire CMS, most of the conversation in this group is about usage, not the development of the platform. 

Punkave you are very generous giving away something that you could keep to yourself, but if you are putting yourself in a position of “driving” an opensource CMS project, the architecture, documentation and development process need reconsideration.

Finally, a big thank you from me and my team.

Best,

FP

--
You received this message because you are subscribed to the Google Groups "apostrophecms" group.
To unsubscribe from this group and stop receiving emails from it, send an email to apostrophecms+unsubscribe@googlegroups.com.
For more options, visit https://groups.google.com/d/optout.

[Tom Boutell]

Fotis, thanks for this really thoughtful response!

Rather than try to respond to everything right now, I just want to say
that I'm going to refer to your email as we do some final tweaks of
the documentation for launch... which is impending (as in, perhaps
Friday)... but, 2.0.0 has resolved a lot of these concerns, and many
of the rest will be resolved by writing more documentation. An ongoing
process beyond the day we type "npm publish" on 2.0.0, for sure.

A few of your burning questions though...

* Longevity

Thanks, this is hugely important to clarify.

1. Yes, 2.0.0 is a bc break for code. New code is needed. But it's
ever so much nicer, and the nice patterns that were stuck inside 0.5,
begging to be released, are now on the surface (:

We didn't throw out concepts like areas and widgets, and "snippets"
were renamed pieces but are otherwise very similar — just, again, much
more elegant.

As you work with it you'll see that it is very much Apostrophe,
liberated from its own cruft — it's radically better, but not
radically different in kind.

2. There WILL be a content migration path from 0.5 to 2.0.0. There
isn't, yet, but we have over 70 clients on 0.5. We WILL write that
task, and quite soon! It just makes sense for now to shake things down
in 2.0.0 with new projects.

3. 2.0.0 is a LONG TERM SUPPORT release. We will stand behind this
release for a *minimum* of 3 years. And when you read that, keep in
mind that in actuality, we are still supporting customers who have
versions of Apostrophe from before 1.0. (:

We approached 2.0.0 as a year-long project and a series of
pair-programming sprints because we wanted a product we would be happy
to support for the long term.

That being said... we are going to follow semantic versioning after
2.0.0 is published. So, we might have to release "3.0.0" or even
"4.0.0" relatively soon, just because of the tiniest bc break that
everyone agrees is obvious and good! That's just how semantic
versioning works. It does not mean that we are making radical changes
or will not stand behind 2.0.0.

* `data` is the new `extras`. Boom. (: Add stuff to `req.data`, it
shows up on the `data` object in Nunjucks. Note this means that
everything you add is a property of `data` rather than being "by
itself" in Nunjucks. Our frontend team made this choice because it
means you can `apos.log(data)`, and because it namespaces things
nicely: `apos` contains Apostrophe helpers, while `data` contains
"your stuff" (including things Apostrophe gives you, like
`data.page`).

* outerLayout is actually a normal template now, extended in a normal
nunjucks way, although you extend "data.outerLayout" to give
Apostrophe a chance to substitute the ajax refresh layout instead.

This means that you can override blocks normally at last! There are no
special case "whoops you're not allowed to override that" sections in
2.0.0.

And we created an "outerLayoutBase" template so you can override
blocks selectively in an "outerLayout.html" in your own
"apostrophe-templates" module.

But, you often won't need to, because the only stuff in outerLayout at
this point is our admin UI and asset delivery. (OK, you might need to
and that's why we've made it easier if you do need to.)

* "What if a module provides multiple features and not only widgets or
is this not possible anymore?" Yes, it's one module per job now...
but, you can "bundle" several Apostrophe modules in a single npm
module thanks to moog-require. Check out:

https://github.com/punkave/apostrophe-blog/tree/unstable

This allows you to pack up a pieces module, a pieces-widgets module
and a pieces-pages module to be distributed together in npm under one
sensible name. The developer currently has to specify that they are
using the bundle in their Apostrophe config object:

```
bundles: ['apostrophe-blog']
```

This requirement may go away in the future.

* "How can we have a default pieces widget value, like specifying
'all' by default?"

I assume you mean from a template and not just globally for that
widget type. This is a good idea and a frequent internal request so
it's likely to be a postlaunch feature before long.

* 404 for a link to the pieces API

We need to mop up a bunch of guesses we made before actually
generating the reference docs.

See:

http://unstable.apostrophenow.org/reference/apostrophe-pieces/

* Identity Crisis

This was a big problem in 0.4/0.5 because... reasons which are too
boring and historical to go into (:

With 2.0.0... the Apostrophe module is "a CMS platform" enabling you
to build a website with a nice CMS and any custom functionality you
wish.

So the apos object you create with it is... *your website*. Boom!

There is no "apostrophe-site" module thrown in later to glue it all together (:

Your "platform" option is definitely more accurate for Apostrophe.
In-house we use extremely stripped-down boilerplate for each new
project.

The new tutorials start "from scratch" to show how easy that is, but
also because that's who Apostrophe, the open source CMS framework, is
for: web developers who want to go beyond a sandbox site. And do it in
Node. With all the performance benefits and the joy of not switching
languages constantly between front and back end.

* Terminology

Oh, don't we know it. Which is why this is SO much better in 2.0.0.
You really should dive in. (:

Some key modules to read about:

apostrophe-module (this is the base class of ALL modules, anything it
can do, any module can do out of the box)
apostrophe-pieces
apostrophe-custom-pages (all regular "page" types extend this,
automatically if not directly)
apostrophe-doc-type-manager (rarely used directly, but -pieces and
-custom-pages both extend this)

Also apostrophe-docs, which provides the low-level guts for
manipulating all docs in the aposDocs collection and lets you get in
touch with the best module (to manage a particular doc, if you have a
mixed bag of them for some reason:

```
apos.docs.getManager(doc.type)
```

Cursors are another important read. The `find` methods of the pieces,
custom-pages, etc. modules all return cursors, which are like mongo
cursors but extensible and very flexible:

http://unstable.apostrophenow.org/reference/apostrophe-docs/server-apostrophe-cursor.html

* Extensibility, Modifiability

Too big to just pop off an email response, but these are vastly better
in 2.0.0. These things you want to do, you can do them. (: Check out
the apostrophe-pieces API reference; it's easy to extend any of those
methods with the super pattern, which you're familiar with.

The improved chooser for picking things? We did that. (: You get to
click "Browse" and use the "manage" modal for that piece type as a
full-powered chooser. The columns of the list view are configurable,
the sorts are configurable, it's very cool. And we need to document it
more, more, more.

Also all that gross "boilerplate" for a new module, or a module that
extends another, is just gone.

lib/modules/products/index.js can look like:

```javascript
module.exports = {
extend: 'apostrophe-pieces',
name: 'product',
label: 'Product',
construct: function(self, options) {
// Override some methods, use the super pattern like always
}
};
```

All the browser-side code works much the same way.

To get a sense check out this recent HOWTO:

http://unstable.apostrophenow.org/howtos/extending-the-pieces-editor-modal.html

* Intrusiveness

We cut this way back. Fewer unnecessary divs, no weirdness like
apos-center still floating around.

All the modules follow the same pattern, all the widget types come
from a module, overriding widget.html works the same for all of them.

* * *

Fotis, I hope this response is helpful and eases both your mind and
those of other A2 developers. We hear you and we're grateful for such
a thoughtful and detailed response.

Now... go check out 2.0.0 (:

unstable.apostrophenow.org

>> email to apostrophecm...@googlegroups.com.

>> For more options, visit https://groups.google.com/d/optout.
>
>

> --
> You received this message because you are subscribed to the Google Groups

> "apostrophenow" group.

> To unsubscribe from this group and stop receiving emails from it, send an

> email to apostropheno...@googlegroups.com.

>
> For more options, visit https://groups.google.com/d/optout.

--


THOMAS BOUTELL, SUPPORT LEAD
P'UNK AVENUE | (215) 755-1330 | punkave.com