Sephiroth

Developer Documentation

Recommended Posts

Hi usually I don't create topics until i feel they are necessary but this is really become a chore for me in development phase, The issue is the Developer Documentation; its really hard for me to get the necessary information I need. I have to go through various topics and navigate through conversations just to find what am looking for.

Just today I was looking for the API for the PageField to save a page as a value and I have no luck, I feel this can increase development time to those new to Processwire. i found out there's a site called wiki.processwire.com but it's been last updated 2012 and the cheatsheet.processwire.com doesn't go indepth enough for me to understand what's going on. 

ADVICE:

I feel we can have a documentation page where users can edit and contribute text to it gradually, there's recipe.processwire.com but its still not enough, it would cool to have something like this http://framework.zend.com/manual/current/en/index.html

Forgive my rant I come from a country where electricity is not guaranteed so its a big deal for me when I have to spend alot of time looking for information. I don't mind contributing examples or if we can find ways to allow community update the wiki.processwire.com.

THANKS GUY 

Still looking for how to use code to save a PageFieldtype with another page

  • Like 3

Share this post


Link to post
Share on other sites

Well I think you're right about this. In my opinion the wiki should be removed and it's helpful articles should become Tutorials in the Tutorial section (I think Joss is already working on this somehow?).

I guess with 2.6 or 3.0 there will be a new complete documentation but at the moment Ryan is busy enough making ProcessWire more awesome every day :)

Maybe there should be some kind of documentation team. Just an idea.

  • Like 1

Share this post


Link to post
Share on other sites

Btw.: A good way to find help is (at least for more advanced users) to directly look into the core files: https://github.com/ryancramerdesign/ProcessWire/blob/master/wire/modules/Fieldtype/FieldtypePage.module

And I guess you can just do something like:

<?php
// the page containing the page field
$mainPage = $pages->get('1234');

$mainPage->pagefieldName = $pages->get('4321'); // assign another page

$mainPage->save();

?>
  • Like 1

Share this post


Link to post
Share on other sites

Well I think you're right about this. In my opinion the wiki should be removed and it's helpful articles should become Tutorials in the Tutorial section (I think Joss is already working on this somehow?).

I guess with 2.6 or 3.0 there will be a new complete documentation but at the moment Ryan is busy enough making ProcessWire more awesome every day :)

Maybe there should be some kind of documentation team. Just an idea.

Exactly because I know how much Ryan is working on Processwire Core, is why I felt the documentation can be created by a team, I like the idea of a documentation team, if you got ways to execute this ideas please let me know so i can join, I can sacrifice some Skyrim time to do this.

  • Like 3

Share this post


Link to post
Share on other sites

I can relate to that. What bugs me often are the arbitrary jumps from http://processwire.com/docs/ to http://processwire.com/api/. The sidebar is so similar I don't think anyone even noticing these the first time. And in /api/ are so many hidden informations, which serve for a great baseline understanding of processwire, it's a pity they are so hidden.

About your FieldtypePage issue:

$pagefield = $page->related;
// Objects are passed as reference
// so this is the same as $page->related->add()
$pagefield->add( $pages->get("id=1234") ); 
$page->of(false);
$page->save();
  • Like 1

Share this post


Link to post
Share on other sites

@LostKobrakai: That bugs me to. But it has an "historical" reason: Some time ago API was an own point instead of Docs. Then Tuts and Dev Directory and the Blog, etc. came and we decided to make a link called "Docs" in the header. And API is same as before (otherwise the urls would have changed) and only got a link from the Docs sidebar instead of the header... But I think we're working on that :)

Share this post


Link to post
Share on other sites

I've guessed for that reason, but it's still a bit cluncy and with all of those great redirecting modules out here, it shouldn't be a great issue. Even after some time of using ProcessWire I'm still using the api sites on a daily basis. Only with my recent dive into module developement for pw I switched more and more to just look at the code on github / locally. But until you've interalised the modularity and oop priciples I think it's impossible to find answers there.

Share this post


Link to post
Share on other sites

@LostKobrakai @Nico Thanks alot guys sometimes its hard following the source since some methods are magical so its hard to pinpoint but am getting there. thanks

Share this post


Link to post
Share on other sites

The extended cheatsheet I setup quite a while ago would be perfect for those small examples for the API. Unfortunately the team refused to work on it since 1.5 year. Kinda sad as I spent many hours setting all up with workflow and such and each contributor has assigned a section.

Instead they prefer to respond in the forums 100 times the same. /rant over

  • Like 2

Share this post


Link to post
Share on other sites

@soma: this looks pretty nice but I think the documentation should be part of the main site and the cheatsheet should link to the docs pages. Shouldn't it?

Share this post


Link to post
Share on other sites

The extended cheatsheet I setup quite a while ago would be perfect for those small examples for the API. Unfortunately the team refused to work on it since 1.5 year. Kinda sad as I spent many hours setting all up with workflow and such and each contributor has assigned a section.

Instead they prefer to respond in the forums 100 times the same. /rant over

