-
-
Notifications
You must be signed in to change notification settings - Fork 106
Add default options argument to sidebar documentation #19
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Conversation
@Smankusors hopefully this is the right place to make this change? |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
looks fine for me.
well... actually... I just looked the documentation.... And it's not just sidenav
... collapsible
, dropdown
... uh oh, literally every JS component have this doc problem 😰
gosh indeed - I think I've corrected it where I could find it (i searched for |
See also #1 |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Think you missed collapsible, see my list at #1
This fix is fine, it does the main job of removing the error. This is fix #2 from my suggestions, whereas I was edging towards fix #1 - removing options rather than declaring it - as I do think that declaring raises other questions. For instance, what we will essentially see as a new user is this:
document.addEventListener('DOMContentLoaded', function() {
var elems = document.querySelectorAll('select');
var options = {};
var instances = M.FormSelect.init(elems, options);
});
// Or with jQuery
$(document).ready(function(){
$('select').formSelect();
});
That is - the jQuery init has no reference to options.
Do we need to declare options again in the jQuery init? Should we bother declaring options at all? It is unnecessary, seeing as we can simply set our options with an object var instances = M.FormSelect.init(elems,{});
Further notes - the docs confusingly use instances
as well as instance
- this can easily trip people up. There's is no need to declare instance
when we can just use instances[0]
, and also, a much cleaner init when you don't need to get the instance is to not even declare it at all:
M.FormSelect.init(document.querySelectorAll('select'))
This single line replaces three lines where there are not options to set:
var elems = document.querySelectorAll('select');
var options = {};
var instances = M.FormSelect.init(elems, options);
And a further thought, is how useful it is to keep redeclaring the same variable over and over, instances
and elems
...
Hmm I see what you're trying to say. Would it be worth mentioning these caveats in a single reference page somewhere, but still ensuring the documentation runs without errors on copy-paste? I don't mind most of your options, I just dislike
Since as a user I wouldn't have a clue what the second argument was or why it was there. |
Also I haven't looked too hard, but how should options be specified for jQuery? |
Like this:
Shown here with the Modal component, |
Strong yes to a standalone page explaining the inits, how to use use them, what options are, how they differ from methods etc. Basic theory such as: Each component has a set of default options that it is initialised with. For instance, initialising
...is the same as writing:
..where options is an object In addition, it would be good to talk about multiple components on the same page - 2 modals with different options. How to approach this. It's not immediately obvious to beginner that
To get the instance, and if there were two on the page, Sorry, I waffle but I use Materialize so much and run into these things all the time, fo me it is easy to use but I remember at the start that the docs were not helpful. Bottom line - your solution works, but we have left the jQuery explanation a little short (and inconsistent). |
How can we solve this in the best way? Any ideas / proposed solutions? |
As you can probably tell, I'm rather new to materialise (and web dev generally) and thus am probably not the best person to write up all these details. I can transcribe most of what has been mentioned in the thread (into a new page called 'working with JS objects' or similar, or editing 'auto init') if it could help more knowledgeable people also add details. Not sure how that works with a PR though - would you need to be collaborators on my GitHub fork? Or can you also submit updates to the same PR? |
I think we can do something like this instead (adding comment "Options here"), for example in the collapsible documentation
with this, the new user will know where to put the options... Now.... if they don't know how to write options argument............ then..... 🙊 |
This sounds good - it answers both the options error and jQuery question. Perhaps underneath the jQuery script - on every component page - we have a link: 'For more details on using options, see And this would link to a new page that we create, with a broader explanation of options and how they are used (which links back to @dev10110's earlier post) @dev10110 what do you think about this over declaring options method? |
Maybe we can use a partial which is included so we have to write the text only once: Let me know if you need any help with this. Regarding push / write access for others, there is a checkbox in the PR settings to allow that others can push to your fork branch. I do not see if this is checked / activated by you. |
Yes - good thinking. DNR! Obviously we will need to create the page first, and the content, which may take a bit of back and forth, so for this PR we could just fix the issue and treat the new page as a separate concern. |
Alright sounds good. Ill make an update to the jQuery part of the docs in this PR, and open a new one for the extra text on options. I did see and tick the checkbox and so that's awesome. Thanks guys! |
@DanielRuf seems like ill need a hand getting the page working - as far as I can tell, the documentation right now is compiled using jade, but the main content is included as a html file. I don't see how to produce and reuse a block of text within the html files. |
also, jquery updates done! |
What is the current status of this PR? |
From my POV: this is ready to go. For the extra documentation on how init works, I tried it, but couldnt figure out how to use the same snippet in multiple places using Jade. #19 (comment) |
@Smankusors what do you think? Can it be merged? |
hmm the that example can be copy from jquery to non jquery, but IMO it looks too long compared to other component documentations. perhaps in the future we should have tab to select non jquery version and jquery version though. 💭 for the multiple |
Ah yes indeed. That would be much appreciated @Smankusors |
Feel free to do so @Smankusors. |
merge all $(document).ready to one
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
alright I think it's done 🙂
Congrats on your first merged PR @dev10110. I've sent you an invitation to this org and the members group. |
Woohoo thanks Daniel, Anthony! |
Proposed changes
It took me an (embarrassingly long) while to realise that the lack of
var options= {}
was the reason my sidebar wasn't working. Hopefully, this documentation update can help someone going forward.Types of changes
Checklist: