Mailing List Archive: Bricolage: users

Template Elements 101?

Index | Next | Previous | View Threaded

waldo at vqronline

Jan 30, 2008, 12:44 PM

Post #1 of 12 (7958 views)
Permalink

Template Elements 101?

Folks,

I've seen some really useful-looking template elements (or is it
"element templates"?) on both the Bricolage site [1] and Building
Brics [2], but I don't have the faintest clue of what to do with them.
I've downloaded a few, notably publish_daily_archive.mc, which I hope
to modify to create seasonal archives, one for each issue that we
publish quarterly.

Combing through my Bricolage install for *other* .mc files, figuring
that'd be the place to put it, I dropped it into /data/burn/comp/oc_1,
restarted Bricolage, and tried pulling it up under Template -> Find
Templates. It didn't show up. No problemo -- I'd just noticed Template
-> New Template, and figured I could add it through the web interface.
But then I was prompted to select from an existing list of element
types (book_profile, book_review, column, cover, etc.) I didn't want
any of those element types. I wanted to make a *new* element that's
none of these types. Maybe I needed to use Admin -> Publishing ->
Element Types to make a new element type and then use *that* to add a
new element template. I created a new "Issue" element type (of type
"story"). That went just fine, so I headed back to Template -> New
Template. I create a new template there, which ends up titled
issue.mc, but it fails with a dump of error messages that's all Greek
to me:

---cut---
Template compile failed: Error during compilation of <anonymous
component>: Global symbol "$action" requires explicit package name at
(eval 581) line 70, <GEN127> line 348. Stack: [/usr/lib/perl5/
site_perl/5.8.5/HTML/Mason/Interp.pm:631] [/usr/local/bricolage/lib/
Bric/Util/Burner/Mason.pm:355] [/usr/local/bricolage/lib/Bric/Util/
Burner.pm:1524] [/usr/local/bricolage/lib/Bric/App/Callback/Profile/
Template.pm:567] [/usr/local/bricolage/lib/Bric/App/Callback/Profile/
Template.pm:98] [/usr/lib/perl5/site_perl/5.8.5/Params/
CallbackRequest.pm:294] [/usr/lib/perl5/site_perl/5.8.5/MasonX/Interp/
WithCallbacks.pm:119] [/usr/lib/perl5/site_perl/5.8.5/HTML/Mason/
ApacheHandler.pm:869] [/usr/lib/perl5/site_perl/5.8.5/HTML/Mason/
ApacheHandler.pm:823] [/usr/local/bricolage/lib/Bric/App/Handler.pm:
314] [/dev/null:0]
---cut---

And that's where I hit a dead end, with no ideas for alternate
approaches and no apparent way forward.

The underlying problem, I suspect, is that I don't understand this
hierarchy of templates, and I don't know how to figure them out.
What's the difference between an element and an element type? A
template and a template element? I've read through the FAQs, the
Perl.org articles, and the mailing list archives, and though I may
have actually encountered an explanation somewhere along the line, I
just feel so confused that I'm not sure I understood them. Could
somebody point me to a resource where I could learn about all of this?

I feel more than a little foolish asking such elementary questions
here, so I have to remind myself that this is a general users list
and, despite the discussion generally being at a far higher level than
this, everybody had to learn this stuff at one time or another. :)

Best,
Waldo

[1] http://www.bricolage.cc/templates/
[2] https://www.buildingbrics.com/trac/browser

---
Virginia Quarterly Review
One West Range, Box 400223
University of Virginia
Charlottesville, VA 22904-4223

chris.schults at pccsea

Jan 30, 2008, 1:24 PM

Post #2 of 12 (7824 views)
Permalink

RE: Template Elements 101? [In reply to]

Waldo,

If you haven't already, read:

http://www.bricolage.cc/docs/current/api/Bric::ElementAdmin

Then, follow up with:

http://www.bricolage.cc/docs/current/api/Bric::Templates
http://www.bricolage.cc/docs/current/api/Bric::AdvTemplates

In short, you need to setup destinations, which is where files get
burned to. Then output channels, which dictate the file extension and
URI convention. Then assign each output channels to the appropriate
destination(s).

Then, create story element types and assign one or more output channels.
Then you can create field elements within the story elements. You can
then create (separately) container elements with their own field
elements and then add them as subelements to your story elements, as
well as other container elements.

At some point, you can start creating categories as well.