I gave you a "like" but you know what I mean - you are right.

I think there are a few things like that where a truly community-wide effort might help but your particular case is something more experienced members would be better helping with - although there are simpler parts too that others could chip in with.

In the case of the cheatsheet though soma, if you want to look over mine and ryan's pages that are awaiting review in the backend of the cheatsheet I would happily look over yours or we can split them somehow? There are 17 awaiting review and I don't think they would take too long to approve :)

  • Like 1

Share this post


Link to post
Share on other sites

@soma: I can do stuff too, but you have to tell me first what's the difference between those pages and the documentation pages :)

Share this post


Link to post
Share on other sites

@soma: I can do stuff too, but you have to tell me first what's the difference between those pages and the documentation pages :)

Thanks Nico. I think we got all sections assigned to someone already but sure there's always enough to do. I'll have a look when I get to it.

A good question. The difference is that it's more of a reference with examples for each API method or property. The documentation pages are good to get understanding with examples and the cheatsheet is built from the content from there (just without examples). Idea is to extend it and provide more examples for stuff that isn't covered on the docu pages. See it as a more comprehensive and compact version like the php api pages with comments and cross references. 

Most important maybe is that we all can edit those and have some cool options that the docu pages don't have.

  • Like 2

Share this post


Link to post
Share on other sites

Nico, feel free to help me with $file and $image parts... :)

  • Like 1

Share this post


Link to post
Share on other sites

I'm reviving this thread! This needs to gain traction!

I would really like to improve the docs, and I propose we start a documentation team.

I've already started a Google Spreadsheet (open for comments, PM me your Google account for modification access) with a tree of the current documentation with comments and improvements (see What's in and What's missing or needs improving tabs). Note that this is mostly made from memory and notes I have laying around. I haven't personally read 100% of the documentation (these days I just go straight to the source code), so I would appreciate your input/feedback/additions.

I suppose a spreadsheet might not be the best way to go at it, let me know how you'd like to organize things moving forward.

Cheers!

  • Like 5

Share this post


Link to post
Share on other sites

Looks nice. When i'm back in Germany i'm going to do some additions (or would like to make some :))

  • Like 1

Share this post


Link to post
Share on other sites

Keep the API-Documentation in mind: http://processwire.com/apigen/

Regarding this, Ryan did originally raise some points about the (intended) public API vs. features intended for internal use only, which this tool doesn't always distinguish properly. I'm going to agree with those points, and perhaps even take them one step further, by stating that in my opinion this is not useful at all, and should be deleted to avoid unnecessary confusion. Considering that it was last generated for ProcessWire 2.2, it would seem that I'm not entirely alone with that opinion either :)

If you need to know how specific object behaves or what methods it has, this provides very little (or none at all) benefit over looking it up from GitHub where you'll also see the code, changelog, etc.

  • Like 1

Share this post


Link to post
Share on other sites

@teppo, I've seen this comment already, and I must somewhat disagree. Some of us do work this deep when working on modules for example and some parts of the architecture could use quick explaining, without entering into a full on object/method reference. I wouldn't say it's a priority at all right now though, other higher level things need documentation badly before this.. 

Share this post


Link to post
Share on other sites

@Pierre-Luc: that's good to know, thanks! Perhaps it's that I've missed what this thing is all about, or just a question of workflow, but at the very least this thing should be properly kept up to date, preferably automatically. It should also allow switching between versions, while we're at it. Only thing worse than no documentation is unreliable documentation.

Anyway, even if we forget the public vs. private API argument for a moment, what's the real benefit this thing provides in comparison to, say, GitHub repository? Is it a presentational thing, i.e. a list of objects (and another of exceptions etc.) instead of files in directories, tables instead of DocBlocks, no code instead of full code, and so on?

If you could explain exactly what the extra value is that ApiGen provides, I would be happy to see if I could, perhaps, help with the "keeping it up to date" issue, so that it becomes actually reliable. Personally I'd prefer more people working directly with code instead of adding weird layers on top of it, but if there's demand for something like this, at least we should do it properly :)

Share this post


Link to post
Share on other sites

http://www.codersgrid.com/2013/07/15/daux-io-documentation-generator-using-markdown/

This is something we should look at it uses markdown and it could leverage on Github meaning the snippets could be updated via Github just like processwire recipe, its highly depressing switching from looking at source code to scanning forums for answers. and if not some of the community can take it in our hands to create a separate site for documentation just like the processwire recipe. 

P.S it would be better if documentation were contributed by us, that way the Processwire Dev team can work on the updates of Processwire rather than being bothered about documentation.

Share this post


Link to post
Share on other sites

Create an account or sign in to comment

You need to be a member in order to leave a comment

Create an account

Sign up for a new account in our community. It's easy!

Register a new account

Sign in

Already have an account? Sign in here.

