[IDEA] Place generated files in PHPDoc @package and @subpackage dirs

[anselmdk]

Just an idea: I think it would be great if you could define package and subpackage on components and pages in your project.yml file.
The idea is for Silversmith then being able to place files in different directories.

Example, project.yml:

PageTypes:
    MyPage:
        Package: mysite
        Subpackage: pagetypes
    MyBasePage:
        Package: mysite
        Subpackage: basepagetypes
    MyOtherPage: 
        Package: myothermodule
        Subpackage: pagetypes

Example, code structure:

mysite/code/pagetypes/MyPage.php
mysite/code/basepagetypes/MyPage.php
myothermodule/code/basepagetypes/MyOtherPage.php

Furthermore this would allow for automatically generating php doc in the file head.

[dospuntocero]

great idea!

francisco arenas
dospuntocero.cl
fb.me/dospuntocero.cl

2013/2/17 Anselm Christophersen [email protected]

Just an idea: I think it would be great if you could define package and
subpackage on components and pages in your project.yml file.
The idea is for Silversmith then being able to place files in different
directories.

Example, project.yml:

PageTypes:
MyPage:
Package: mysite
Subpackage: pagetypes
MyBasePage:
Package: mysite
Subpackage: basepagetypes
MyOtherPage:
Package: myothermodule
Subpackage: pagetypes

Example, code structure:

mysite/code/pagetypes/MyPage.php
mysite/code/basepagetypes/MyPage.php
myothermodule/code/basepagetypes/MyOtherPage.php

Furthermore this would allow for automatically generating php doc in the
file head.

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/9.

[anselmdk]

I'm currently working on a rather large project, having 30+ Silversmith generated files, and here it would really be a great help to be able to split the project into sub package directories.

[unclecheese]

It's a really good idea. I'm concerned about one limitation of the SilverSmith YAML spec that's been bugging me for some time. You can't really group nodes. For instance, the "Tab" attribute of a field becomes really redundant -- the same way your "Package" node does in the example. Ideally, I'd like to see the spec updated so that both of these things are possible:

NewsPage:
  Tabs:
    Tab1:
       SomeField: {CMSField: Text}
       AnotherField: {CMSField: Text}
    Tab2:
      Foo: {CMSField: Text}

Likewise:

PageTypes:
  Packages:
    News:
      NewsPage:
        Fields:
          Foo: {CMSField: Text}

Thoughts?

[dospuntocero]

then probably the word packages is not the best... because you can't fill
of folders inside the code folder (almost sure about this... am i wrong?)

what about a different kind of root node?

Modules:
News:
NewsPage:
Fields:
Foo: {CMSField: Text}

...

i like the idea of the tabs too.

Silversmith already handles the creation of modules, but it stops there... maybe if you control the module from the project.yml itself can be a really deal breaker!

francisco arenas
dospuntocero.cl
fb.me/dospuntocero.cl

2013/2/17 unclecheese [email protected]

It's a really good idea. I'm concerned about one limitation of the
SilverSmith YAML spec that's been bugging me for some time. You can't
really group nodes. For instance, the "Tab" attribute of a field becomes
really redundant -- the same way your "Package" node does in the example.
Ideally, I'd like to see the spec updated so that both of these things are
possible:

NewsPage:
Tabs:
Tab1:
SomeField: {CMSField: Text}
AnotherField: {CMSField: Text}
Tab2:
Foo: {CMSField: Text}

Likewise:

PageTypes:
Packages:
News:
NewsPage:
Fields:
Foo: {CMSField: Text}

Thoughts?

—
Reply to this email directly or view it on GitHubhttps://github.com//issues/9#issuecomment-13701088.

[anselmdk]

Good idea. I'm myself not a fan of redundant code.
Just to clarify, the way I understand the way the PHPDoc package and subpackage is used in the SS core is that a package is a module while a subpackage can be a subdivision of code in the module.

@dospuntocero yes you can have subdirectories inside of code. I do that all the time. Usually I make directories like pagetypes, models, controllers, but in some projects I think it would make more sense to divide the project into the actual page subsections, hence this thread.

Thinking about it, I'm not sure it would be a good idea to allow creating files in others modules than the current module, as it could open up for a lot of complications as one module could accidentally overwrite files in another module.

So, based on that (and your proposals), I'm considering the following:

PageTypes:
    Subpackages:
        News:
            NewsPage:
                Fields:
                    Foo: {CMSField: Text}
Components:
    Subpackages:
        News:
            NewsItem:

Possibly this shouldn't be forced. Maybe we could by default add page types to a pagetypes directory, and components (DataObjects) to a components directory.

So the simple syntax could still be supported:

PageTypes:
    HomePage:
        Fields:
            Foo: {CMSField: Text}
Components:
    RotatingImage:
        Fields:
            Foo: {CMSField: Text}

...and combined that could look like this:

PageTypes:
    HomePage:
        Fields:
            Foo: {CMSField: Text}
    Subpackages:
        News:
            NewsPage:
                Fields:
                    Foo: {CMSField: Text}
Components:
    RotatingImage:
        Fields:
            Foo: {CMSField: Text}
    Subpackages:
        News:
            NewsItem:

I'm thinking we could do something similar for tabs.
Here HomePage would be placed in mysite/code/pagetypes/, and NewsPage would be placed in mysite/code/news/. RotatingImage would be placed in mysite/code/components/, while NewsItem would be placed in mysite/code/news.

Does that make sense?

Furthermore, if we want to support auto generating PHPDoc document headers, the package name could either be added in a configuration file, or by adding another root node before PageTypes and Components

Package:
    Name: 'Mysite'
    Description: 'This is the code for the ... site'
PageTypes:
    ...
Components:
    ...

Thinking further, this could be a great helper for/when auto generating project documentation.