From 5cace7c693640cd10e6a05aaea64fbbc91f8623d Mon Sep 17 00:00:00 2001 From: Ingo Schommer Date: Fri, 27 May 2016 13:08:22 +1200 Subject: [PATCH] Fixed javascript/ docs references (#5599) * More pointers to new build tooling docs in upgrading guide * Fixed docs references to moved files We don't want to mandate every module to switch from javascript/ to client/src, but at the same time shouldn't reference non-existant files and confuse newcomers that way. * More pointers to new React docs --- .../01_Templates/03_Requirements.md | 41 +++++++++-------- .../Field_types/03_HTMLEditorField.md | 44 ++----------------- .../03_Forms/Field_types/05_UploadField.md | 6 +-- .../03_Forms/Field_types/06_AssetField.md | 6 +-- .../02_CMS_Architecture.md | 4 +- docs/en/04_Changelogs/4.0.0.md | 6 ++- 6 files changed, 36 insertions(+), 71 deletions(-) diff --git a/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md b/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md index 9849e07f8..5fccbdc7b 100644 --- a/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md +++ b/docs/en/02_Developer_Guides/01_Templates/03_Requirements.md @@ -7,14 +7,18 @@ The requirements class takes care of including CSS and JavaScript into your appl coding any references in the `` tag of your template, as it enables a more flexible handling through the [api:Requirements] class. +The examples below are using certain folder naming conventions (CSS files in `css/`, JavaScript files in `javascript/`). +SilverStripe core modules like `cms` use a different naming convention (CSS and JavaScript files in `client/src/`). +The `Requirements` class can work with arbitrary file paths. + ## Template Requirements API -**mysite/templates/Page.ss** +**/templates/SomeTemplate.ss** :::ss - <% require css("cms/css/TreeSelector.css") %> - <% require themedCSS("TreeSelector") %> - <% require javascript("cms/javascript/LeftAndMain.js") %> + <% require css("/css/some_file.css") %> + <% require themedCSS("some_themed_file") %> + <% require javascript("/javascript/some_file.js") %>
Requiring assets from the template is restricted compared to the PHP API. @@ -33,8 +37,8 @@ as close to rendering as possible (e.g. in [api:FormField]). public function init() { parent::init(); - Requirements::javascript("cms/javascript/LeftAndMain.js"); - Requirements::css("cms/css/TreeSelector.css"); + Requirements::javascript("/javascript/some_file.js"); + Requirements::css("/css/some_file.css"); } } @@ -47,7 +51,7 @@ If you're using the CSS method a second argument can be used. This argument defi `` element, so you can define 'screen' or 'print' for example. :::php - Requirements::css("cms/css/TreeSelector.css", "screen,projection"); + Requirements::css("/css/some_file.css", "screen,projection"); ### Javascript Files @@ -59,12 +63,12 @@ JavaScript in a separate file and instead load, via search and replace, several :::php $vars = array( - "EditorCSS" => "cms/css/editor.css", + "MemberID" => Member::currentUserID(), ); - Requirements::javascriptTemplate("cms/javascript/editor.template.js", $vars); + Requirements::javascriptTemplate("/javascript/some_file.js", $vars); -In this example, `editor.template.js` is expected to contain a replaceable variable expressed as `$EditorCSS`. +In this example, `some_file.js` is expected to contain a replaceable variable expressed as `MemberID`. If you are using front-end script combination mechanisms, you can optionally declare that your included files provide these scripts. This will ensure that subsequent @@ -73,12 +77,12 @@ files. :::php - Requirements::javascript('mysite/js/dist/bundle.js', ['provides' => [ - 'mysite/js/jquery.js' - 'mysite/js/src/main.js', - 'mysite/js/src/functions.js' + Requirements::javascript('/javascript/dist/bundle.js', ['provides' => [ + '/javascript/jquery.js' + '/javascript/src/main.js', + '/javascript/src/functions.js' ]]); - Requirements::javascript('mysite/js/jquery.js'); // Will will skip this file + Requirements::javascript('/javascript/jquery.js'); // Will will skip this file ### Custom Inline CSS or Javascript @@ -110,8 +114,8 @@ by reducing HTTP requests. Requirements::combine_files( 'foobar.js', array( - 'mysite/javascript/foo.js', - 'mysite/javascript/bar.js', + '/javascript/foo.js', + '/javascript/bar.js', ) ); @@ -275,4 +279,5 @@ If the Javascript files are preferred to be placed in the `` tag rather th ## API Documentation -* [api:Requirements] + * [api:Requirements] + * [CMS Architecture and Build Tooling](/developer_guides/customising_the_admin_interface/cms_architecture) \ No newline at end of file diff --git a/docs/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md b/docs/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md index 68c40e99a..815340938 100644 --- a/docs/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md +++ b/docs/en/02_Developer_Guides/03_Forms/Field_types/03_HTMLEditorField.md @@ -144,52 +144,14 @@ The default setting for the CMS's `extended_valid_elements` we are overriding he ## Writing custom plugins -It is also possible to add custom buttons to TinyMCE. A simple example of this is SilverStripe's `ssmacron` plugin. The -source can be found in the Framework's `thirdparty/tinymce_ssmacron` directory. - -Here is how we can create a project-specific plugin. Create a `mysite/javascript/myplugin` directory, add the plugin -button icon - here `myplugin.png` - and the source code - here `editor_plugin.js`. Here is a very simple example of a -plugin that adds a button to the editor: - - :::js - (function() { - tinymce.create('tinymce.plugins.myplugin', { - - init : function(ed, url) { - var self = this; - - ed.addButton ('myplugin', { - 'title' : 'My plugin', - 'image' : url+'/myplugin.png', - 'onclick' : function () { - alert('Congratulations! Your plugin works!'); - } - }); - - }, - - getInfo : function() { - return { - longname : 'myplugin', - author : 'Me', - authorurl : 'http://me.org.nz/', - infourl : 'http://me.org.nz/myplugin/', - version : "1.0" - }; - } - }); - - tinymce.PluginManager.add('myplugin', tinymce.plugins.myplugin); - })(); - -You can then enable this plugin through the [api:HtmlEditorConfig::enablePlugins()]: +It is also possible to add custom plugins to TinyMCE, for example toolbar buttons. +You can enable them through [api:HtmlEditorConfig::enablePlugins()]: **mysite/_config.php** :::php HtmlEditorConfig::get('cms')->enablePlugins(array('myplugin' => '../../../mysite/javascript/myplugin/editor_plugin.js')); -For more complex examples see the [Creating a Plugin](http://www.tinymce.com/wiki.php/Creating_a_plugin) in TinyMCE -documentation, or browse through plugins that come with the Framework at `thirdparty/tinymce/plugins`. +You can learn how to [create a plugin](http://www.tinymce.com/wiki.php/Creating_a_plugin) from the TinyMCE documentation. ## Image and media insertion diff --git a/docs/en/02_Developer_Guides/03_Forms/Field_types/05_UploadField.md b/docs/en/02_Developer_Guides/03_Forms/Field_types/05_UploadField.md index f895c21bf..0c7214f68 100644 --- a/docs/en/02_Developer_Guides/03_Forms/Field_types/05_UploadField.md +++ b/docs/en/02_Developer_Guides/03_Forms/Field_types/05_UploadField.md @@ -355,8 +355,7 @@ In a similar fashion you can use 'setFileEditActions' to set the actions for the String values are interpreted as permission codes. * `setCanUpload`: (boolean|string) Can the user upload new files, or just select from existing files. String values are interpreted as permission codes. - * `setDownloadTemplateName`: (string) javascript template used to display already uploaded files, see - javascript/UploadField_downloadtemplate.js. + * `setDownloadTemplateName`: (string) javascript template used to display already uploaded files. * `setFileEditFields`: (FieldList|string) FieldList $fields or string $name (of a method on File to provide a fields) for the EditForm (Example: 'getCMSFields'). * `setFileEditActions`: (FieldList|string) FieldList $actions or string $name (of a method on File to @@ -368,8 +367,7 @@ In a similar fashion you can use 'setFileEditActions' to set the actions for the * `setPreviewMaxHeight`: (int). * `setTemplateFileButtons`: (string) Template name to use for the file buttons. * `setTemplateFileEdit`: (string) Template name to use for the file edit form. - * `setUploadTemplateName`: (string) javascript template used to display uploading files, see - javascript/UploadField_uploadtemplate.js. + * `setUploadTemplateName`: (string) javascript template used to display uploading files. * `setCanPreviewFolder`: (boolean|string) Is the upload folder visible to uploading users? String values are interpreted as permission codes. diff --git a/docs/en/02_Developer_Guides/03_Forms/Field_types/06_AssetField.md b/docs/en/02_Developer_Guides/03_Forms/Field_types/06_AssetField.md index e479a8fc9..4ef6c2495 100644 --- a/docs/en/02_Developer_Guides/03_Forms/Field_types/06_AssetField.md +++ b/docs/en/02_Developer_Guides/03_Forms/Field_types/06_AssetField.md @@ -214,12 +214,10 @@ If the AssetField doesn't save into a relation, there's technically no saveable String values are interpreted as permission codes. * `setCanUpload`: (boolean|string) Can the user upload new files, or just select from existing files. String values are interpreted as permission codes. - * `setDownloadTemplateName`: (string) javascript template used to display already uploaded files, see - javascript/UploadField_downloadtemplate.js. + * `setDownloadTemplateName`: (string) javascript template used to display already uploaded files. * `setPreviewMaxWidth`: (int). * `setPreviewMaxHeight`: (int). * `setTemplateFileButtons`: (string) Template name to use for the file buttons. - * `setUploadTemplateName`: (string) javascript template used to display uploading files, see - javascript/UploadField_uploadtemplate.js. + * `setUploadTemplateName`: (string) javascript template used to display uploading files. * `setCanPreviewFolder`: (boolean|string) Is the upload folder visible to uploading users? String values are interpreted as permission codes. diff --git a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md index 100e55e4e..5e5e39dcf 100644 --- a/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md +++ b/docs/en/02_Developer_Guides/15_Customising_the_Admin_Interface/02_CMS_Architecture.md @@ -1,4 +1,4 @@ -# CMS architecture +# CMS Architecture ## Introduction @@ -13,7 +13,7 @@ feel familiar to you. This is just a quick run down to get you started with some special conventions. For a more practical-oriented approach to CMS customizations, refer to the -[Howto: Extend the CMS Interface](/developer_guides/customising_the_admin_interface/how_tos/extend_cms_interface) which builds +[Howto: Extend the CMS Interface](/developer_guides/customising_the_admin_interface/how_tos/extend_cms_interface). ## Installation diff --git a/docs/en/04_Changelogs/4.0.0.md b/docs/en/04_Changelogs/4.0.0.md index 5721084e9..f374becd0 100644 --- a/docs/en/04_Changelogs/4.0.0.md +++ b/docs/en/04_Changelogs/4.0.0.md @@ -101,8 +101,10 @@ * Bundling of core JavaScript via [Browserify](http://browserify.org/) * CMS build tasks managed by [Gulp](http://gulpjs.com/) -For more details see the docs on [working with client-side dependencies](../contributing/code#working-with-client-side-dependencies). Note that you don't need any of these tools for running SilverStripe -or developing your own website. These improvements are mainly geared at CMS core development. +If you're planning to contribute to SilverStripe core, +you should learn how to [use the build tooling](/developer_guides/customising_the_admin_interface/cms_architecture) +and [work with client-side dependencies](../contributing/code#working-with-client-side-dependencies). +Note that you don't need any of these tools for running SilverStripe or developing your own website. ### Added new front-end UI libraries