We need help to update our tutorials to 3.0 APIs and the new default theme

[Ingo Schommer]

Hey everybody! If you always wanted to contribute to core,

but didn't feel up to writing the PHP for it, here's a great way you can help out:

We need somebody to go through our five introductory tutorials, and make

sure they are up to date with SS3, as well as using the new default theme:

http://open.silverstripe.org/ticket/7023

These tutorials are the entry point for many of our developers,

so you have the chance to make a big impact to the overall product.

Note: We're not looking for a complete rewrite, simply maintenance and clarification.

If you are keen, please let me know and we can go through the details!

Thanks!

Ingo

[Andy Adiwidjaja]

Hi Ingo,

I really would like to work on this but I think I won't be fast... if completion in "the next weeks" is ok, I can do this. 

I like that the tutorial starts from a bare template at the moment and creates a menu from scratch. Maybe we should

create a new tutorial skin to start from?

I have many more ideas but I would first concentrate on making it work. The most annoying work will be making

the new screenshots...

Andy

[Gordon Anderson]

Just a thought but could Capybara be used to automate the screenshotting?  It would mean writing a script to drive the browser but it would mean that future 're screenshotting' could be done more easily

G

[Ingo Schommer]

Hey Andy, I think "next weeks" is a fine,
as long as it doesn't get into "next months" (plural)
Don't you love open source deadline agreements? ;)

It'd be good to see some work in progress fairly soon though.
And I'm still open to other offers if they can start sooner,
it sounds like a big enough task to benefit from collaboration.

On starting with a bare theme, my motivation is mostly the
maintenance overhead - I don't want to maintain
a fork of the 'simple' theme just for the tutorials.
This forking lead us to the current situation of having
two visually quite distinct default skins (blackcandy and tutorial) in the first place.

But also: The theme markup is simple enough to use as a tutorial,
and overall I think that SS newbies will learn faster if they can
tinker with (smaller) existing stuff anyway, than if they have to copypaste
template fragments from a website into the right place.

As far as CSS goes, I would suggest that we remove all
related instructions from the tutorials - its not about learning
CSS after all, and even the 'simple' theme CSS is way too complex for that.
We should limit our focus to filesystem conventions, and how its included in SS.

Sent with Sparrow (http://www.sparrowmailapp.com/?sig)

> --
> You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.
> To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/BziuzeSKXXsJ.
> To post to this group, send email to silverst...@googlegroups.com (mailto:silverst...@googlegroups.com).
> To unsubscribe from this group, send email to silverstripe-d...@googlegroups.com (mailto:silverstripe-d...@googlegroups.com).
> For more options, visit this group at http://groups.google.com/group/silverstripe-dev?hl=en.

[Sam Minnée]

On 15/03/2012, at 6:21 AM, Gordon Anderson wrote:

> Just a thought but could Capybara be used to automate the screenshotting? It would mean writing a script to drive the browser but it would mean that future 're screenshotting' could be done more easily

PHP-WebDriver is another option for that, which has the advantage of being in PHP.

It would end up being a lot more work than just taking screenshots, but you're right about maintainability. If someone was keen to try one of these tools out, they might want to work with Andy to produce a suitable set of scripts.

[Andy Adiwidjaja]

Hi!

Am Mittwoch, 14. März 2012 18:23:27 UTC+1 schrieb Ingo Schommer:

Hey Andy, I think "next weeks" is a fine,  
as long as it doesn't get into "next months" (plural)
Don't you love open source deadline agreements? ;)

It'd be good to see some work in progress fairly soon though.

I'm planning to make it work first and then make improvements. I will start asap.

On starting with a bare theme, my motivation is mostly the maintenance overhead - I don't want to maintain a fork of the 'simple' theme just for the tutorials.This forking lead us to the current situation of having two visually quite distinct default skins (blackcandy and tutorial) in the first place.

Ok.

 

But also: The theme markup is simple enough to use as a tutorial, and overall I think that SS newbies will learn faster if they can tinker with (smaller) existing stuff anyway, than if they have to copypaste template fragments from a website into the right place.

Ok, I have some experience with students learning silverstripe with the tutorials. They began to understood the structure of the silverstripe objects when they wrote code themselves, even when they copied it. But I can show that on top of the theme, maybe with a content listing.

 

As far as CSS goes, I would suggest that we remove all related instructions from the tutorials - its not about learning CSS after all, and even the 'simple' theme CSS is way too complex for that. We should limit our focus to filesystem conventions, and how its included in SS.

Agreed.

Cheers,

Andy

[Andy Adiwidjaja]

@Sam, @Gordon:

I don't think automatic screenshots will help here. The screenshots must be annotated and cropped. I will try to make updating screens easier in the future.

Cheers,

Andy

[Andy Adiwidjaja]

One question: Is the theme that is used on http://doc.silverstripe.org/ available somewhere so I can preview the documentation with the theme? 

Another question: The simple theme uses the <% control %>-Syntax. Is this intentionally to support ss2.4? Should this be changed, as I want

to write about the new syntax?

Andy

Am Mittwoch, 14. März 2012 14:48:34 UTC+1 schrieb Ingo Schommer:

[Sam Minnée]

I think that's because the simple theme developer didn't know about the new controls. We should patch the theme to use the 3.0 commands.

[Ingo Schommer]

Done: https://github.com/silverstripe-themes/silverstripe-simple/commit/44cec3d0ac439cc54f6881b045932a7cf0be6f4e

> --
> You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.

[Andy Adiwidjaja]

Am Donnerstag, 15. März 2012 11:29:52 UTC+1 schrieb Ingo Schommer:

Done: https://github.com/silverstripe-themes/silverstripe-simple/commit/44cec3d0ac439cc54f6881b045932a7cf0be6f4e

Great :-)

