Need clear deployment instructions for non-technical users
sympmarc opened this issue · comments
With the new AMD approach, deploying SPServices doesn't work quite the same as before. We need good, clear instructions for people who have no idea what "build" means. Something like http://spservices.codeplex.com/documentation#general-instructions
Marc,
For general (most) users, the instructions have not changed: they upload the dist/jquery.SPServices.min.js file and include it in their pages (btw: have you decided to keep both the dist and build folders?.
What I think you are tyring to put together is the instructions of how one would use SPServices if they wanted to take advantage of AMD - for example: through the use of RequireJS dependency manager.
Is that correct?
Yes, I think so. Ideally we'll have just one build? Or would you favor having an old-fashioned build and an AMD build? Last I tried dropping the current build into a page with a simple script reference, that didn't work, but I didn't try very hard.
Re: AMD Build
I don't think you need one... Its basically grabbing your src folder and uploading it... I guess you could also package it as a standalone folder inside the zip file... is that what you meant.
Re: Getting it working
I actually setup a working example of the use of AMD through the src/dev.aspx file... its default is to load SPServices via AMD. Take a look - starting at line 105: https://github.com/sympmarc/SPServices/blob/master/src/dev.aspx#L105
I'm just thinking of the old skool citizen developers who are used to dropping one file into a Document Library and referencing it with a <script> tag in a Content Editor Web Part. I don't think we want to make their lives harder with all this, even though we're heading in a very positive direction.
do you literally mean 1 file? because the built jquery.SPServices.js file already is AMD compliant... I was thinking about the Advanced user who may want fine control over which specific modules are loaded/used.
If you mean just general instructions on how to use the existing built file with AMD, then there is no build changes... Its just documenting the require.js setup to load it...
That. ;+) Advanced users wil get the AMD idea and want to use it. "Regular" users not so much. Though if we can just say something like do this:
var app = requirejs.config({
context: "SPServices",
baseUrl: "./",
urlArgs: '@BUILD',
paths: {
jquery : '//ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min'
},
shim: {}
});
app(["require", "jquery", "SPServices"], function(require, $){
done($);
});the maybe we have them covered.
close, but that will not work.. :) it will load the individual files from src/ folder... I think what you want is this (Warning: untested):
var app = requirejs.config({
context: "MyApp",
paths: {
jquery : '//ajax.googleapis.com/ajax/libs/jquery/1.11.3/jquery.min',
SPServices: '//cdnjs.cloudflare.com/ajax/libs/jquery.SPServices/2014.02/jquery.SPServices-2014.02.min.js'
},
shim: {
SPServices: ["jquery"]
}
});
app(["SPServices"], function($){
alert("SPServices Loaded! v" + $.SPServices.version());
});
What this is doing is creating a new RequireJS configuration that includes two named references: jquery and SPServices... It also sets a shim to tell RequireJS that SPServices is dependent on jquery, so that it knows to load jQuery first because SPServices is going to need it as a dependency.
The paths above could be replaced with local paths if the files were not coming from a CDN.
BTW: the dev.aspx file probably should have the shim as well... Else, it could fail if SPservices is loaded prior to jquery.