The word “project” is used to refer to the overall site (what is referred to when running composer create-project, and is also used to refer to the back-end/code side of the Project (the project-directory). I’ll use the capitalized version of “Project” to refer to the former, and lower-case version “project” to refer to the later.

There are two general parts to a Project. The theme and the project. The theme is everything that is involved with rendering the UI of the site, while the project is the code and configuration that supports the site - it does the back-end work. The organization of these is one of the most confusing parts of working with Silverstripe.

With the theme category, there is a further division between UI assets (css, images, javascript) and templates. UI assets are static files that the templates use to render a page, organized by file type. The theme template files are .ss files, an extension of the .php file type, and used as a template for HTML markup (HTML mixed with PHP code). The folder names, templates, Includes, and Layout are required. The other names are user-supplied or customary.

There are two ways to organize the files in a theme.

###named-theme organization###

When using a named-theme organization, the public/web-accessible resources and the templates live under the named-theme folder (e.g. /themes/mytheme). To make these resources web-accessible, symbolic links are created under /public that point at the theme’s front-end files (see under /public/_resources/themes). The theme templates are also stored in the named-theme folder. You can see an example of this by examining the folders under /themes/simple.

###project-as-a-theme organization###

When using the project-as-a-theme organization, the Silverstripe install is devoted to one project with one theme. The public/web-accessible resources live under /public, and are obviously web-accessible as they are under /public. The templates share the project-directory /app. This is especially confusing, as theme related files (...templates/...) are placed in the project-folder (/app/...). This is the organization we will continue working with.

The project category centers around its project folder /app. The configuration files are stored under _config and the code is stored under src.

The project name for the site is specified in the /app/_config/mysite.yml configuration file (it is strange to me that the configuration is itself under the /app folder). This the what is found in a default install. The documentation when describing how to rename a project specifies that you rename the folder (e.g. from mysite to app) and then rename the mysite.yml file to app.yml, then edit the project name in app.yml to “app”.

###Theme - front-end UI code###

####Theme - public/web-accessible resources####

    /public/css
    /public/images
    /public/javascript

####Theme - non-public/non-web-accessible resources - templates####

    /app/templates
    /app/templates/Includes
    /app/templates/Layout

###Back-end PHP code and configuration - project###

    /app
    /app/_config
    /app/src

Within /app/src there are typically pairs of .php files that form what is known as a page-type (e.g. Page.php and PageController.php). The Page.php file is known as the model and deals with the database access for the page-type, while PageController.php is a controller and deals with the request-response cycle of the site, pretty much a catch all for all the code that makes the site function. Both of these types have long inheritance chains that pull in functionality, and so the files themselves can be short with most of the behavior hidden. This is one of the framework parts of Silverstripe.

The theme is selected by editing /app/_config/theme.yml. The “project-as-a-theme” theme is known as “$default”, so in that configuration file, edit so that you have (which will mean deleting, or commenting out using the # character, the line with “simple”). This is also a confusing file - hard descriptions of what $public and $default are expanded to is hard to come by. $public relates in some way to /public, while $default relates to the project that uses project-as-a-theme organization.

    SilverStripe\View\SSViewer:
      themes:
        - '$public'
        - '$default'

So far we have

• Organization for the project, including a theme
• A page-type “Page” defined by the file pair Page.php and PageController.php. By default these are linked by the names.

We still lack a template and a page that renders using our page type and template.

In the next section we will look at the admin section where pages are defined (and stored in the database). After that, we will look at templates and end up with a functioning page - and hopefully a basic understanding of how the page is built.

References: [1] https://www.silverstripe.org/learn/lessons/v4/creating-your-first-project [2] https://www.silverstripe.org/learn/lessons/v4/working-with-multiple-templates-1