Go to main content

Textpattern CMS support forum

You are not logged in. Register | Login | Help

#1 2009-10-04 15:22:38

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,793
Website

[wiki] Core Function Reference

Just added Core Function Reference category. This is a draft to see what others think of the idea, formatting, and organization. Currently contains one sub-cat and one function. Function definition modeled more or less after the online PHP function documentation.


Code is topiary

Offline

#2 2009-10-04 16:42:49

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,821
Website GitHub

Re: [wiki] Core Function Reference

Nice idea. Kind of a selective PHPdoc system, except this one’s manually created ;-)

If this is to be useful and maintainable, the categories will need to be well-defined as I’d prefer not to have a ‘miscellaneous’ wiki category to house interesting functions in the catch-all txplib_misc.php. Which functions would you intend to highlight? Off the top of my head:

  • the major DB functions, as you have started
  • the ones to create output (doTag(), doLabel(), etc)
  • the form functions (fInput(), text_area(), checkbox(), radio())
  • string/attribute manipulation like maybe lAtts(), do_list(), et al
  • gps(), cs(), pcs()
  • more…

With regards page layout, how about this as a suggestion:

 string [[safe_pfx]] ( string ''$table'' )

Prepares the table name for use in [[safe_query]].

'''''source''''' — lib/txplib_db.php

==Parameters==

; table
: standard Txp table name (without PFX prefix).

The Parameters bit — rendered as a definition list — matches the attributes list in the tag reference. I found (by accident) that putting a space in front of the function signature seems to render it in a fixed-width font. Whether that’s an improvement is in the eye of the beholder. Using the double square brackets around the function name is easier to remember — and 2 chars fewer — than the triple apostrophe as well as being easier to remember, since all other tags will have double square brackets round them as wiki links. Can’t decide what to do with the source bit though; it looks a little out of place where it is now. Like it has no trousers to wear to the dance. Hmmmm.

Last edited by Bloke (2009-10-04 17:00:56)


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#3 2009-10-04 17:01:36

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,793
Website

Re: [wiki] Core Function Reference

Bloke wrote:

Nice idea. Kind of a selective PHPdoc system, except this one’s manually created ;-)

Well, would it make more sense to adapt to PHPdoc? Devs open to the idea? I can imagine it’s been discussed before.

  • the major DB functions, as you have started
  • the ones to create output (doTag(), doLabel(), etc)
  • the form functions (fInput(), text_area(), checkbox(), radio())
  • string/attribute manipulation like maybe lAtts(), do_list(), et al
  • gps(), cs(), pcs()
  • more…

Yeah, much like that. Will try out your formatting suggestions.


Code is topiary

Offline

#4 2009-10-04 17:09:04

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,793
Website

Re: [wiki] Core Function Reference

Bloke wrote:

The Parameters bit — rendered as a definition list — matches the attributes list in the tag reference.

Great — thanks. I know little about MW syntax.

I found (by accident) that putting a space in front of the function signature seems to render it in a fixed-width font. Whether that’s an improvement is in the eye of the beholder.

I’m thinking save fixed-width for code examples. As you say, a matter of taste.

Using the double square brackets around the function name is easier to remember — and 2 chars fewer — than the triple apostrophe

Didn’t know that one either.

Can’t decide what to do with the source bit though; it looks a little out of place where it is now. Like it has no trousers to wear to the dance.

Agreed; could
  • have its own section (seems overkill)
  • join in with the Changelog
  • or Notes

Edit: or leave it off entirely, given that I’ve just added links in the Changelog.

Last edited by jsoo (2009-10-04 17:10:51)


Code is topiary

Offline

#5 2009-10-04 17:54:35

Bloke
Developer
From: Leeds, UK
Registered: 2006-01-29
Posts: 11,821
Website GitHub

Re: [wiki] Core Function Reference

jsoo wrote:

or leave it off entirely, given that I’ve just added links in the Changelog.

Nice one; page lookin’ good. I assume you’re intending to write up soething about PFX then?


The smd plugin menagerie — for when you need one more gribble of power from Textpattern. Bleeding-edge code available on GitHub.

Txp Builders – finely-crafted code, design and Txp

Online

#6 2009-10-04 18:14:48

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,793
Website

Re: [wiki] Core Function Reference

I figured it would be good practice to go ahead and make all mentions of other constants, classes, and functions wiki links, so that if/when those pages get added the existing pages will have proper links. And also as a reminder to add those pages when you see a red link.


Code is topiary

Offline

#7 2009-10-04 19:09:06

hcgtv
Plugin Author
From: Key Largo, Florida
Registered: 2005-11-29
Posts: 2,722
Website

Re: [wiki] Core Function Reference

Jeff, here’s the link to the Textpattern function index at PHPXref.

Offline

#8 2009-10-04 19:51:46

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,793
Website

Re: [wiki] Core Function Reference

Thanks Bert: I had just added a link to the top level of PHPxref/textpattern in the “mini-nav”.


Code is topiary

Offline

#9 2009-10-04 20:08:11

JanDW
Plugin Author
From: Providence, RI, USA
Registered: 2008-07-18
Posts: 327
Website

Re: [wiki] Core Function Reference

Shouldn’t this be linked to from the extending textpattern page?

Glad to see that more info on developing plugins is being added to textbook. Thanks!

Last edited by JanDW (2009-10-04 20:09:01)


TXPDream – A Textpattern Tag Library for Adobe Dreamweaver. (updated for 4.2.0) | jdw_if_ajax – Only serve certain parts of a page when requested with AJAX

Offline

#10 2009-10-04 20:17:00

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,793
Website

Re: [wiki] Core Function Reference

JanDW wrote:

Shouldn’t this be linked to from the extending textpattern page?

That’s the idea; I was waiting to see how this would be received. No point starting unless there is some agreement as to whether to proceed, how to format each page, and willingness to write up the functions (which does take a bit of time).

Edit: In particular, Stef’s mention of PHPDoc brings up an entirely different direction in which such efforts might be usefully made.

Last edited by jsoo (2009-10-04 20:18:30)


Code is topiary

Offline

#11 2009-10-04 20:20:09

JanDW
Plugin Author
From: Providence, RI, USA
Registered: 2008-07-18
Posts: 327
Website

Re: [wiki] Core Function Reference

and willingness to write up the functions (which does take a bit of time).

I’m of the sort that needs to read those pages rather than write them. Still, let me know if there is something I can do.


TXPDream – A Textpattern Tag Library for Adobe Dreamweaver. (updated for 4.2.0) | jdw_if_ajax – Only serve certain parts of a page when requested with AJAX

Offline

#12 2009-10-04 20:40:14

jsoo
Plugin Author
From: NC, USA
Registered: 2004-11-15
Posts: 1,793
Website

Re: [wiki] Core Function Reference

Those who are best qualified to write them are the devs, whose time is better spent on coding. So, IF this is a viable project, it will be up to us lesser lights to do the grunt work. If it gets off the ground I expect the devs would check in occasionally to make sure things are reasonably correct.

All of which is to say, you might find it a helpful learning exercise to write up a function—would make you take a thorough look to figure out what it’s doing in detail. That in turn would sharpen your familiarity with the code base and your skills at tracing through it. So feel free!


Code is topiary

Offline

Board footer

Powered by FluxBB