{"action":"created","issue":{"url":"https://api.github.com/repos/e107inc/e107/issues/1725","repository_url":"https://api.github.com/repos/e107inc/e107","labels_url":"https://api.github.com/repos/e107inc/e107/issues/1725/labels{/name}","comments_url":"https://api.github.com/repos/e107inc/e107/issues/1725/comments","events_url":"https://api.github.com/repos/e107inc/e107/issues/1725/events","html_url":"https://github.com/e107inc/e107/issues/1725","id":161441468,"number":1725,"title":"[documentation] - Library Manager","user":{"login":"lonalore","id":6043821,"avatar_url":"https://avatars3.githubusercontent.com/u/6043821?v=4","gravatar_id":"","url":"https://api.github.com/users/lonalore","html_url":"https://github.com/lonalore","followers_url":"https://api.github.com/users/lonalore/followers","following_url":"https://api.github.com/users/lonalore/following{/other_user}","gists_url":"https://api.github.com/users/lonalore/gists{/gist_id}","starred_url":"https://api.github.com/users/lonalore/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lonalore/subscriptions","organizations_url":"https://api.github.com/users/lonalore/orgs","repos_url":"https://api.github.com/users/lonalore/repos","events_url":"https://api.github.com/users/lonalore/events{/privacy}","received_events_url":"https://api.github.com/users/lonalore/received_events","type":"User","site_admin":false},"labels":[{"id":124917167,"url":"https://api.github.com/repos/e107inc/e107/labels/documentation","name":"documentation","color":"c7def8","default":false}],"state":"open","locked":false,"assignee":{"login":"Moc","id":577978,"avatar_url":"https://avatars1.githubusercontent.com/u/577978?v=4","gravatar_id":"","url":"https://api.github.com/users/Moc","html_url":"https://github.com/Moc","followers_url":"https://api.github.com/users/Moc/followers","following_url":"https://api.github.com/users/Moc/following{/other_user}","gists_url":"https://api.github.com/users/Moc/gists{/gist_id}","starred_url":"https://api.github.com/users/Moc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Moc/subscriptions","organizations_url":"https://api.github.com/users/Moc/orgs","repos_url":"https://api.github.com/users/Moc/repos","events_url":"https://api.github.com/users/Moc/events{/privacy}","received_events_url":"https://api.github.com/users/Moc/received_events","type":"User","site_admin":false},"assignees":[{"login":"Moc","id":577978,"avatar_url":"https://avatars1.githubusercontent.com/u/577978?v=4","gravatar_id":"","url":"https://api.github.com/users/Moc","html_url":"https://github.com/Moc","followers_url":"https://api.github.com/users/Moc/followers","following_url":"https://api.github.com/users/Moc/following{/other_user}","gists_url":"https://api.github.com/users/Moc/gists{/gist_id}","starred_url":"https://api.github.com/users/Moc/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/Moc/subscriptions","organizations_url":"https://api.github.com/users/Moc/orgs","repos_url":"https://api.github.com/users/Moc/repos","events_url":"https://api.github.com/users/Moc/events{/privacy}","received_events_url":"https://api.github.com/users/Moc/received_events","type":"User","site_admin":false}],"milestone":null,"comments":5,"created_at":"2016-06-21T13:47:47Z","updated_at":"2017-09-26T07:24:01Z","closed_at":null,"author_association":"CONTRIBUTOR","body":"## Installing an external library that is required by a contributed plugin\r\n- **Download the library** - The plugin that requires the external library should provide a link to the homepage of that library or, even better, directly to that library's download page. Sometimes the plugin will specify a version for you to download, otherwise just download the latest version.\r\n- **Extract the files** - If the file you downloaded is an archive, i.e. its file extension is .zip or .tar.gz, you will need to extract it first. On Windows, use a program like [7-zip](http://www.7-zip.org/) to extract it. On the Mac, you can use [Stuffit Expander](http://my.smithmicro.com/stuffit-expander-mac.html). For *nix systems, use the command line: `tar -zxvf filename.tar.gz`. After extracting the file, you should see multiple files or a single folder with the library's name.\r\n- **Upload the library** - Inside the `e107_web/lib/` directory create a new directory with the e107 machine name of the library. The machine name should be provided by the plugin that requires it, sometimes implicitly as in \"Install the `foo` library!\" (in that case the machine name would be `foo`). Upload the library files into the directory you have just created. If the library consists of a directory, which you have just extracted, upload the entire directory into the `e107_web/lib/machine_name` directory.\r\n- **Install the other plugin** - Now you should be able to install the plugin that requires the external library.\r\n## The ideas and design behind Library Manager\r\n#### External libraries should not be committed to the source code of plugin/theme\r\n##### Reasoning\r\n- Policy conflicts.\r\n- Plugins and themes and their release cycles should not be affected by the release cycles of external libraries.\r\n##### Effect\r\n\r\nLibraries need to be obtained separately from e107 plugins and themes. For now this has to be done manually.\r\n#### Libraries should not reside in plugin folders\r\n##### Reasoning\r\n- Best practices for plugin upgrades dictate to delete the old plugin folder before the upgrade. This removes any libraries inside of that folder.\r\n- Multiple plugins can implement the same library.\r\n##### Effect\r\n\r\nThe best practice is to place libraries into a `e107_web/lib` directory.\r\n#### Library Manager needs to be able to detect a library's version\r\n##### Reasoning\r\n\r\nRelease cycles of e107 plugins and themes can be different than the release cycles of external libraries.\r\n##### Effect\r\n\r\nLibrary Manager supports version detection of libraries and provides a library's version information to plugins. Plugins implementing libraries can provide version-specific integration code or at least bail out in case of incompatible versions.\r\n\r\nThe current code flow is:\r\n\r\n``` php\r\n<?php\r\n$library = e107::library('detect', 'example_library');\r\n$version = $library['version'];\r\n?>\r\n```\r\n#### Only one version of a library can be installed per site\r\n##### Reasoning\r\n\r\nIf two different versions of the same library are installed, there is no way to guarantee that they will not both be loaded on the same page. If that were the case, visual errors could appear in case of CSS libraries, functional errors in case of JavaScript libraries and fatal errors in case of PHP libraries.\r\n#### Library Manager needs meta information about libraries\r\n- A specific \"machine name\" for plugins to reference the library by.\r\n- Name, Website and Download link for the Library Manager's user interface.\r\n- Information how to detect the version of the library (see above)\r\n- Files that belong to this library. Note that since this information can vary between library versions. Also some libraries come with different 'variants'. For example a 'source code variant' and a 'minified variant'. Or TinyMCE, for instance, comes with a special 'jQuery-based variant'.\r\n- Plugin's and theme's integration files to load alongside the library.\r\n- Library dependencies.\r\n\r\n**See the API documentation** for `config()` method in `e107_plugins/_blank/e_library.php` file for a detailed explanation of the information currently needed.\r\n\r\nThere are currently two ways to declare this information:\r\n- Implementing your own class with `config()` method in a plugin with `e_library.php` file\r\n- Implementing your own class with `config()` method in a theme with `theme_library.php` file\r\n## Using Library Manager (as a plugin-developer)\r\n##### Declaration\r\n\r\nLibrary Manager includes a library registry, so if you want to use an external library in your plugin, you need to make it known first. You can do this by implementing `config()` method in `e_library.php` file of your plugin for your library, which users then have to download.\r\n##### Using `e_library.php` file and implementing `config()` method\r\n\r\n``` php\r\n<?php\r\n/**\r\n * @file\r\n * Provides information about external libraries.\r\n */\r\n\r\n/**\r\n * Class PLUGIN_library.\r\n */\r\nclass PLUGIN_library\r\n{\r\n\r\n    /**\r\n     * Return information about external libraries.\r\n     */\r\n    function config()\r\n    {\r\n        // A very simple library. No changing APIs (hence, no versions), no variants. \r\n        // Expected to be extracted into 'e107_web/lib/simple'.\r\n        $libraries['simple'] = array(\r\n            'name'              => 'Simple library',\r\n            'vendor_url'        => 'http://example.com/simple',\r\n            'download_url'      => 'http://example.com/simple',\r\n            'version_arguments' => array(\r\n                'file'    => 'readme.txt',\r\n                // Best practice: Document the actual version strings for later reference.\r\n                // 1.x: Version 1.0\r\n                'pattern' => '/Version (\\d+)/',\r\n                'lines'   => 5,\r\n            ),\r\n            'files'             => array(\r\n                'js'  => array(\r\n                    'simple.js',\r\n                ),\r\n                'css' => array(\r\n                    'simple.css',\r\n                ),\r\n            ),\r\n        );\r\n\r\n        return $libraries;\r\n    }\r\n\r\n}\r\n```\r\n##### Version detection\r\n\r\nVersion detection is using regular expressions. If you'd like to bypass the version detection regex you can replace the `version_arguments` array with a callback as demonstrated below:\r\n\r\n``` php\r\n<?php\r\n/**\r\n * @file\r\n * Provides information about external libraries.\r\n */\r\n\r\n/**\r\n * Class PLUGIN_library.\r\n */\r\nclass PLUGIN_library\r\n{\r\n\r\n    /**\r\n     * Return information about external libraries.\r\n     */\r\n    function config()\r\n    {\r\n        // A very simple library. No changing APIs (hence, no versions), no variants. \r\n        // Expected to be extracted into 'e107_web/lib/simple'.\r\n        $libraries['simple'] = array(\r\n            'name'              => 'Simple library',\r\n            'vendor_url'        => 'http://example.com/simple',\r\n            'download_url'      => 'http://example.com/simple',\r\n            'version callback' => 'simple_version_callback',\r\n            'files'             => array(\r\n                'js'  => array(\r\n                    'simple.js',\r\n                ),\r\n                'css' => array(\r\n                    'simple.css',\r\n                ),\r\n            ),\r\n        );\r\n\r\n        return $libraries;\r\n    }\r\n\r\n    function simple_version_callback() {\r\n        // Use some fancy magic to get the version number... or don't.\r\n        return TRUE;\r\n    }\r\n\r\n}\r\n```\r\n##### Loading\r\n\r\nTo load the library from inside your plugin (i.e in your `e_header.php` file), simply do:\r\n\r\n``` php\r\n<?php\r\ne107::library('load', $name);\r\n?>\r\n```\r\n\r\nUsually, you'll want to do something after the library has been loaded. Because you cannot always depend on the library being installed you have to check first if the loading was actually successful:\r\n\r\n``` php\r\n<?php\r\n// Try to load the library and check if that worked.\r\nif (($library = e107::library('load', $name)) && !empty($library['loaded'])) {\r\n    // Do something with the library here.\r\n}\r\n?>\r\n```\r\n##### Detection\r\n\r\nIf you just want to check whether the library is installed, but don't want to load it right away, you can use:\r\n\r\n``` php\r\n<?php\r\n$library = e107::library('detect', $name);\r\n?>\r\n```\r\n\r\nSimilar to checking whether the library was loaded above, we can then check if the library is installed:\r\n\r\n``` php\r\n<?php\r\nif (($library = e107::library('detect', $name)) && !empty($library['installed'])) {\r\n    // The library is installed. Awesome!\r\n}\r\nelse\r\n{\r\n    // Something went wrong. :(\r\n    // This contains a short status code of what went wrong, such as 'not found'.\r\n    $error = $library['error'];\r\n    // This contains a detailed error message.\r\n    $error_message = $library['error_message'];\r\n}\r\n?>\r\n```\r\n\r\n## Using Newer Versions of jQuery in e107\r\n\r\nYou will often need a newer version of jQuery to use a certain jQuery plugin. There are two ways to achieve this.\r\n\r\n#### Method 1: Using `theme_library.php` addon file in your **theme** folder\r\n\r\n```php\r\n<?php\r\n\r\n/**\r\n * @file\r\n * Provides information about external libraries.\r\n */\r\n\r\n\r\n/**\r\n * Class theme_library.\r\n */\r\nclass theme_library\r\n{\r\n\r\n\t/**\r\n\t * Provides information about external libraries.\r\n\t */\r\n\tfunction config()\r\n\t{\r\n\t\treturn array();\r\n\t}\r\n\r\n\t/**\r\n\t * Alters library information before detection and caching takes place.\r\n\t */\r\n\tfunction config_alter(&$libraries)\r\n\t{\r\n\t\t// Override CDN library path. Make sure, CDN path is correct.\r\n\t\t$libraries['cdn.jquery']['path'] = '3.1.1';\r\n\t\t\r\n\t\t// Override local library path. Make sure, you have downloaded the files\r\n\t\t// to 'e107_web/lib/jquery/3.1.1' folder with the same folder structure\r\n\t\t// than 'e107_web/lib/jquery/2.2.4'.\r\n\t\t$libraries['jquery']['path'] = '3.1.1';\r\n\t}\r\n\r\n}\r\n\r\n```\r\n\r\n#### Method 2: Using `e_library.php` addon file in your **plugin** folder\r\n\r\n```php\r\n<?php\r\n\r\n/**\r\n * @file\r\n * Provides information about external libraries.\r\n */\r\n\r\n\r\n/**\r\n * Class PLUGIN_NAME_library.\r\n */\r\nclass PLUGIN_NAME_library\r\n{\r\n\r\n\t/**\r\n\t * Provides information about external libraries.\r\n\t */\r\n\tfunction config()\r\n\t{\r\n\t\treturn array();\r\n\t}\r\n\r\n\t/**\r\n\t * Alters library information before detection and caching takes place.\r\n\t */\r\n\tfunction config_alter(&$libraries)\r\n\t{\r\n\t\t// Override CDN library path. Make sure, CDN path is correct.\r\n\t\t$libraries['cdn.jquery']['path'] = '3.1.1';\r\n\t\t\r\n\t\t// Override local library path. Make sure, you have downloaded the files\r\n\t\t// to 'e107_web/lib/jquery/3.1.1' folder with the same folder structure\r\n\t\t// than 'e107_web/lib/jquery/2.2.4'.\r\n\t\t$libraries['jquery']['path'] = '3.1.1';\r\n\t}\r\n\r\n}\r\n\r\n```\r\n\r\nFinally, visit **Admin UI / Preferences / Libraries** page, and check your jQuery libraries.\r\n"},"comment":{"url":"https://api.github.com/repos/e107inc/e107/issues/comments/332109894","html_url":"https://github.com/e107inc/e107/issues/1725#issuecomment-332109894","issue_url":"https://api.github.com/repos/e107inc/e107/issues/1725","id":332109894,"user":{"login":"lonalore","id":6043821,"avatar_url":"https://avatars3.githubusercontent.com/u/6043821?v=4","gravatar_id":"","url":"https://api.github.com/users/lonalore","html_url":"https://github.com/lonalore","followers_url":"https://api.github.com/users/lonalore/followers","following_url":"https://api.github.com/users/lonalore/following{/other_user}","gists_url":"https://api.github.com/users/lonalore/gists{/gist_id}","starred_url":"https://api.github.com/users/lonalore/starred{/owner}{/repo}","subscriptions_url":"https://api.github.com/users/lonalore/subscriptions","organizations_url":"https://api.github.com/users/lonalore/orgs","repos_url":"https://api.github.com/users/lonalore/repos","events_url":"https://api.github.com/users/lonalore/events{/privacy}","received_events_url":"https://api.github.com/users/lonalore/received_events","type":"User","site_admin":false},"created_at":"2017-09-26T07:24:00Z","updated_at":"2017-09-26T07:24:00Z","author_association":"CONTRIBUTOR","body":"@CaMer0n It's a good idea, if I have time I will look into that plugin manager class to see how it works.\r\n\r\n@Jimmi08 e107 uses BS3 plugins, especially on the forms, e.g. BS3 Datepicker, Selectize.js with BS3 theme (autocomplete fields), and e107 renders HTML output based on BS3 standards. So I don't think you can use BS4 for your theme (without having to overwrite core functions).\r\n@CaMer0n I was just wondering what do you think about a \"v3.0.0\" branch in this repo, for preparing e107 core for BS4 standards? We could also drop old BC codes from the core."}}
{"actor":{"display_login":"lonalore"}}