Publication
Many Querki Spaces are there so that you and others can organize and share information -- where the members of the Space are basically peers, and everything is readable as soon as it is created.
Some kinds of Spaces, though, are designed as information sources, aimed at readers. There are many kinds of these -- blogs, FAQs, cookbooks and many others. (For the examples below, we'll use a Cookbook.) They share a few characteristics:
- They have a distinct audience, separate from the people creating the Space.
- The creators want to finish the Things before showing them to the audience.
- The audience need ways to find out when these Things are created or edited.
For Spaces like this, Querki has Publication.
In a Space that uses Publication, you declare one or more Models to be "Publishable". When you create Instances of these Models, they can only be read by the editors of the Space. You work on the Instances until they are ready, and then you Publish them -- once they are Published, they become more widely visible, and they show on the Space's Recent Changes page.
Making a Model Publishable
All Publication functions use a common icon and button, which looks like this:
This button shows up whenever Publication is relevant; once you enable Publication, it shows up in more places.
The Pubication button is always visible in the Model Designer, in its title line:
Hovering over the button tells you whether this Model is Publishable or not. Pressing it takes you to the Edit Publication page:
If you check the checkbox at the top, the Model becomes Publishable, and more appears on the page:
Now you can control exactly who can read the Instances of this Model, both before and after you Publish them. (You can usually leave this alone. By default, the Members of the Space can see the Instances, and after Publication anybody can do so. This works in most cases, but you can change it if you need to.)
Editing and Publishing Instances
The most visible change, after you make a Model Publishable, is in how you edit the Instances. Creating or Editing an Instance always takes you to the Advanced Editor, which is similar to the Model Designer. (This is a temporary limitation; eventually, these will work with the ordinary Instance Editor, as usual.)
At the bottom of the Advanced Editor, where you would normally see the Done button, you instead see this:
First, there is a box where you can add some Change Notes. This is entirely optional, but if you add Change Notes they will be shown on the Recent Changes page. This allows you to talk about this Instance, and why it might be interesting to the readers. The Change Notes stick around from edit to edit, so you can edit the notes as you go; after you Publish this Instance, the Change Notes will be used, and then cleared.
Below that, instead of the simple Done button, you get a choice. You can stop editing for now, but leave this Instance unpublished; press this if you want to keep working on this Instance. Or, if the Instance is in good shape, you can Publish the Instance, which will make it visible and add it to the Recent Changes.
Instances of Publishable Models show the Publication button in the title bar. If the Instance isn't published yet, it looks like this -- notice the yellow Publication button, with a down-arrow:
Clicking on this button shows a drop-menu menu, from which you can Publish the Instance:
If the Instance has been published, the button looks like this, and doesn't do anything:
Updating Published Instances
Sometimes you need to make changes to a Published Instance. These changes are immediately visible (the upcoming Experiment feature will provide a way to make changes privately), but you still want to decide when you publicize those changes.
The bottom of the Editor for a Published Instance looks like this:
The Change Notes work the same as before Publication, but there are slightly different buttons. The first finishes editing, but doesn't Publish anything. The second Publishes an Update and adds it to the Recent Updates page. The third Publishes a minor Update -- this doesn't normally get shown on the Recent Changes page.
Recent Changes
If a Space has Publishable Models, the Space's homepage also shows the Publication button:
That button has a menu:
The Recent Changes page shows the changes in reverse chronological order:
The Recent Changes page is nothing more than a complex QL function:
[[_getChanges(reverse=true) ->
""{{well well-sm:
[[_date]]: [[_who]] [[_if(_publishedThings -> _isAnUpdate, ""updated"", ""published"")]]
[[_publishedThings -> _thing]]
[[_if(_not(_equals(_publishedThings -> _thing -> Name, _publishedThings -> _publishedName)), "" (then named [[_publishedThings -> _publishedName]]) "")]]
[[_if(_isMinorUpdate, ""(minor update)"")]] [[_if(_isNonEmpty(_publishedNotes), ""
[[_publishedNotes]]"")]]
}}""]]
The _getChanges() function produces all of the recent changes in this Space. It has a bunch of parameters, all of them optional:
since -- This should be a Date, and says when the list of Changes should start.until -- This should be the Date when the Changes end.duration -- This is of Duration Type, and says how long a period the list should cover. It is usually paired with until, so you can say, eg, "15 days, ending on June 10th".changesTo -- This should be one or more Models; if specified, only Instances of those Models will be included.includeMinor -- This should be true or false (by default it is false); if specified, Minor Updates will be included.reverse -- By default this is false, and the changes will be listed oldest-to-newest; if you set this to true, the newest changes will be on top.
There is nothing sacred about the built-in Recent Changes page; feel free to build a customized version of your own. If you set the Link Name of your customized page to recent-space-changes, that will become the page that is used when you click on the "Recent Changes" menu item from the Space's Publication menu.
These improvements are planned for the not-too-distant future:
- Spaces with Publishable Models will automatically have an RSS feed available, so that external readers can get the Recent Changes as a news feed.
- Updates will expose some way to get a "diff" showing more clearly what changed.
- The built-in Recent Changes page will get more powerful: at the least, it will let you page backwards through the history of the Space, choose to include Minor Updates, and let you view the history of the Space from the beginning.
