App development review

[Aiwa]

Now that I have written 3 apps, of varying complexity, for IPS4, I thought I'd share some feedback.  

• If you're using something that's documented, things go very smoothly.  A pretty simple app with notifications, e-mails, a handful of settings, and a simple pruning task only took 45 minutes and about 30 lines of code.  That's a tremendous improvement over IPS3.   
• If you're using an endpoint that's not documented, you're left to the mercy of the content in the forums and usually a 4 tiered structure of classes you have to bounce back and forth between to understand
  • 'Sending a PM'... how to create the PM, add users to it, etc.  I fiddled with it for an hour, got the PM to send, stored in the database, but couldn't open it in the users inbox without getting an Exception thrown.  Gave up and went a route that didn't involve PM's.  
  • 'Creating a Table' in the ACP with data from your DB table.  That one went pretty smooth without documentation, but I'm still running into bugs because I missed a step somewhere.  I can search, but nothing sorts correctly.  

Extensions:

I'm sure there are many that are quite useful, but the text in the Developer Center just doesn't do them justice.  It would be nice to see a documentation page that lists all of the available extensions and goes into a bit more detail about what each extension will do for you, and what limitations it may have.  

• memberForm, I assumed that added a form to the front end for user entered settings specific for my app.  That's not the case, it is to members as groupForm is to groups.  An ACP settings tab for admin control of any settings not stored in Profile Fields.  Which now means you need to hook into the profile fields form to add your member settings rather than being able to do this with an extension.  Unless I missed something, but another reason for a bit better documentation.  
• The template files for extensions are great, and do give you a bit more information, but they also lack the verbiage required to give a full understanding of what the extension will really DO for you.  

Front End Output:

The default styles and java-script functions available are simply amazing.  Hats off to @Rikki for building such a robust library.  I've yet to run into a situation where the core CSS classes for layouts / grids / type / etc, don't meet my needs.  And the added controls using the java-script ips.ui. make up for all of my fringe cases with layouts.  The ips.ui. extensions also make working with modals / etc super simple.  Something that took us writing our own java-script module for before, now just takes two parameters embedded in your HTML.  Also, the CSS and JS documentation, while not entirely complete - some examples missing, is very well done.  I always have both open in another tab for quick reference.  

Bottom line:

Developing for 4.x is MUCH more powerful and faster than 3.x.  Including the built in CSS styles and the javascript ips.ui.* methods I haven't run into an issue yet that those can't solve for me.  

If I had to pick one place to focus on, it would be Documentation of the IPS PHP Framework.  I know that can seem like a daunting task with as many built in classes there are in IPS4, but they need to be tackled one at a time, one foot in front of the other.  More complete documentation is one thing that will grow the Marketplace and the development community by lowering the learning curve to develop for IPS4, which was quite high when writing my first app.  

Suggestion:

Many of the 3rd party developers here have written documentation for IPS4 and posted it around the forums.  I'd like to see that data leveraged and used in the IPS guides.  I'm not saying create the wild-west community guides section.  What I'm saying is allow 3rd party developers to submit guides to IPS to review and validate for best practice.  Re-format to meet your technical publication standards and start filling in gaps in your documentation.  Maybe even give those developers submitting guides some kind of distinction as validation of their help solving a problem that's plagued the development community around IPS4 for over a year.

[Simon Woods]

Awesome suggestion. These forums are full of all kinds of good advice and useful knowledge, even exceptional at times; it would be to the benefit of so many people if IPS could find a way to utilise this information, across the range of all topics and issues.

[Rikki]

Thanks for the feedback We're currently building a whole new developer area that will have properly-categorized docs (focused on the backend). There's a lot to document of course, so it's something that we'll build up over time, but we'll be launching the first version in the near future.

[Aiwa]

5 minutes ago, Rikki said:

Thanks for the feedback We're currently building a whole new developer area that will have properly-categorized docs (focused on the backend). There's a lot to document of course, so it's something that we'll build up over time, but we'll be launching the first version in the near future.

Indeed there is a lot to document, and appreciate that it takes a considerable amount of time.  

Can't wait to see what you guys are cooking up!

[Dylan Riggs]

Thanks for this Aiwa, I would have to most certainly agree with you about @Rikki - And I love how he's been engaged with useful Theme Tips. I'm mostly engaged with all the front-end work and haven't had any issues so far, and with his Theme Tips, (especially his last one with converting to RGB) has really made my life easier.

It'd be great to see more real life examples on more of the back end being done, something like "Code Tips" following standards and useful examples from the backend spectrum and how IPS is doing certain things with it's software that we, as communities can use as examples to expand upon. I want to tackle IPS4 PHP framework, but I'm definitely a document person and don't like "jumping" in unless 100% necessary or searches return no results.

@Aiwa - How has searching been for you when doing your research when documentation wasn't available? Do you ever discuss anything with another 3rd party developer off the site using something like Skype to ask/answer questions? I did this for IPS3 and always bugged Marcher or CodingJungle as I didn't have documentation, and searches didn't return anything.

What documentation I do see currently, already seems to reference 4.0 - how accurate is it with 4.1 being out and expanding? Just trying to get a feel of everything as I plan on jumping in very soon. I have a few apps I want to update!

As for your suggestion, pretty pretty please do this @Lindy

 

 

[Aiwa]

@Dylan Riggs If it wasn't in the documentation, and I had to search the forums, I found about 1/3rd of what I was looking for.  So worse odds than rolling the dice.  In some cases there were topics that had questions asked, but no one answered.  

I did get A LOT of help in the developer assistance and contributor chat forums when I did run into a problem that I couldn't quite figure out by looking at the code and other apps.  I didn't speak to any devs offline, just used the forums here.  At a minimum, I threw out some code that may help someone else down the road.  

I don't think there were to many differences in the guides from 4.0 to 4.1.  But as always, if you run into an issue, use one of the forums above and someone will come around to help.

 

[HeadStand]

I think the documentation isn't as incomplete as people think, it's just really really hard to find things. For example, "follow" functionality is buried in "Introduction to Content Items". Some reorganization would do wonders.

That being said, there are some areas that could use some work. Extensions is one of them - the only thing preventing me from writing that help article is because I myself am not entirely certain about all of it.  

[Rikki]

1 hour ago, HeadStand said:

I think the documentation isn't as incomplete as people think, it's just really really hard to find things. For example, "follow" functionality is buried in "Introduction to Content Items". Some reorganization would do wonders.

Yes, agreed - our existing documentation is from a PDF document created for IPS developers, so it's not very efficient to get around on the web version. We're working on it still - it'll be a vast improvement  

[Florent Cadet]

Open the eyes please

Type IPS Documentation on Google :

You can see "4.0 Developer Documentation", click it and worth it :

Quote

4.0 Developer Documentation

There's no guides in this category yet

!!!!

To understand plugin architecture, I had to read community forum because IPS documentation is related to IPS 3.x architecture

This is not serious...