AWS support

igaster · igaster · commit 8e28e5fd972c · 2015-07-02T09:32:57.000+03:00
diff --git a/README.md b/README.md
@@ -12,11 +12,11 @@ Features:
 * Intergrates [Orchestra/Asset](http://orchestraplatform.com/docs/3.0/components/asset) to provide Asset dependencies managment
 * Your App & Views remain theme-agnostic. Include new themes with (almost) no modifications
 
-## How it works
+# How it works
 
 Very simple, you create a folder for each Theme in 'resources/views' and keep all your views seperated. The same goes for assets: create a folder for each theme in your 'public' directory. Set your active theme and you are done. The rest of your application remains theme-agnostic©, which means that when you `View::make('index')` you will access the `index.blade.php` from your selected theme's folder. Same goes for your assets.
 
-## Installation
+# Installation
 
 Edit your project's `composer.json` file to require:
 
@@ -40,7 +40,7 @@ Almost Done. You only need to publish configuration file to your application wit
 
 That's it. You are now ready to start theming your applications!
 
-## Defining themes
+# Defining themes
 
 Simple define your themes in the `themes` array in `config/themes.php`. The format for every theme is very simple:
 
@@ -67,13 +67,13 @@ Simple define your themes in the `themes` array in `config/themes.php`. The form
 ```
 all settings are optional and can be ommited. Check the example in the configuration file... If you are OK with the defaults then you don't even have to touch the configuration file. If a theme is not found then the default values will be used (Convention over configuration)
 
-## Extending themes
+# Extending themes
 
 You can set a theme to extend an other. When you are requesting a view/asset that doesn't exist in your active theme, then it will be resolved from it's parent theme. You can easily create variations of your theme by simply overiding your views/themes that are different. 
 
 All themes fall back to the default laravel folders if a resource is not found on the theme folders. So for example you can leave your common libraries (jquery/bootstrap ...) in your `public` folder and use them from all themes. No need to dublicate common assets for each theme!
 
-## Working with Themes
+# Working with Themes
 
 The default theme can be configured in the `theme.php` configuration file. Working with themes is very straightforward. Use:
 
@@ -98,7 +98,7 @@ class themeSelectServiceProvider extends ServiceProvider {
 ```
 ...or you can use a middleware to apply a theme to a `Route::group()` etc. For more advanced example check demo application: [Set Theme in Session](https://github.com/igaster/laravel-theme-demo) 
 
-## Building your views
+# Building your views
 
 Whenever you need the url of a local file (image/css/js etc) you can retrieve its path with:
 
@@ -120,7 +120,7 @@ Theme::css('file-name')
 Theme::img('src','alt', 'class-name')
 ```    
 
-## Assets Managment (Optional)
+# Assets Managment (Optional)
 
 This package provides intergration with [Orchestra/Asset](http://orchestraplatform.com/docs/3.0/components/asset) component. All the features are explained in the official documentation. If you don't need the extra functinality you can skip this section. Orchestra/Asset is NOT installed along with this package - you have to install it manualy.
 
@@ -147,7 +147,7 @@ Please note that you are just defining your css/js files but not actually dumpin
 
 exactly where you want write your declerations.
 
-## Assets dependencies
+# Assets dependencies
 
 This is an [Orchestra/Asset](http://orchestraplatform.com/docs/3.0/components/asset) feature explained well in the official documentation. Long story short:
 
@@ -159,6 +159,20 @@ and your assets dependencies will be auto resolved. Your assets will be exported
     @js  (jquery.js,    jq)
     @js  (bootstrap.js, bs, jq)
 
-## Important Note:
+# Important Note:
 
 Laravel is compiling your views every-time you make an edit. A compiled view will not recompile unless you make any edit to your view. Keep this in mind while you are developing themes...
+
+# FAQ:
+
+##### Is this package compatible with AWS?
+Yes with one exception: If you are building Theme hierarcies, asset's will not be looked up on the parent theme. Performing file searching on a remote repository is not the best practice. Should be addressed in a future version... However Blade templates auto-discovery works fine since they are local files.
+
+##### What about external assets (eg CDN)?
+Link directly to your external assets. Every url that starts with http(s) will not be proccesed by default.
+
+##### How do I change the public path?
+Rebind Laravel's 'path.public'. [(More info)](https://laracasts.com/discuss/channels/general-discussion/where-do-you-set-public-directory-laravel-5)
+
+##### I'm editing a view but I dont see the changes
+Laravel is compiling your views every-time you make an edit. A compiled view will not recompile unless you make any edit to your view. Keep this in mind while you are developing themes...
diff --git a/src/Theme.php b/src/Theme.php
@@ -5,10 +5,10 @@ class Theme extends Tree\Item {
     public $assetPath;
     public $viewsPath;
 
-    public function __construct($name, $assetPath = null, $viewsPath = null){
-        $this->name = $name;
-        $this->assetPath = $assetPath === null ? $name : $assetPath;
-        $this->viewsPath = $viewsPath === null ? $name : $viewsPath;
+    public function __construct($themeName, $assetPath = null, $viewsPath = null){
+        $this->name = $themeName;
+        $this->assetPath = $assetPath === null ? $themeName : $assetPath;
+        $this->viewsPath = $viewsPath === null ? $themeName : $viewsPath;
     }
 
     public function getParent(){
@@ -18,19 +18,34 @@ public function getParent(){
             return null;
     }
 
+
+    /**
+     * Attach theme paths to a local Url. The Url must be a resource located on the asset path
+     * of the current theme or it's parents. 
+     *
+     * @param  string $url
+     * @return string
+     */
     public function url($url){
+        // return external URLs unmodified
         if(preg_match('/^((http(s?):)?\/\/)/i',$url))
             return $url;
 
+        // Is it on AWS? Dont lookup parent themes...
+        if(preg_match('/^((http(s?):)?\/\/)/i',$this->assetPath))
+            return $this->assetPath.'/'.ltrim($url, '/');
+
+        // Lookup asset in current's theme asset path
         $fullUrl = (empty($this->assetPath) ? '' : '/').$this->assetPath.'/'.ltrim($url, '/');
 
         if (file_exists($fullPath = public_path($fullUrl)))
             return $fullUrl;
 
+        // If not found then lookup in parent's theme asset path
         if ($this->getParent())
             return $this->getParent()->url($url);
         
-        //Asset not found
+        // Asset not found at all. Error handling
         $action = \Config::get('themes.asset_not_found','LOG_ERROR');
 
         if ($action == 'THROW_EXCEPTION')
@@ -39,7 +54,13 @@ public function url($url){
             \Log::warning("Asset not found [$url] in Theme [".\Theme::get()."]");
     }
 
-    // get theme's configuration
+    /**
+     * Return the configuration value of $key for the current theme. Configuration values
+     * are stored per theme in themes.php config file. 
+     *
+     * @param  string $key
+     * @return mixed
+     */
     public function config($key){
         if (array_key_exists($key, $conf = \Config::get("themes.themes")[$this->name]))
             return $conf[$key];
@@ -51,72 +72,4 @@ public function config($key){
     }
 
 
-}
-
-
-// use Illuminate\Support\Facades\Config;
-
-// class Theme {
-// 	public $themeName;
-//     public $assetPath;
-//     public $viewsPath;
-//     public $parentTheme;
-
-//     public static $defaultViewsPath = '';
-
-//     /**
-//      *
-//      * @param string $themeName
-//      * @param array $options : ['assetPath' => xx, 'viewsPath' => xx, 'extends' => xx]
-//      *
-//      */
-//     public function __construct($themeName, $options = []){
-
-//         if (empty(static::$defaultViewsPath))
-//             static::$defaultViewsPath = Config::get('view.paths')[0];
-
-//         $defaults = [
-//             'asset-path'  => $themeName,
-//             'views-path'  => $themeName,
-//             'extends'     => '',
-//         ];
-
-//         $options = array_merge($defaults, $options);
-
-//         $this->themeName    = $themeName;
-//         $this->assetPath    = $options['asset-path'];
-//         $this->viewsPath    = $options['views-path'];
-//         $this->parentTheme  = Themes::get($options['extends']);
-//     }
-
-//     public function url($url){
-//         if(preg_match('/^((http(s?):)?\/\/)/i',$url))
-//             return $url;
-
-// 		$fullUrl = (empty($this->assetPath) ? '' : '/').$this->assetPath.'/'.ltrim($url, '/');
-
-//         if (!file_exists($fullPath = base_path('public').$fullUrl))
-//             if (empty($this->parentTheme))
-//                 throw new \Exception("$fullPath - not found");
-//             else
-//                 return $this->parentTheme->url($url);
-
-//         return $fullUrl;
-// 	}
-
-//     public function activate(){
-//         Config::set('view.paths', $this->pathsList_Views());
-//         Themes::set($this->themeName);
-// 	}
-
-// 	public function pathsList_Views(){
-// 		if (!empty($this->parentTheme))
-// 			$paths = $this->parentTheme->pathsList_Views();
-// 		else
-// 			$paths = [];
-
-//         array_unshift($paths,static::$defaultViewsPath.'/'.$this->viewsPath);
-// 		return $paths;
-// 	}
-
-// }
+}
diff --git a/src/Themes.php b/src/Themes.php
@@ -16,7 +16,13 @@ public function __construct(){
 		$this->root = new Theme('root','','');
     }
 
-	// Add a new theme to the Tree
+    /**
+     * Add a new theme to the hierarcy. Optionaly define a parent theme.
+     *
+     * @param   \igaster\laravelTheme\Theme $theme
+     * @param   string $parentName
+     * @return  \igaster\laravelTheme\Theme
+     */
 	public function add(Theme $theme, $parentName = ''){
 
 		if ($parentName)
@@ -28,21 +34,37 @@ public function add(Theme $theme, $parentName = ''){
 		return $theme;
 	}
 
-	// find a Theme (by name)
-    public function find($name){
-        return $this->root->searchChild(function($item) use($name){
-            if ($item->name == $name)
+    /**
+     * Find a Theme (by name)
+     *
+     * @param   string $themeName
+     * @return  \igaster\laravelTheme\Theme
+     */
+    public function find($themeName){
+        return $this->root->searchChild(function($item) use($themeName){
+            if ($item->name == $themeName)
                 return $item;
             else
                 return false;
         });
     }
 
+    /**
+     * Check if $themeName is a valid Theme
+     *
+     * @param   string $themeName
+     * @return  bool
+     */
     public function exists($themeName){
     	return ($this->find($themeName)!==false);
     }
 
-	// Set active theme (by name)
+    /**
+     * Set $themeName is the active Theme
+     *
+     * @param   string $themeName
+     * @return  void
+     */
 	public function set($themeName){
 		if (!Config::get('themes.enabled', true))
 			return;
@@ -73,33 +95,69 @@ public function set($themeName){
 		$themeViewFinder->setPaths($paths);
 	}
 
-	// get active theme (name)
+    /**
+     * Get  active's Theme Name
+     *
+     * @return  string
+     */
 	public function get(){
 		return $this->activeTheme ? $this->activeTheme->name : '';
 	}
 
-	// get current theme's configuration
+    /**
+     * Return current theme's configuration option for $key
+     *
+     * @param   string $key
+     * @return  mixed
+     */
 	public function config($key){
 		return $this->activeTheme->config($key);
 	}
 
+    /**
+     * Attach current theme's paths to a local Url. The Url must be a resource located on the asset path
+     * of the current theme or it's parents. 
+     *
+     * @param  string $url
+     * @return string
+     */
 	public function url($url){
 		if (Config::get('themes.enabled', true))
 			return $this->activeTheme->url($url);
 		else
 			return $url;
 	}
 
-	//	Helper Functions (for Blade files)
+	//---------------- Helper Functions (for Blade files) -------------------------
 
+    /**
+     * Return css link for $href
+     *
+     * @param  string $href
+     * @return string
+     */
 	public function css($href){
 		return '<link media="all" type="text/css" rel="stylesheet" href="'.$this->url($href).'">'."\n";
 	}
 
+    /**
+     * Return script link for $href
+     *
+     * @param  string $href
+     * @return string
+     */
 	public function js($href){
 		return '<script src="'.$this->url($href).'"></script>'."\n";
 	}
 
+    /**
+     * Return img tag
+     *
+     * @param  string $src
+     * @param  string $alt
+     * @param  string $Class
+     * @return string
+     */
 	public function img($src, $alt='', $Class=''){
 		return '<img src="'.$this->url($src).'" alt="'.$alt.'" class="'.$Class.'">'."\n";
 	}	