What about the doc.silverstripe.org-Theme, is it available somewhere? I would like to test different image sizes and to use features like the information boxes:

<div class="notice" markdown='1'>

</div>

Andy

[Ingo Schommer]

Hey Andy,

It uses the sapphiredocs module: https://github.com/silverstripe/silverstripe-sapphiredocs
The doc.ss.org codebase itself isn't open source (simply because we didn't have time or demand for it),
but it uses more or less standard sapphiredocs, so you should be able to get close enough.

Ingo

> --
> You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.

> To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/2A1mN_gpqkIJ.

[Andy Adiwidjaja]

Hi,

Am Donnerstag, 15. März 2012 22:34:18 UTC+1 schrieb Ingo Schommer:

It uses the sapphiredocs module: https://github.com/silverstripe/silverstripe-sapphiredocs
The doc.ss.org codebase itself isn't open source (simply because we didn't have time or demand for it),
but it uses more or less standard sapphiredocs, so you should be able to get close enough.

Ah, sorry. I installed the sapphiredocs module, but I did it wrong (with a theme) so I got a plain view - I thought this is intentional and I am missing a theme.

Now I got it, it's really close enough.

Andy

[Cam Findlay]

Hey Andi, 

Looks like I started to work on the same stuff at the last hackfest.

How far have you got with the tutorials? I am happy to collab on this but what will be the best way to work? 

I have a github branch I started working in: https://github.com/cam-findlay/sapphire/tree/7023-tutorials but if you have done the same perhaps I can simply be a second eye over your work which is always a good thing.

[Andy Adiwidjaja]

Hey Cam,

no problem, I mainly worked on the child-theme topic which I saw as a precondition for the tutorial. But overall I hadn't enough time last week. So, I'm happy with any help. I looked at your branch and it looks good, I will integrate it into my branch.

Andy

[Cam Findlay]

Cheers... ok I will keep working on the tutorials section then... in a similar boat... Uni assignments coming up this week but should be free to make progress next week... keep an eye on the branch :)

I can see some of the tutorials need to be changed slightly due to the new layouts etc and that the page editing panels are now split up into separate menu items.

Will keep you posted here, maybe get together on Skype to go over things soon?

[camfindlay]

RIghto, just finished up tutorial one for SS3.0 https://github.com/cam-findlay/sapphire/blob/7023-tutorials/docs/en/tutorials/1-building-a-basic-site.md

Actually took quite a while as the changes in the Page and Edit page layouts in the CMS from 2.4 is quite different and had to be reworded.

Same with the idea that we are not starting from a blank template... again lots of rewording and dropping out irrelevant stuff... I can see this might continue to take a while but at least a little progress made.

[Ingo Schommer]

Hey Cam,

It's really coming together, thanks for your awesome work!

Added some inline comments on the commit:

https://github.com/cam-findlay/sapphire/commit/d63b06849d17051bf79e27bb1dbb9819e1cec6cd#L0L26