Then once you have story and container elements, you can start creating
templates for each element/category/output channel combination. Then
there are category and utility templates ... whee!

Reading (and rereading) the above helped me. So did trial and error, and
this list.

Good luck, and let us know if you have more questions after reading the
docs.

Chris

david at kineticode

Jan 31, 2008, 4:42 PM

Post #3 of 12 (7802 views)
Permalink

Re: Template Elements 101? [In reply to]

On Jan 30, 2008, at 12:44, Waldo Jaquith wrote:

> Combing through my Bricolage install for *other* .mc files, figuring
> that'd be the place to put it, I dropped it into /data/burn/comp/
> oc_1, restarted Bricolage, and tried pulling it up under Template ->
> Find Templates. It didn't show up. No problemo -- I'd just noticed
> Template -> New Template, and figured I could add it through the web
> interface. But then I was prompted to select from an existing list
> of element types (book_profile, book_review, column, cover, etc.) I
> didn't want any of those element types. I wanted to make a *new*
> element that's none of these types. Maybe I needed to use Admin ->
> Publishing -> Element Types to make a new element type and then use
> *that* to add a new element template.

Yes, that's it exactly.

> I created a new "Issue" element type (of type "story"). That went
> just fine, so I headed back to Template -> New Template. I create a
> new template there, which ends up titled issue.mc, but it fails with
> a dump of error messages that's all Greek to me:
>
> ---cut---
> Template compile failed: Error during compilation of <anonymous
> component>: Global symbol "$action" requires explicit package name
> at (eval 581) line 70, <GEN127> line 348. Stack: [/usr/lib/perl5/
> site_perl/5.8.5/HTML/Mason/Interp.pm:631]

What did the template look like?

> And that's where I hit a dead end, with no ideas for alternate
> approaches and no apparent way forward.
>
> The underlying problem, I suspect, is that I don't understand this
> hierarchy of templates, and I don't know how to figure them out.
> What's the difference between an element and an element type? A
> template and a template element? I've read through the FAQs, the
> Perl.org articles, and the mailing list archives, and though I may
> have actually encountered an explanation somewhere along the line, I
> just feel so confused that I'm not sure I understood them. Could
> somebody point me to a resource where I could learn about all of this?

I think Chris was spot-on here.

> I feel more than a little foolish asking such elementary questions
> here, so I have to remind myself that this is a general users list
> and, despite the discussion generally being at a far higher level
> than this, everybody had to learn this stuff at one time or
> another. :)

Absolutely.

Best,

David

david at kineticode

Jan 31, 2008, 4:44 PM

Post #4 of 12 (7770 views)
Permalink

Re: Template Elements 101? [In reply to]

On Jan 30, 2008, at 13:24, Schults, Chris wrote:

> In short, you need to setup destinations, which is where files get
> burned to. Then output channels, which dictate the file extension and
> URI convention. Then assign each output channels to the appropriate
> destination(s).
>
> Then, create story element types and assign one or more output
> channels.
> Then you can create field elements within the story elements. You can
> then create (separately) container elements with their own field
> elements and then add them as subelements to your story elements, as
> well as other container elements.
>
> At some point, you can start creating categories as well.
>
> Then once you have story and container elements, you can start
> creating
> templates for each element/category/output channel combination. Then
> there are category and utility templates ... whee!

Wow, that's the most succinct description I've ever read. We gotta get
you writing a users' manual, Chris! ;-)

Best,

David

chris.schults at pccsea

Jan 31, 2008, 4:54 PM

Post #5 of 12 (7803 views)
Permalink

RE: Template Elements 101? [In reply to]

> Wow, that's the most succinct description I've ever read. We
> gotta get
> you writing a users' manual, Chris! ;-)

Thanks, I just started training my team on using Bricolage, so this is
all fresh in my head. I'd volunteer, but right now I've got to focus on
implementing Bricolage and migrating content! Perhaps at a later date.
Until then, I'm happy to respond to questions on the list.

Chris

waldo at vqronline

Jan 31, 2008, 6:33 PM

Post #6 of 12 (7774 views)
Permalink

Re: Template Elements 101? [In reply to]

On Jan 31, 2008, at 7:42 PM, David E. Wheeler wrote:
>> I created a new "Issue" element type (of type "story"). That went
>> just fine, so I headed back to Template -> New Template. I create a
>> new template there, which ends up titled issue.mc, but it fails
>> with a dump of error messages that's all Greek to me:
>>
>> ---cut---
>> Template compile failed: Error during compilation of <anonymous
>> component>: Global symbol "$action" requires explicit package name
>> at (eval 581) line 70, <GEN127> line 348. Stack: [/usr/lib/perl5/
>> site_perl/5.8.5/HTML/Mason/Interp.pm:631]
>
> What did the template look like?

