Textpattern CMS support forum
You are not logged in. Register | Login | Help
- Topics: Active | Unanswered
[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
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
Offline
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 algps(),cs(),pcs()- more…
Yeah, much like that. Will try out your formatting suggestions.
Code is topiary
Offline
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.
Agreed; couldCan’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.
- 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
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
Offline
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
Re: [wiki] Core Function Reference
Jeff, here’s the link to the Textpattern function index at PHPXref.
We Love TXP . TXP Themes . TXP Tags . TXP Planet . TXP Make
Offline
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
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
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
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
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