It "flows" and reads well in general - although I think you can still

combine sentences into larger paragraphs

to visually form more logical units - it looks quite disjoint

and "bullet-pointy" at the moment.

The (sub-)headlines need some work, it should be easy to determine

what the article is about by scanning through them. 

The hierarchy is also a bit off, e.g. "Highlighting the current page"

shouldn't be on the same level as "the navigation system"

(its a sub-chapter of it).

Anybody else keen to review?

I would be particularly interested in feedback

from any of your dev friends who have a working

knowledge of PHP, but haven't used SS yet.

All in all, very promising :)

Ingo

--
You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.

To view this discussion on the web visit https://groups.google.com/d/msg/silverstripe-dev/-/sQNZxUx7k6AJ.
To post to this group, send email to silverst...@googlegroups.com.
To unsubscribe from this group, send email to silverstripe-d...@googlegroups.com.

[Ingo Schommer]

Hey Cam and Andi, how's the tutorial rewrite coming along?

You know that you can split up and just work on different tutorials at the same time, right? :)

I've written up a ticket with some further details: http://open.silverstripe.org/ticket/7157

That was done by quickly browsing through the tutorials, but looking forward to

your suggestions how we can demonstrate the core concepts more effectively -

we don't have to rigidly follow every code example from the old tutorials

if it doesn't make sense any more in 3.0. One example is tutorial 5:
It should really use ModelAdmin to show off GridField (formerly ComplexTableField),

because its such a popular feature in SilverStripe.

Thanks

Ingo

[Andy Adiwidjaja]

Hey Ingo and Cam,

sorry that I was so slow in responding and working, this is the first week I can work on this topic again. I think we have to work in incremental steps: 

1. Make the tutorial work for 3.0 (remove wrong and deprecated stuff, make use of simple theme, work on the issues on the ticket)

2. Make better use of the core concepts

3. Add features, do things differently

For example I think it is necessary to introduce a DropdownField in tutorial 2 but this is level 2. I think it is better to use the child theme stuff but this is level 3. I will try to push the level 1 work on every tutorial in the next days.

I reviewed Cam's version of tutorial 1 and everything works.

I have completed my first edit on tutorial 2:

https://github.com/adiwidjaja/sapphire/blob/7023-tutorials/docs/en/tutorials/2-extending-a-basic-site.md

Any feedback is welcome, I have some technical questions:

- How should I merge Cam's changes into my fork? I tried a git merge, but this leads to a "merge commit". Or should we both make separated pull requests?

- Tutorial 2 sets the icons in the cms. Should I copy these icons from the tutorial theme to the simple theme? Or to the docs-folder?

- Is the usage of DataObject::get_one still correct? In this case it is not needed at all but I will think about a better use of the datamodel-api later.

@Cam: I will continue with tutorial 4.

@Ingo: Maybe we could couple tutorial 3 and 5 by implementing student applications as the form example? As we have to rewrite tutorial 5 completely - maybe we should implement a completely different application like the job board example in the book?

Cheers

Andy

[Ingo Schommer]

Hello Andy,

Thanks, tutorial 2 is looking great :)

On 18/04/2012, at 1:39 AM, Andy Adiwidjaja wrote:

sorry that I was so slow in responding and working, this is the first week I can work on this topic again. I think we have to work in incremental steps: 

That's OK, the ticket I wrote can be split up if its more convenient.

I have completed my first edit on tutorial 2:

https://github.com/adiwidjaja/sapphire/blob/7023-tutorials/docs/en/tutorials/2-extending-a-basic-site.md

Left some inline comments :)

Any feedback is welcome, I have some technical questions:

- How should I merge Cam's changes into my fork? I tried a git merge, but this leads to a "merge commit". Or should we both make separated pull requests?

Merge commits are fine, they help git figure out the best merging stategy going forward.

It means we can't easily merge your two codebases in isolation, but that's acceptable.

Might be more efficient to work on one remote though (one of you can give the other push rights on his repo fork).

- Tutorial 2 sets the icons in the cms. Should I copy these icons from the tutorial theme to the simple theme? Or to the docs-folder?

Hmm, yeah lets copy them into the theme, as it makes copypaste easier.

Means we'll have to do the same dance when using a different theme for the tutorial in the future, but that's fine.