https://www.buildingbrics.com/trac/browser/trunk/utilities/publish_daily_archive.mc

And thank you, Chris, for providing a reading-order guide to the API
documentation. I haven't given those a whirl yet, but I intend to
tomorrow.

FWIW, the use of the term "burn" in documentation represents a
significant obstacle to new users. (Or at least to me. :) As best as I
can tell, this word is used by Bricoleurs to refer to the act of
generating a static file from a bit of dynamic content. It's a use of
the verb that I have never encountered anywhere else, and isn't
defined when it's used throughout Bricolage documentation.
Periodically providing a few contextual words of explanation would
really help.

Best,
Waldo

---
Virginia Quarterly Review
One West Range, Box 400223
University of Virginia
Charlottesville, VA 22904-4223

david at kineticode

Feb 1, 2008, 10:54 AM

Post #7 of 12 (7756 views)
Permalink

Re: Template Elements 101? [In reply to]

On Jan 31, 2008, at 18:33, Waldo Jaquith wrote:

> On Jan 31, 2008, at 7:42 PM, David E. Wheeler wrote:
>>> I created a new "Issue" element type (of type "story"). That went
>>> just fine, so I headed back to Template -> New Template. I create
>>> a new template there, which ends up titled issue.mc, but it fails
>>> with a dump of error messages that's all Greek to me:
>>>
>>> ---cut---
>>> Template compile failed: Error during compilation of <anonymous
>>> component>: Global symbol "$action" requires explicit package name
>>> at (eval 581) line 70, <GEN127> line 348. Stack: [/usr/lib/perl5/
>>> site_perl/5.8.5/HTML/Mason/Interp.pm:631]
>>
>> What did the template look like?
>
> https://www.buildingbrics.com/trac/browser/trunk/utilities/publish_daily_archive.mc

That's a bug. That tempate needs something like this:

<%init>
my $action $burner->get_mode == PUBLISH_MODE
? 'publish_another'
: 'preview_another';
</%init>

> And thank you, Chris, for providing a reading-order guide to the API
> documentation. I haven't given those a whirl yet, but I intend to
> tomorrow.
>
> FWIW, the use of the term "burn" in documentation represents a
> significant obstacle to new users. (Or at least to me. :) As best as
> I can tell, this word is used by Bricoleurs to refer to the act of
> generating a static file from a bit of dynamic content. It's a use
> of the verb that I have never encountered anywhere else, and isn't
> defined when it's used throughout Bricolage documentation.
> Periodically providing a few contextual words of explanation would
> really help.

Think of it like burning a CD. That's the usual analogy.

Best,

David

waldo at vqronline

Feb 1, 2008, 1:27 PM

Post #8 of 12 (7765 views)
Permalink

Re: Template Elements 101? [In reply to]

On Jan 30, 2008, at 4:24 PM, Schults, Chris wrote:
> If you haven't already, read:
>
> http://www.bricolage.cc/docs/current/api/Bric::ElementAdmin
>
> Then, follow up with:
>
> http://www.bricolage.cc/docs/current/api/Bric::Templates
> http://www.bricolage.cc/docs/current/api/Bric::AdvTemplates

Having now read these, I've got to say these things *definitely*
shouldn't be buried in the API browser. They're much too useful for
that. Not only would somebody have to be enormously lucky to stumble
across this trio of documents there, but the entire design and writing
of the API browser fairly screams "this is more information than
you'll possibly require when you're getting started."

