Merge pull request #1042 from hydephp/update-InMemoryPage-class

emmadesilva · web-flow · commit 52cef93c3b79 · 2023-02-15T21:24:13.000+01:00
Update InMemoryPage class documentation
diff --git a/packages/framework/src/Pages/InMemoryPage.php b/packages/framework/src/Pages/InMemoryPage.php
@@ -20,9 +20,8 @@
  * usually within the boot method of the package's service provider, or a page collection callback in an extension.
  * This is because these pages cannot be discovered by the auto discovery process as there's no source files to parse.
  *
- * This class is especially useful for one-off pages, like pagination pages and the like.
- * But if your usage grows, or if you need file-based autodiscovery, you may benefit
- * from creating a custom page class instead, as that will give you full control.
+ * This class is especially useful for one-off custom pages. But if your usage grows, or if you want to utilize
+ * Hyde autodiscovery, you may benefit from creating a custom page class instead, as that will give you full control.
  */
 class InMemoryPage extends HydePage
 {
@@ -45,19 +44,20 @@ public static function make(string $identifier = '', FrontMatter|array $matter =
     }
 
     /**
-     * Create a new virtual page instance.
+     * Create a new in-memory/virtual page instance.
      *
-     * The virtual page class offers two content options. You can either pass a string to the $contents parameter,
+     * The in-memory page class offers two content options. You can either pass a string to the $contents parameter,
      * Hyde will then save that literally as the page's contents. Alternatively, you can pass a view name to the $view parameter,
      * and Hyde will use that view to render the page contents with the supplied front matter during the static site build process.
      *
      * Note that $contents take precedence over $view, so if you pass both, only $contents will be used.
      * You can also register a macro with the name 'compile' to overload the default compile method.
      *
      * @param  string  $identifier  The identifier of the page. This is used to generate the route key which is used to create the output filename.
-     *                              If the identifier for a virtual page is "foo/bar" the page will be saved to "_site/foo/bar.html".
+     *                              If the identifier for an in-memory page is "foo/bar" the page will be saved to "_site/foo/bar.html".
+     *                              You can then also use the route helper to get a link to it by using the route key "foo/bar".
      * @param  \Hyde\Markdown\Models\FrontMatter|array  $matter  The front matter of the page. When using the Blade view rendering option,
-     *                                                           this will be passed to the view.
+     *                                                           all this data will be passed to the view rendering engine.
      * @param  string  $contents  The contents of the page. This will be saved as-is to the output file.
      * @param  string  $view  The view key or Blade file for the view to use to render the page contents.
      */
@@ -81,6 +81,10 @@ public function getBladeView(): string
 
     /**
      * Get the contents that will be saved to disk for this page.
+     *
+     * In order to make your virtual page easy to use we provide a few options for how the page can be compiled.
+     * If you want even more control, you can register a macro with the name 'compile' to overload the method,
+     * or simply extend the class and override the method yourself, either in a standard or anonymous class.
      */
     public function compile(): string
     {
@@ -89,13 +93,16 @@ public function compile(): string
         }
 
         if (! $this->getContents() && $this->getBladeView()) {
-            if (str_ends_with($this->view, '.blade.php')) {
+            if (str_ends_with($this->getBladeView(), '.blade.php')) {
+                // If the view key is for a Blade file path, we'll use the anonymous view compiler to compile it.
+                // This allows you to use any arbitrary file, without needing to register its namespace or directory.
                 return AnonymousViewCompiler::call($this->getBladeView(), $this->matter->toArray());
             }
 
             return View::make($this->getBladeView(), $this->matter->toArray())->render();
         }
 
+        // If there's no macro or view configured, we'll just return the contents as-is.
         return $this->getContents();
     }
 

Original file line number	Diff line number	Diff line change
`@@ -20,9 +20,8 @@`
`20`	`20`	`* usually within the boot method of the package's service provider, or a page collection callback in an extension.`
`21`	`21`	`* This is because these pages cannot be discovered by the auto discovery process as there's no source files to parse.`
`22`	`22`	`*`
`23`		`- * This class is especially useful for one-off pages, like pagination pages and the like.`
`24`		`- * But if your usage grows, or if you need file-based autodiscovery, you may benefit`
`25`		`- * from creating a custom page class instead, as that will give you full control.`
	`23`	`+ * This class is especially useful for one-off custom pages. But if your usage grows, or if you want to utilize`
	`24`	`+ * Hyde autodiscovery, you may benefit from creating a custom page class instead, as that will give you full control.`
`26`	`25`	`*/`
`27`	`26`	`class InMemoryPage extends HydePage`
`28`	`27`	`{`
`@@ -45,19 +44,20 @@ public static function make(string $identifier = '', FrontMatter\|array $matter =`
`45`	`44`	`}`
`46`	`45`
`47`	`46`	`/**`
`48`		`- * Create a new virtual page instance.`
	`47`	`+ * Create a new in-memory/virtual page instance.`
`49`	`48`	`*`
`50`		`- * The virtual page class offers two content options. You can either pass a string to the $contents parameter,`
	`49`	`+ * The in-memory page class offers two content options. You can either pass a string to the $contents parameter,`
`51`	`50`	`* Hyde will then save that literally as the page's contents. Alternatively, you can pass a view name to the $view parameter,`
`52`	`51`	`* and Hyde will use that view to render the page contents with the supplied front matter during the static site build process.`
`53`	`52`	`*`
`54`	`53`	`* Note that $contents take precedence over $view, so if you pass both, only $contents will be used.`
`55`	`54`	`* You can also register a macro with the name 'compile' to overload the default compile method.`
`56`	`55`	`*`
`57`	`56`	`* @param string $identifier The identifier of the page. This is used to generate the route key which is used to create the output filename.`
`58`		`- * If the identifier for a virtual page is "foo/bar" the page will be saved to "_site/foo/bar.html".`
	`57`	`+ * If the identifier for an in-memory page is "foo/bar" the page will be saved to "_site/foo/bar.html".`
	`58`	`+ * You can then also use the route helper to get a link to it by using the route key "foo/bar".`
`59`	`59`	`* @param \Hyde\Markdown\Models\FrontMatter\|array $matter The front matter of the page. When using the Blade view rendering option,`
`60`		`- * this will be passed to the view.`
	`60`	`+ * all this data will be passed to the view rendering engine.`
`61`	`61`	`* @param string $contents The contents of the page. This will be saved as-is to the output file.`
`62`	`62`	`* @param string $view The view key or Blade file for the view to use to render the page contents.`
`63`	`63`	`*/`
`@@ -81,6 +81,10 @@ public function getBladeView(): string`
`81`	`81`
`82`	`82`	`/**`
`83`	`83`	`* Get the contents that will be saved to disk for this page.`
	`84`	`+ *`
	`85`	`+ * In order to make your virtual page easy to use we provide a few options for how the page can be compiled.`
	`86`	`+ * If you want even more control, you can register a macro with the name 'compile' to overload the method,`
	`87`	`+ * or simply extend the class and override the method yourself, either in a standard or anonymous class.`
`84`	`88`	`*/`
`85`	`89`	`public function compile(): string`
`86`	`90`	`{`
`@@ -89,13 +93,16 @@ public function compile(): string`
`89`	`93`	`}`
`90`	`94`
`91`	`95`	`if (! $this->getContents() && $this->getBladeView()) {`
`92`		`- if (str_ends_with($this->view, '.blade.php')) {`
	`96`	`+ if (str_ends_with($this->getBladeView(), '.blade.php')) {`
	`97`	`+ // If the view key is for a Blade file path, we'll use the anonymous view compiler to compile it.`
	`98`	`+ // This allows you to use any arbitrary file, without needing to register its namespace or directory.`
`93`	`99`	`return AnonymousViewCompiler::call($this->getBladeView(), $this->matter->toArray());`
`94`	`100`	`}`
`95`	`101`
`96`	`102`	`return View::make($this->getBladeView(), $this->matter->toArray())->render();`
`97`	`103`	`}`
`98`	`104`
	`105`	`+ // If there's no macro or view configured, we'll just return the contents as-is.`
`99`	`106`	`return $this->getContents();`
`100`	`107`	`}`
`101`	`108`