We could also link to http://www.famfamfam.com/lab/icons/silk/ for more icons.

- Is the usage of DataObject::get_one still correct? In this case it is not needed at all but I will think about a better use of the datamodel-api later.

Yep, should be DataList::create().

@Ingo: Maybe we could couple tutorial 3 and 5 by implementing student applications as the form example? As we have to rewrite tutorial 5 completely - maybe we should implement a completely different application like the job board example in the book?

Yep, they're both fairly close to realistic use cases (registration/submission and catalogue-style).

Feel free to get inspired by code from the book,

just don't copypaste anything directly (I would let you, but my publisher won't…).

Ingo

[camfindlay]

Good stuff Andy, 

I'll review your tutorial 2 as well... time is pretty short for me at the moment with uni assessments due again but I'll start looking into tut 3 and 5. As Ingo mentions perhaps some sort of joint 3/5 tutorial might be good... perhaps we can come up with a scenario that demonstrates the same concepts but leaves the user with something tangible they can use for their own site?

Job board could work, are there any other commonly used things that might be better? I guess we just need to make sure that each of the data-relationships are represented (has_one, has_many and many_many).

How about some sort of community events posting thing? has_one - date, time & location, has_many - attendees (that can rsvp via the form we set up in tut3), many_many - tags?

The merge stuff between doc content will be an interesting one... perhaps we strip the entire docs folder out into its own repo (maybe on the silverstripe github) with push rights for those of us working on it? then a final move of the content back into sapphire/framework once it is deemed useable by the public?

[Ingo Schommer]

Hey guys,

On 19/04/2012, at 11:27 PM, camfindlay wrote:

I'll review your tutorial 2 as well... time is pretty short for me at the moment with uni assessments due again but I'll start looking into tut 3 and 5. As Ingo mentions perhaps some sort of joint 3/5 tutorial might be good... perhaps we can come up with a scenario that demonstrates the same concepts but leaves the user with something tangible they can use for their own site?

The reason tutorial 5 exists is that we developed ModelAdmin and related features after 2.0,

and didn't want to alter the previous tutorials. Its an important enough aspect of the system

to bring it in earlier if it fits into the "story" of the tutorial IMHO.

Job board could work, are there any other commonly used things that might be better? I guess we just need to make sure that each of the data-relationships are represented (has_one, has_many and many_many).

How about some sort of community events posting thing? has_one - date, time & location, has_many - attendees (that can rsvp via the form we set up in tut3), many_many - tags?

One thing I learned the hard way writing the book: Write up the code examples first,

its very easy to come up with examples which require too much code to explain them,

watering down the message. E.g. you don't want to set up another RSVP form submission

if you've already explained the form API in an earlier tutorial, stuff like that.

I also think its important to choose a domain model that's clear enough so you 

can explain it in a single sentence - there should be no logical ambiguity

about if something's a has_many or many_many for example.

The merge stuff between doc content will be an interesting one... perhaps we strip the entire docs folder out into its own repo (maybe on the silverstripe github) with push rights for those of us working on it? then a final move of the content back into sapphire/framework once it is deemed useable by the public?

You won't have any merge conflicts when merging in code changes,

only from files you both modified (in /docs). That's why I suggested

to decide on one repo and give the respective other commit access.

I would advise against stripping it out into its own repo,

as you won't be able to submit (and update) pull requests to us easily.

Ingo

[camfindlay]

My time is super limited now till the end of June... I'll see what I can get done... perhaps if we just keep it all simple and just update the existing tutorials as they are to incorporate the new SS3.0 features.

Perhaps a full review of this section would be good once things have stablised with 3.0 and some better tutorials which showcase and teach the changes to the framework could be looked at.

I'm happy to write and explain if someone can come up with the multi-part tutorial code example.

C

[Sam Minnée]

Hey Cam,

Completely understand that you're time is limited. If you have any work in progress, perhaps you want to submit a pull request, so that someone else can help work on it as well if they have time?

Thanks,
Sam

[camfindlay]

Yeah sure thing Sam... any work that gets it a bit closer to finished is good... I still pine for a more open wiki system for this kind of stuff but none-the-less I think Andy and myself have got a good start on this stuff and I'll keep jumping in where I can.

I will have a good block of free to to dedicate to some of this stuff end of June if there is still thing to be done or written then... until then it's head in books.