Sign In Now

  • Recently Browsing   0 members

    No registered users viewing this page.

  • Similar Content

    • By Sten
      Hello,
      I'd like to participate to a documentation about the page flow in PW. I am still a beginner and still have difficulties to see the big picture but I could help to the writing.
      What is the flow when a page is displayed or created ? It would be fine to draw a scheme with every stage in which one can add hooks. Something to describe the flow in time.
      May be it exists.
      page
      |
      fields
      |
      template
      What do you think ?
    • By Orkun
      Hi Guys
      It would be awesome when all the resource about processwire (tutorials, docs, cheatsheet, recipes, videos, api, faq etc...) would be unified on one documentation website called "docs.processwire.com".
      The new site would gather infos & data from these resources:
      https://processwire-recipes.com/ http://processwire.tv/ https://www.pwtuts.com/ https://processwire.com/docs/ http://cheatsheet.processwire.com/ and would unified it on the final site https://docs.processwire.com.
      I think It is far more better to have one endpoint for all the processwire resources & wisdom then mutliple sites. This way it is far more easier to get into the processwire world and choosing processwire as the next main cms for further projects.
       
      The Documentation Site could perhaps look like this (it is just a mockup, so don't expect to much from me ):

       
    • By netcarver
      Part 1 of a 2 part Module & Service Reveal.
      I'm currently working on a new module: ModuleReleaseNotes that was inspired by the work I originally did on making Ryan's ProcessWireUpgrades module "release" aware. In the end, I decided to ditch the approach I was originally taking and instead work on a module that hooked in to the UpgradeConfirmation dialog and the module edit page.
      Aims
      My aims for this module are as follows...
      Make discovery of a module's changes prior to an upgrade a trivial task. Make breaking changes very obvious. Make reading of a module's support documentation post-install a trivial task. Make module authors start to think about how they can improve the change discovery process for their modules. Make sure the display of information from the module support files/commit messages doesn't introduce a vulnerability. Looking at these in turn...
      Making discovery of a module's changes prior to upgrade a trivial task.
      This is done by adding a "What's changed section" to the upgrade confirmation dialog.  This section takes a best-effort approach to showing what's changed between the installed version and the updated version that's available via the module repository.
      At present, it is only able to talk to github-hosted repositories in order to ask them for the release notes, the changelog file (if present) and a list of commits between the git tag that matches the installed version and the tag matching the latest version.
      It will display the Release Notes (if the author is using the feature), else it will display the commits between the tags (if tagging is used by the module author) else it will show the changelog file (if present) else it will show the latest N commits on the master branch (N, of course, being configurable to your liking.)
      An example of the Github Release Notes pulled in for you, taken from Mike Rockett's TextformatterTypographer Module...

      An example of a tag-to-tag commit list from the same module...

      An example of a changelog - formatted to show just the changes (formatting styles will change)...

      Finally, an example of a fallback list of commits - sorry Adrian ...

       
      Making breaking changes obvious.
      This is currently done by searching for a set of configurable search strings. Later versions may be able to support breaking change detection via use of Semantic Versioning - but this may require some way of signalling the use of this versioning standard on a module-by-module basis.
      For now, then, you can customise the default set of change markers. Here I have added my own alias to the list of breaking change markers and the changes section of the changelog is styled accordingly (these will be improved)...

       
      Make reading of a module's support documentation, post-install, a trivial task.
      This is done by making some of the support files (like the README, CHANGELOG and LICENSE files) readable from the module's information/settings screen. There is an option to control the initial open/closed state of this section...

      Here is Tracy's README file from within the module settings page... 

       
      Make module authors start to think about how they can improve the change discovery process for their modules.
      There are notes in each of the sections displayed on the upgrade confirmation page that help authors use each of the features...

       
      Make sure display of external information doesn't introduce a vulnerability.
      This is an ongoing concern, and is the thing that is most likely to delay or prevent this module's release lead to this module's withdrawl should a vulnerability be found. Currently, output is formatted either via Markdown + HTML Purifier (if it was originally a Markdown file) or via htmlspecialchars() if it has come from a plaintext file.
      If you discover a vulnerability, please get in contact with me via the forum PM system.
       
      Ongoing...
      For now, I've concentrated on integration with GitHub, as most people use that platform to host their code. I know a few people are hosting their repositories with BitBucket (PWFoo comes to mind) and some with GitLab (Mike Rockett?) and I would eventually like to have adaptor implementations for these providers (and perhaps GitKraken) - but for now, GitHub rules and the other hosts are unsupported.
       
      Links
      Github: ModuleReleaseNotes
      PW Module Repository: Here
    • By ethanbeyer
      Today I noticed the Fieldgroups class is missing from the reference, and I wasn't sure why! Does anyone know?
      Also, I feel like the docs would be easier to parse/navigate if the API Variables were shown alongside the class they were an instance of.
      Config ($config) Field Fields ($fields) Fieldgroup Fieldgroups ($fieldgroups) Fieldtype HookEvent Inputfield InputfieldWrapper MarkupPagerNav Module Modules ($modules) ... Page ($page) Pages ($pages) ... I'm also aware of the API Gen reference page (https://processwire.com/apigen/index.html), which is more robust, but a little harder to parse.