I was about to suggest that they be put in the Documentation section
of the website, but lo and behold, they're in a part of the site that
I'd never, ever discovered. The menu design of the Bricolage site is
such that it's in no way obvious that the individual menu items
(about, documentation, support, development) are individually
selectable. It looks like they are merely containers, and only their
child elements can be selected. (This is, after all, precisely the
functionality of application menus in GUIs like Windows and Mac OS X,
the very functionality that's being emulated here.) Consequently, I
have never discovered the general Bricolage Documentation page <http://www.bricolage.cc/docs/
>. Perhaps a small UI tweak to the site menu would help with this?

Best,
Waldo

---
Virginia Quarterly Review
One West Range, Box 400223
University of Virginia
Charlottesville, VA 22904-4223

david at kineticode

Feb 2, 2008, 10:38 PM

Post #9 of 12 (7799 views)
Permalink

Re: Template Elements 101? [In reply to]

On Feb 1, 2008, at 13:27, Waldo Jaquith wrote:

> Having now read these, I've got to say these things *definitely*
> shouldn't be buried in the API browser. They're much too useful for
> that. Not only would somebody have to be enormously lucky to
> stumble across this trio of documents there, but the entire design
> and writing of the API browser fairly screams "this is more
> information than you'll possibly require when you're getting started."
>
> I was about to suggest that they be put in the Documentation section
> of the website, but lo and behold, they're in a part of the site
> that I'd never, ever discovered. The menu design of the Bricolage
> site is such that it's in no way obvious that the individual menu
> items (about, documentation, support, development) are individually
> selectable. It looks like they are merely containers, and only their
> child elements can be selected. (This is, after all, precisely the
> functionality of application menus in GUIs like Windows and Mac OS
> X, the very functionality that's being emulated here.) Consequently,
> I have never discovered the general Bricolage Documentation page <http://www.bricolage.cc/docs/
> >. Perhaps a small UI tweak to the site menu would help with this?

Your opportunity to do some template editing. ;-)

https://svn.bricolage.cc/bricolage.cc/

Best,

David

waldo at vqronline

Feb 3, 2008, 10:06 AM

Post #10 of 12 (7765 views)
Permalink

Re: Template Elements 101? [In reply to]

On Feb 3, 2008, at 1:38 AM, David E. Wheeler wrote:
> Your opportunity to do some template editing. ;-)
>
> https://svn.bricolage.cc/bricolage.cc/

You'll recall that what started this discussion was my confession that
I haven't the slightest idea of how to make heads or tails of
templates. I *really* don't think I ought to start off by trying to
edit bricolage.cc's templates. :)

FWIW, this appears to be a problem that would best handled via a CSS
modification or a redundant menu item addition, neither of which are
in the templates but, instead, exist as stories within Bricolage. (I
think.) So I wouldn't have access to those, anyhow.

Best,
Waldo

---
Virginia Quarterly Review
One West Range, Box 400223
University of Virginia
Charlottesville, VA 22904-4223

david at kineticode

Feb 3, 2008, 11:35 AM

Post #11 of 12 (7743 views)
Permalink

Re: Template Elements 101? [In reply to]

On Feb 3, 2008, at 10:06, Waldo Jaquith wrote:

> On Feb 3, 2008, at 1:38 AM, David E. Wheeler wrote:
>> Your opportunity to do some template editing. ;-)
>>
>> https://svn.bricolage.cc/bricolage.cc/
>
> You'll recall that what started this discussion was my confession
> that I haven't the slightest idea of how to make heads or tails of
> templates. I *really* don't think I ought to start off by trying to
> edit bricolage.cc's templates. :)
>
> FWIW, this appears to be a problem that would best handled via a CSS
> modification or a redundant menu item addition, neither of which are
> in the templates but, instead, exist as stories within Bricolage. (I
> think.) So I wouldn't have access to those, anyhow.

I would probably modify the template to add a menu item for the top-
level menu name, without modifying the story type. But maybe not.

David

phillip at communitybandwidth

Feb 4, 2008, 7:32 AM

Post #12 of 12 (7748 views)
Permalink

Re: Template Elements 101? [In reply to]

On 1-Feb-08, at 1:54 PM, David E. Wheeler wrote:

>>>
>>> What did the template look like?
>>
>> https://www.buildingbrics.com/trac/browser/trunk/utilities/publish_daily_archive.mc
>
> That's a bug. That tempate needs something like this:

Speaking of the new template repository, I should mention that the
fine folks at Gossamer Threads re-installed Trac 0.11b1 and added the
accountmanager plugin (which should solve a number of problems we were
having with it)).

Folks can register via the register link and that will allow them svn
access:
https://www.buildingbrics.com/trac/register

Over the next few weeks and months, I'm hoping that we can start
growing a nice collection of utility and site templates. And, of
course, if there are bugs in the existing templates, please feel free
to check-in new version. ;-)

Best,

Phillip.

--
Phillip Smith,
Simplifier of Technology
Community Bandwidth
http://www.communitybandwidth.ca

Index | Next | Previous | View Threaded

Interested in having your list archived? Contact Gossamer Threads