Interestingly enough I have been researching a concept called "Communities of Practice" and used you guys as an example in one of the assessments... getting a good theoretical and practical dose of what makes communities like ours tick ;) Perhaps that will come in handy down the line.

C

[Andy Adiwidjaja]

Hello Ingo,

sorry that I didn't answer for a long time. Now I'm back on track and I have
- finished tutorial 2
- finished tutorial 4
- merged tutorial 1 from Cam
- included your comments on tutorial 1

all in https://github.com/adiwidjaja/sapphire/tree/7023-tutorials (I
had some strange merge/history correction error).

I saw your comment about the old logo too late, I will work on all
screens again later (I renamed all screens to find them easier next
time).

Now I will think about tutorial 3 & 5 but I would propose that I make
a pull request with these changes first.

Thanks,


Andy

> --
> You received this message because you are subscribed to the Google Groups
> "SilverStripe Core Development" group.
> To view this discussion on the web visit

> https://groups.google.com/d/msg/silverstripe-dev/-/ASmWNlaWcuwJ.

>
> To post to this group, send email to silverst...@googlegroups.com.
> To unsubscribe from this group, send email to
> silverstripe-d...@googlegroups.com.
> For more options, visit this group at
> http://groups.google.com/group/silverstripe-dev?hl=en.

--
Andy Adiwidjaja // Partner Strategie & IT

Adiwidjaja Teamworks GmbH // Aktive und Interaktive Kommunikation
Königstraße 16 // 22926 Ahrensburg // www.adiwidjaja.com

a...@adiwidjaja.com // 04102 208456 // 0179 5456465

[Ingo Schommer]

Hey Andy,

I've looked through your changes, and commented inline a bit,
overall its looking great - thank you very much!
If you could look at those two comments of mine,
we're happy to accept the pull request.
Good idea to treat tutorial 3 and five as separate requests,
no reason to delay the merge of existing work.

Don't sweat the accuracy of the CMS screenshots too much
(beta1 vs beta3 etc), IMHO its much more important to get the content right.

Ingo

[Ingo Schommer]

Hello Andy, Cam, and everybody interested in making docs better,

Naomi has rewritten Tutorial 4, and I've created a whole new Tutorial 5.

They're a pull request waiting for peer review:

https://github.com/silverstripe/sapphire/pull/657

Does anybody have feedback before we merge this back in ~24h?

Note: You can click through from the commit pages in github

to "view file at...", which shows you an approximation of the Markdown

display, which might be easier to read+review.

Thanks

Ingo

>> To post to this group, send email to silverstripe-dev@googlegroups.com.

>> To unsubscribe from this group, send email to

>> silverstripe-dev+unsubscribe@googlegroups.com.

>> For more options, visit this group at
>> http://groups.google.com/group/silverstripe-dev?hl=en.
>
>
>
> --
> Andy Adiwidjaja // Partner Strategie & IT
>
> Adiwidjaja Teamworks GmbH // Aktive und Interaktive Kommunikation
> Königstraße 16 // 22926 Ahrensburg // www.adiwidjaja.com
>
> a...@adiwidjaja.com // 04102 208456 // 0179 5456465
>
> --
> You received this message because you are subscribed to the Google Groups "SilverStripe Core Development" group.

> To post to this group, send email to silverstripe-dev@googlegroups.com.
> To unsubscribe from this group, send email to silverstripe-dev+unsubscribe@googlegroups.com.

[Andy Adiwidjaja]

Hi Ingo,

On Mon, Aug 6, 2012 at 9:48 AM, Ingo Schommer <ingo.s...@gmail.com> wrote:
> Naomi has rewritten Tutorial 4, and I've created a whole new Tutorial 5.
> They're a pull request waiting for peer review:
> https://github.com/silverstripe/sapphire/pull/657
> Does anybody have feedback before we merge this back in ~24h?
> Note: You can click through from the commit pages in github
> to "view file at...", which shows you an approximation of the Markdown
> display, which might be easier to read+review.

I read everything, unfortunately I have no time to try tutorial 5 in
the next hours. The only thing I found:

"Replace the student template code in both Project.ss and
ProjectHolder.ss templates with the new placeholder, $Info. With this
pattern, you can increase code reuse across templates."

You should make this explicit, "the student template code" is possibly
not understood by everyone.

Everything else looks good.


Andy

[Ingo Schommer]

Done, and merged :)